Refactor / update Awair integration (#34394)
* Refactor / update Awair integration
This commit does a few things, all in service of making the Awair
integration more modern and reliable. Specifically we do the following:
- Update to python_awair 0.1.1
- Begin using config entries / flow for setting up the integration.
- YAML support is completely removed.
- The integration now allows adding multiple Awair accounts, should a
user wish to do so (I found it _very_ useful in development).
- Group various Awair sensors into devices, using the device registry.
- Renames various sensors and treats the "dust" sensor as a particulate sensor.
- Device update rate-limits are no longer dynamically calculated; the
Awair API now separates rate-limits on a per-device basis.
- Supports sound pressure and illuminance sensors found on some Awair devices.
- We report the "awair index" for certain sensors as part of device_state_attributes.
The "index" is a subjective measure of whether or not a sensor reading
is "good" or "bad" (and to what extent). It's a component of the Awair
score, and it is useful on its own as an input for those who wish to
do things like "display this color if the value is 'bad'".
This is a breaking change, and requires updates to documentation and a
warning in the README. The breaking changes in detail, are:
- Support for all YAML configuration is removed, and users will need to
re-add the integration via the UI.
- We no longer support overriding device discovery via manual
configuration of device UUIDs. This was previously supported because
the Awair API had severe limits on the device list endpoints; however
those have since been removed.
- Gen 1 devices no longer show a "dust" sensor; rather we create a PM2.5
sensor and a PM10 sensor and just keep the values in sync. This better
reflects the sensor capabilities: it can detect particles in a range
from 2.5 -> 10, but cannot differentiate between sizes.
- Sensors are renamed as follows:
- "sensor.devicename_co2" -> "sensor.devicename_carbon_dioxide"
- "sensor.devicename_voc" -> "sensor.devicename_volatile_organic_compounds"
- "sensor.devicename_score" -> "sensor.devicename_air_quality_index"
- I've chosen to call the "Awair Score" an "air quality index" sensor,
because fundamentally the "Awair Score" and other air quality indices
(such as CAQI) do the same thing: they calculate a value based on a
variety of other inputs.
Under the hood, the integration has seen some improvements:
- We use the DataUpdateCoordinator class to handle updates, rather than
rolling our own update class.
- The code no longer tracks availability based on a timestamp returned
from the Awair service; we assert that if we have received a response
and the response has data for our device, then we are available (and
otherwise, not available). We don't need to test the actual Awair API
so heavily.
- Test coverage has been expanded to handle a variety of products that
Awair produces, not just the one I happen to own.
- Test coverage no longer concerns itself with testing behavior that is
now handled by the DataUpdateCoordinator; nor is it concerned with
ensuring that the overall component sets up and registers properly.
These are assumed to be well-tested functionaity of the core and not
things we need to re-test ourselves.
Finally - between library updates and integration updates, this
integration is well-positioned to support future updates. I have a
proof-of-concept patch for device automations, and the underlying
library now supports subclassing authentication (which clears the way
for us to use OAuth authentication for Awair).
* Wrap test fixture in mock_coro
Truthfully I'm not sure why this was passing on my local dev
environment, but I was developing with python 3.8 before. After
installing python 3.7, I was able to reproduce the CI failures and fix
them.
* Fix broken tests after #34901 and/or #34989
* Do not rename sensors so broadly
We're going to keep the sensors named as they were before, pending the
outcome of any decisions around the air_quality component and what names
should be standardized for air-quality-like devices.
If standardized names are selected (which does seem likely), then we
will update this integration to match them - at which point, it would be
a breaking change.
But for now, we'll keep names mostly identical to what users had before.
Notable in this commit is that we generate the entity_id ourselves,
rather than just allowing it to be auto-generated from the name
attribute. This allows us to provide more human friendly names, while
keeping the old format for entity ids. For example, given an Awair
device called "Living Room", we'll generate an entity id of
"sensor.living_room_voc" but show set the name of the device to "Living
Room Volatile organic compounds".
* Support import from config.yaml
We'll create a config entry from config.yaml the first time we're
loaded, and then defer to it from then on.
We ignore all keys other than the access_token, since we no longer need
to deal with per-account rate-limits (rather, everything is per-device
now).
* Add myself to CODEOWNERS
Since I wrote the initial integration, and now this re-write, it feels
appropriate for me to take care of the integration along with `danielsjf`.
* Remove name mangling
* Update homeassistant/components/awair/manifest.json
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
* Update homeassistant/components/awair/config_flow.py
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
* Update homeassistant/components/awair/sensor.py
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
* Update homeassistant/components/awair/sensor.py
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
* Address some review feedback
* Set up reauth flow in a job, rather than awaiting
* Remove unnecessary title string
* Remove unnecessary config schema checking
As pointed out in review, because this comes in via import from
`configuration.yaml`, we can rely on the `PLATFORM_SCHEMA` validation instead.
* Fix tests
* Set unique_id appropriately for legacy devices
For users who have had this integration already installed (and who have
updated their home assistant installation sometime in recent history),
we want to ensure that unique_id's are set to the same thing as before,
to facilitate the upgrade process.
To do that, we add an additional property to the `SENSOR_TYPES` dict
(`ATTR_UNIQUE_ID`) which allows us to map modern sensor names from
python_awair to what older versions called them - ie: `humidity` ->
`HUMID`. We then use that value when constructing the unique ID. This
should allow users to upgrade and not lose configuration even if entity
IDs would otherwise change (because we have changed the name format that
generates entity IDs).
One note is that for the gen1 `DUST` sensor, we have to treat it
differently. This integration used to call that a "PM2.5" sensor, but
the unique_id generated would be something like `awair_12345_DUST`. So
we special-case that sensor, and do the same thing. We do not need to
special-case the PM10 sensor for gen1 devices, because we didn't create
a PM10 sensor in the past (we do now, because the "DUST" sensor is
really a hybrid PM2.5/PM10 sensor).
* Patch async_setup_entry for two tests
* Update awair config_flow to require / use an email address for unique_id
Also, only start one re-auth flow.
* Add a few more tests, try to get coverage up.
* Add another test
* Move attribution to device_state_attributes
* Don't require email
* Switch from Union[dict, None] to Optional[dict]
* Use a mock where requested
* Fix missing constant rename
* Use async_create_task
* Bump test coverage a bit for config_flow
* s/CONF_UNIQUE_ID/UNIQUE_ID/g
* Add warning about deprecated platform config
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
2020-06-21 19:46:07 +00:00
|
|
|
{
|
|
|
|
|
"config": {
|
|
|
|
|
"step": {
|
|
|
|
|
"user": {
|
|
|
|
|
"description": "You must register for an Awair developer access token at: https://developer.getawair.com/onboard/login",
|
|
|
|
|
"data": {
|
|
|
|
|
"access_token": "[%key:common::config_flow::data::access_token%]",
|
|
|
|
|
"email": "[%key:common::config_flow::data::email%]"
|
|
|
|
|
}
|
|
|
|
|
},
|
|
|
|
|
"reauth": {
|
|
|
|
|
"description": "Please re-enter your Awair developer access token.",
|
|
|
|
|
"data": {
|
|
|
|
|
"access_token": "[%key:common::config_flow::data::access_token%]",
|
|
|
|
|
"email": "[%key:common::config_flow::data::email%]"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
},
|
|
|
|
|
"error": {
|
2020-10-07 13:17:10 +00:00
|
|
|
"invalid_access_token": "[%key:common::config_flow::error::invalid_access_token%]",
|
|
|
|
|
"unknown": "[%key:common::config_flow::error::unknown%]"
|
Refactor / update Awair integration (#34394)
* Refactor / update Awair integration
This commit does a few things, all in service of making the Awair
integration more modern and reliable. Specifically we do the following:
- Update to python_awair 0.1.1
- Begin using config entries / flow for setting up the integration.
- YAML support is completely removed.
- The integration now allows adding multiple Awair accounts, should a
user wish to do so (I found it _very_ useful in development).
- Group various Awair sensors into devices, using the device registry.
- Renames various sensors and treats the "dust" sensor as a particulate sensor.
- Device update rate-limits are no longer dynamically calculated; the
Awair API now separates rate-limits on a per-device basis.
- Supports sound pressure and illuminance sensors found on some Awair devices.
- We report the "awair index" for certain sensors as part of device_state_attributes.
The "index" is a subjective measure of whether or not a sensor reading
is "good" or "bad" (and to what extent). It's a component of the Awair
score, and it is useful on its own as an input for those who wish to
do things like "display this color if the value is 'bad'".
This is a breaking change, and requires updates to documentation and a
warning in the README. The breaking changes in detail, are:
- Support for all YAML configuration is removed, and users will need to
re-add the integration via the UI.
- We no longer support overriding device discovery via manual
configuration of device UUIDs. This was previously supported because
the Awair API had severe limits on the device list endpoints; however
those have since been removed.
- Gen 1 devices no longer show a "dust" sensor; rather we create a PM2.5
sensor and a PM10 sensor and just keep the values in sync. This better
reflects the sensor capabilities: it can detect particles in a range
from 2.5 -> 10, but cannot differentiate between sizes.
- Sensors are renamed as follows:
- "sensor.devicename_co2" -> "sensor.devicename_carbon_dioxide"
- "sensor.devicename_voc" -> "sensor.devicename_volatile_organic_compounds"
- "sensor.devicename_score" -> "sensor.devicename_air_quality_index"
- I've chosen to call the "Awair Score" an "air quality index" sensor,
because fundamentally the "Awair Score" and other air quality indices
(such as CAQI) do the same thing: they calculate a value based on a
variety of other inputs.
Under the hood, the integration has seen some improvements:
- We use the DataUpdateCoordinator class to handle updates, rather than
rolling our own update class.
- The code no longer tracks availability based on a timestamp returned
from the Awair service; we assert that if we have received a response
and the response has data for our device, then we are available (and
otherwise, not available). We don't need to test the actual Awair API
so heavily.
- Test coverage has been expanded to handle a variety of products that
Awair produces, not just the one I happen to own.
- Test coverage no longer concerns itself with testing behavior that is
now handled by the DataUpdateCoordinator; nor is it concerned with
ensuring that the overall component sets up and registers properly.
These are assumed to be well-tested functionaity of the core and not
things we need to re-test ourselves.
Finally - between library updates and integration updates, this
integration is well-positioned to support future updates. I have a
proof-of-concept patch for device automations, and the underlying
library now supports subclassing authentication (which clears the way
for us to use OAuth authentication for Awair).
* Wrap test fixture in mock_coro
Truthfully I'm not sure why this was passing on my local dev
environment, but I was developing with python 3.8 before. After
installing python 3.7, I was able to reproduce the CI failures and fix
them.
* Fix broken tests after #34901 and/or #34989
* Do not rename sensors so broadly
We're going to keep the sensors named as they were before, pending the
outcome of any decisions around the air_quality component and what names
should be standardized for air-quality-like devices.
If standardized names are selected (which does seem likely), then we
will update this integration to match them - at which point, it would be
a breaking change.
But for now, we'll keep names mostly identical to what users had before.
Notable in this commit is that we generate the entity_id ourselves,
rather than just allowing it to be auto-generated from the name
attribute. This allows us to provide more human friendly names, while
keeping the old format for entity ids. For example, given an Awair
device called "Living Room", we'll generate an entity id of
"sensor.living_room_voc" but show set the name of the device to "Living
Room Volatile organic compounds".
* Support import from config.yaml
We'll create a config entry from config.yaml the first time we're
loaded, and then defer to it from then on.
We ignore all keys other than the access_token, since we no longer need
to deal with per-account rate-limits (rather, everything is per-device
now).
* Add myself to CODEOWNERS
Since I wrote the initial integration, and now this re-write, it feels
appropriate for me to take care of the integration along with `danielsjf`.
* Remove name mangling
* Update homeassistant/components/awair/manifest.json
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
* Update homeassistant/components/awair/config_flow.py
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
* Update homeassistant/components/awair/sensor.py
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
* Update homeassistant/components/awair/sensor.py
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
* Address some review feedback
* Set up reauth flow in a job, rather than awaiting
* Remove unnecessary title string
* Remove unnecessary config schema checking
As pointed out in review, because this comes in via import from
`configuration.yaml`, we can rely on the `PLATFORM_SCHEMA` validation instead.
* Fix tests
* Set unique_id appropriately for legacy devices
For users who have had this integration already installed (and who have
updated their home assistant installation sometime in recent history),
we want to ensure that unique_id's are set to the same thing as before,
to facilitate the upgrade process.
To do that, we add an additional property to the `SENSOR_TYPES` dict
(`ATTR_UNIQUE_ID`) which allows us to map modern sensor names from
python_awair to what older versions called them - ie: `humidity` ->
`HUMID`. We then use that value when constructing the unique ID. This
should allow users to upgrade and not lose configuration even if entity
IDs would otherwise change (because we have changed the name format that
generates entity IDs).
One note is that for the gen1 `DUST` sensor, we have to treat it
differently. This integration used to call that a "PM2.5" sensor, but
the unique_id generated would be something like `awair_12345_DUST`. So
we special-case that sensor, and do the same thing. We do not need to
special-case the PM10 sensor for gen1 devices, because we didn't create
a PM10 sensor in the past (we do now, because the "DUST" sensor is
really a hybrid PM2.5/PM10 sensor).
* Patch async_setup_entry for two tests
* Update awair config_flow to require / use an email address for unique_id
Also, only start one re-auth flow.
* Add a few more tests, try to get coverage up.
* Add another test
* Move attribution to device_state_attributes
* Don't require email
* Switch from Union[dict, None] to Optional[dict]
* Use a mock where requested
* Fix missing constant rename
* Use async_create_task
* Bump test coverage a bit for config_flow
* s/CONF_UNIQUE_ID/UNIQUE_ID/g
* Add warning about deprecated platform config
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
2020-06-21 19:46:07 +00:00
|
|
|
},
|
|
|
|
|
"abort": {
|
|
|
|
|
"already_configured": "[%key:common::config_flow::abort::already_configured_account%]",
|
2020-10-07 13:17:10 +00:00
|
|
|
"no_devices_found": "[%key:common::config_flow::abort::no_devices_found%]",
|
2020-10-06 09:29:53 +00:00
|
|
|
"reauth_successful": "[%key:common::config_flow::abort::reauth_successful%]"
|
Refactor / update Awair integration (#34394)
* Refactor / update Awair integration
This commit does a few things, all in service of making the Awair
integration more modern and reliable. Specifically we do the following:
- Update to python_awair 0.1.1
- Begin using config entries / flow for setting up the integration.
- YAML support is completely removed.
- The integration now allows adding multiple Awair accounts, should a
user wish to do so (I found it _very_ useful in development).
- Group various Awair sensors into devices, using the device registry.
- Renames various sensors and treats the "dust" sensor as a particulate sensor.
- Device update rate-limits are no longer dynamically calculated; the
Awair API now separates rate-limits on a per-device basis.
- Supports sound pressure and illuminance sensors found on some Awair devices.
- We report the "awair index" for certain sensors as part of device_state_attributes.
The "index" is a subjective measure of whether or not a sensor reading
is "good" or "bad" (and to what extent). It's a component of the Awair
score, and it is useful on its own as an input for those who wish to
do things like "display this color if the value is 'bad'".
This is a breaking change, and requires updates to documentation and a
warning in the README. The breaking changes in detail, are:
- Support for all YAML configuration is removed, and users will need to
re-add the integration via the UI.
- We no longer support overriding device discovery via manual
configuration of device UUIDs. This was previously supported because
the Awair API had severe limits on the device list endpoints; however
those have since been removed.
- Gen 1 devices no longer show a "dust" sensor; rather we create a PM2.5
sensor and a PM10 sensor and just keep the values in sync. This better
reflects the sensor capabilities: it can detect particles in a range
from 2.5 -> 10, but cannot differentiate between sizes.
- Sensors are renamed as follows:
- "sensor.devicename_co2" -> "sensor.devicename_carbon_dioxide"
- "sensor.devicename_voc" -> "sensor.devicename_volatile_organic_compounds"
- "sensor.devicename_score" -> "sensor.devicename_air_quality_index"
- I've chosen to call the "Awair Score" an "air quality index" sensor,
because fundamentally the "Awair Score" and other air quality indices
(such as CAQI) do the same thing: they calculate a value based on a
variety of other inputs.
Under the hood, the integration has seen some improvements:
- We use the DataUpdateCoordinator class to handle updates, rather than
rolling our own update class.
- The code no longer tracks availability based on a timestamp returned
from the Awair service; we assert that if we have received a response
and the response has data for our device, then we are available (and
otherwise, not available). We don't need to test the actual Awair API
so heavily.
- Test coverage has been expanded to handle a variety of products that
Awair produces, not just the one I happen to own.
- Test coverage no longer concerns itself with testing behavior that is
now handled by the DataUpdateCoordinator; nor is it concerned with
ensuring that the overall component sets up and registers properly.
These are assumed to be well-tested functionaity of the core and not
things we need to re-test ourselves.
Finally - between library updates and integration updates, this
integration is well-positioned to support future updates. I have a
proof-of-concept patch for device automations, and the underlying
library now supports subclassing authentication (which clears the way
for us to use OAuth authentication for Awair).
* Wrap test fixture in mock_coro
Truthfully I'm not sure why this was passing on my local dev
environment, but I was developing with python 3.8 before. After
installing python 3.7, I was able to reproduce the CI failures and fix
them.
* Fix broken tests after #34901 and/or #34989
* Do not rename sensors so broadly
We're going to keep the sensors named as they were before, pending the
outcome of any decisions around the air_quality component and what names
should be standardized for air-quality-like devices.
If standardized names are selected (which does seem likely), then we
will update this integration to match them - at which point, it would be
a breaking change.
But for now, we'll keep names mostly identical to what users had before.
Notable in this commit is that we generate the entity_id ourselves,
rather than just allowing it to be auto-generated from the name
attribute. This allows us to provide more human friendly names, while
keeping the old format for entity ids. For example, given an Awair
device called "Living Room", we'll generate an entity id of
"sensor.living_room_voc" but show set the name of the device to "Living
Room Volatile organic compounds".
* Support import from config.yaml
We'll create a config entry from config.yaml the first time we're
loaded, and then defer to it from then on.
We ignore all keys other than the access_token, since we no longer need
to deal with per-account rate-limits (rather, everything is per-device
now).
* Add myself to CODEOWNERS
Since I wrote the initial integration, and now this re-write, it feels
appropriate for me to take care of the integration along with `danielsjf`.
* Remove name mangling
* Update homeassistant/components/awair/manifest.json
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
* Update homeassistant/components/awair/config_flow.py
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
* Update homeassistant/components/awair/sensor.py
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
* Update homeassistant/components/awair/sensor.py
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
* Address some review feedback
* Set up reauth flow in a job, rather than awaiting
* Remove unnecessary title string
* Remove unnecessary config schema checking
As pointed out in review, because this comes in via import from
`configuration.yaml`, we can rely on the `PLATFORM_SCHEMA` validation instead.
* Fix tests
* Set unique_id appropriately for legacy devices
For users who have had this integration already installed (and who have
updated their home assistant installation sometime in recent history),
we want to ensure that unique_id's are set to the same thing as before,
to facilitate the upgrade process.
To do that, we add an additional property to the `SENSOR_TYPES` dict
(`ATTR_UNIQUE_ID`) which allows us to map modern sensor names from
python_awair to what older versions called them - ie: `humidity` ->
`HUMID`. We then use that value when constructing the unique ID. This
should allow users to upgrade and not lose configuration even if entity
IDs would otherwise change (because we have changed the name format that
generates entity IDs).
One note is that for the gen1 `DUST` sensor, we have to treat it
differently. This integration used to call that a "PM2.5" sensor, but
the unique_id generated would be something like `awair_12345_DUST`. So
we special-case that sensor, and do the same thing. We do not need to
special-case the PM10 sensor for gen1 devices, because we didn't create
a PM10 sensor in the past (we do now, because the "DUST" sensor is
really a hybrid PM2.5/PM10 sensor).
* Patch async_setup_entry for two tests
* Update awair config_flow to require / use an email address for unique_id
Also, only start one re-auth flow.
* Add a few more tests, try to get coverage up.
* Add another test
* Move attribution to device_state_attributes
* Don't require email
* Switch from Union[dict, None] to Optional[dict]
* Use a mock where requested
* Fix missing constant rename
* Use async_create_task
* Bump test coverage a bit for config_flow
* s/CONF_UNIQUE_ID/UNIQUE_ID/g
* Add warning about deprecated platform config
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
2020-06-21 19:46:07 +00:00
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
