# pystove
An async python library with command line interface to interact with HWAM SmartControl wood burning stoves.
### Contents
- [Usage Example](#usage-example)
- [Library Reference](#library-reference)
- [Properties](#properties)
- [Methods](#methods)
- [Command Line Invocation](#command-line-invocation)
### Usage Example
```python
import asyncio
from pystove import Stove
HOST = 'stove.local'
async def switch_on_stove():
"""Create a Stove object, switch to ignition mode and set burn level to 5."""
# Create the object
stove = await Stove.create(HOST)
# Switch to ignition mode
if await stove.start():
# If successful, set burn level to 5.
await stove.set_burn_level(5)
# Clean up
await stove.destroy()
# Set up the event loop and run the switch_on_stove coroutine.
loop = asyncio.get_event_loop()
loop.run_until_complete(switch_on_stove())
```
## Library Reference
### Properties
#### Stove.algo_version
The algorithm version of the stove.
#### Stove.name
The name of the stove as set during initial configuration.
#### Stove.series
The series/model of the stove.
#### Stove.stove_host
The hostname used during creation of the Stove object.
#### Stove.stove_ip
The IP address as reported by the stove.
#### Stove.stove_mdns
The MAC address prefixed with "ihs_" as reported by the stove.
#### Stove.stove_ssid
The SSID to which the stove is connected.
### Methods
#### @classmethod Stove.create(_cls_, stove_host, loop=asyncio.get_event_loop(), skip_ident=False)
Create a pystove object asynchronously. This method takes the following arguments:
- __stove_host__ The hostname or IP address of the stove.
- __loop__ Event loop to use for the pystove object.
- __skip_ident__ Skip identification calls to the stove. Speeds up creation of the pystove object but the resulting object will be missing its identifying information.
Returns a pystove object with at least the `stove_host` property set. If `skip_ident` was set to `False` (the default), all other properties should be set as well
This method is a coroutine.
#### Stove.destroy(_self_)
Run a cleanup of the Stove object. This method should be called before exiting your program to avoid error messages.
This method is a coroutine.
#### Stove.get_data(_self_)
Retrieve information about the current state of the stove.
Returns a dict containing processed information about the current state of the stove. Useful for e.g. display purposes as most variables have been processed into readable information or python data types.
This method is a coroutine.
#### Stove.get_live_data(_self_)
Retrieve a log of recent temperature and oxygen level data from the stove.
Returns a dict with the following structure:
```python
{
pystove.DATA_STOVE_TEMPERATURE: [...],
pystove.DATA_OXYGEN_LEVEL: [...]
}
```
Each item contains a sequential list with historical sensor data for each minute of the last 2 hours.
This method is a coroutine.
#### Stove.get_raw_data(_self_)
Retrieve information about the current state of the stove.
Returns a dict containing unprocessed information about the current state of the stove. All information is forwarded as provided by the stove.
This method is a coroutine.
#### Stove.self_test(_self_, processed=True)
Start and monitor the self-test routine of the stove. This method will request and return intermediate results every 3 seconds until all tests have either been passed or skipped.
The following argument is supported:
- __processed__ Whether the results should be processed into human-readable form. Defaults to `True`.
This method is a generator coroutine.
#### Stove.set_burn_level(_self_, burn_level)
Set the burn level on the stove. Returns `True` on success.
This method takes the following argument:
- __burn_level__ The burn level to set on the stove. Supported values are 0 through 5.
This method is a coroutine.
#### Stove.set_night_lowering(_self_, state=None)
Set or toggle the night lowering option on the stove. Returns `True` on success.
This method takes the following argument:
- __state__ The new night lowering setting to set on the stove. Supported values must evaluate to `True` or `False`. If omitted or `None` (the default), the setting will be toggled.
This method is a coroutine.
#### Stove.set_night_lowering_hours(_self_, start=None, end=None)
Set the night lowering hours on the stove. Returns `True` on success.
This method takes the following arguments:
- __start__ A `datetime.time` object containing the requested night lowering start time. If omitted or `None`, the start time will not be changed.
- __end__ A `datetime.time` object containing the requested night lowering end time. If omitted or `None`, the end time will not be changed.
This method is a coroutine.
#### Stove.set_remote_refill_alarm(_self_, state=None)
Set the remote refill alarm. Returns `True` on success.
This method takes the following argument:
- __state__ The new remote refill alarm setting to set on the stove. Supported values must evaluate to `True` or `False`. If omitted or `None` (the default), the setting will be toggled.
This method is a coroutine.
#### Stove.set_time(_self_, new_time=datetime.now())
Set the time and date on the stove. Returns `True` on success.
This method takes the following argument:
- __new_time__ A `datetime.datetime` object containing the time and date to set on the stove. If omitted, the current time on the local host will be used.
This method is a coroutine.
#### Stove.start(_self_)
Switch the stove to `Ignition` mode. Returns `True` on success.
This method is a coroutine.
## Command Line Invocation
```
Usage: ./pystove_cli.py <options>
Options:
-h, --host <HOST> Required
The IP address or hostname of the stove.
-f, --fast Optional
Run in fast mode (skip ident).
-c, --command <COMMAND> Optional
The command to send to the stove.
If no command is provided, it defaults to show_info.
-v, --value <VALUE> Optional
The value to send to the stove with the supplied command.
Supported commands:
get_data
Retrieve a list of processed configuration values.
get_live_data:
Retrieve historical stove temperature and oxygen level
data from the last 2 hours.
get_raw_data
Retrieve a list of unprocessed configuration values.
self_test
Run stove self test routine and return result.
set_burn_level
Set the burn level of the stove.
This command requires a value between 0 and 5.
set_night_lowering
Set the night lowering option.
This command takes an optional value: 1=on, 0=off
A call without value toggles the setting.
set_night_lowering_hours
Set the night lowering hours on the stove.
This command requires a <value> in the form of <start>-<end>
Both <start> and <end> must be in 24h format H[:MM]
set_remote_refill_alarm
Set the remote refill alarm.
This command takes an optional value: 1=on, 0=off
A call without value toggles the setting.
set_time
Set the time on the stove. Defaults to current time on this system.
Optional value format: YYYY-MM-DD HH:MM:SS
show_info
Show the stove identification information.
start
Set the stove in ignition mode.
```
Raw data
{
"_id": null,
"home_page": "https://github.com/mvn23/pystove",
"name": "pystove",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "stove hwam smartcontrol",
"author": "Milan van Nugteren",
"author_email": "milan@network23.nl",
"download_url": "https://files.pythonhosted.org/packages/e7/f5/ea51be5b5a425617f091c06b4b81a219e77eee21d60442198fdabb70f71d/pystove-0.3a1.tar.gz",
"platform": null,
"description": "# pystove\n\nAn async python library with command line interface to interact with HWAM SmartControl wood burning stoves.\n\n### Contents\n- [Usage Example](#usage-example)\n- [Library Reference](#library-reference)\n - [Properties](#properties)\n - [Methods](#methods)\n- [Command Line Invocation](#command-line-invocation)\n\n### Usage Example\n```python\nimport asyncio\nfrom pystove import Stove\n\n\nHOST = 'stove.local'\n\n\nasync def switch_on_stove():\n \"\"\"Create a Stove object, switch to ignition mode and set burn level to 5.\"\"\"\n\n # Create the object\n stove = await Stove.create(HOST)\n\n # Switch to ignition mode\n if await stove.start():\n\n # If successful, set burn level to 5.\n await stove.set_burn_level(5)\n\n # Clean up\n await stove.destroy()\n\n# Set up the event loop and run the switch_on_stove coroutine.\nloop = asyncio.get_event_loop()\nloop.run_until_complete(switch_on_stove())\n\n```\n\n## Library Reference\n\n### Properties\n\n#### Stove.algo_version\nThe algorithm version of the stove.\n#### Stove.name\nThe name of the stove as set during initial configuration.\n#### Stove.series\nThe series/model of the stove.\n#### Stove.stove_host\nThe hostname used during creation of the Stove object.\n#### Stove.stove_ip\nThe IP address as reported by the stove.\n#### Stove.stove_mdns\nThe MAC address prefixed with \"ihs_\" as reported by the stove.\n#### Stove.stove_ssid\nThe SSID to which the stove is connected.\n\n### Methods\n\n#### @classmethod Stove.create(_cls_, stove_host, loop=asyncio.get_event_loop(), skip_ident=False)\nCreate a pystove object asynchronously. This method takes the following arguments:\n\n- __stove_host__ The hostname or IP address of the stove.\n- __loop__ Event loop to use for the pystove object.\n- __skip_ident__ Skip identification calls to the stove. Speeds up creation of the pystove object but the resulting object will be missing its identifying information.\n\nReturns a pystove object with at least the `stove_host` property set. If `skip_ident` was set to `False` (the default), all other properties should be set as well\n\nThis method is a coroutine.\n\n#### Stove.destroy(_self_)\nRun a cleanup of the Stove object. This method should be called before exiting your program to avoid error messages.\n\nThis method is a coroutine.\n\n#### Stove.get_data(_self_)\nRetrieve information about the current state of the stove.\nReturns a dict containing processed information about the current state of the stove. Useful for e.g. display purposes as most variables have been processed into readable information or python data types.\n\nThis method is a coroutine.\n\n#### Stove.get_live_data(_self_)\nRetrieve a log of recent temperature and oxygen level data from the stove.\nReturns a dict with the following structure:\n```python\n{\n pystove.DATA_STOVE_TEMPERATURE: [...],\n pystove.DATA_OXYGEN_LEVEL: [...]\n}\n```\nEach item contains a sequential list with historical sensor data for each minute of the last 2 hours.\n\nThis method is a coroutine.\n\n#### Stove.get_raw_data(_self_)\nRetrieve information about the current state of the stove.\nReturns a dict containing unprocessed information about the current state of the stove. All information is forwarded as provided by the stove.\n\nThis method is a coroutine.\n\n#### Stove.self_test(_self_, processed=True)\nStart and monitor the self-test routine of the stove. This method will request and return intermediate results every 3 seconds until all tests have either been passed or skipped.\nThe following argument is supported:\n\n- __processed__ Whether the results should be processed into human-readable form. Defaults to `True`.\n\nThis method is a generator coroutine.\n\n#### Stove.set_burn_level(_self_, burn_level)\nSet the burn level on the stove. Returns `True` on success.\nThis method takes the following argument:\n\n- __burn_level__ The burn level to set on the stove. Supported values are 0 through 5.\n\nThis method is a coroutine.\n\n#### Stove.set_night_lowering(_self_, state=None)\nSet or toggle the night lowering option on the stove. Returns `True` on success.\nThis method takes the following argument:\n\n- __state__ The new night lowering setting to set on the stove. Supported values must evaluate to `True` or `False`. If omitted or `None` (the default), the setting will be toggled.\n\nThis method is a coroutine.\n\n#### Stove.set_night_lowering_hours(_self_, start=None, end=None)\nSet the night lowering hours on the stove. Returns `True` on success.\nThis method takes the following arguments:\n\n- __start__ A `datetime.time` object containing the requested night lowering start time. If omitted or `None`, the start time will not be changed.\n- __end__ A `datetime.time` object containing the requested night lowering end time. If omitted or `None`, the end time will not be changed.\n\nThis method is a coroutine.\n\n#### Stove.set_remote_refill_alarm(_self_, state=None)\nSet the remote refill alarm. Returns `True` on success.\nThis method takes the following argument:\n\n- __state__ The new remote refill alarm setting to set on the stove. Supported values must evaluate to `True` or `False`. If omitted or `None` (the default), the setting will be toggled.\n\nThis method is a coroutine.\n\n#### Stove.set_time(_self_, new_time=datetime.now())\nSet the time and date on the stove. Returns `True` on success.\nThis method takes the following argument:\n\n- __new_time__ A `datetime.datetime` object containing the time and date to set on the stove. If omitted, the current time on the local host will be used.\n\nThis method is a coroutine.\n\n#### Stove.start(_self_)\nSwitch the stove to `Ignition` mode. Returns `True` on success.\n\nThis method is a coroutine.\n\n## Command Line Invocation\n```\nUsage: ./pystove_cli.py <options>\n\nOptions:\n\n -h, --host <HOST>\t\tRequired\n The IP address or hostname of the stove.\n\n -f, --fast\t\t\tOptional\n Run in fast mode (skip ident).\n\n -c, --command <COMMAND>\tOptional\n The command to send to the stove.\n If no command is provided, it defaults to show_info.\n\n -v, --value <VALUE>\t\tOptional\n The value to send to the stove with the supplied command.\n\n\nSupported commands:\n\n get_data\n Retrieve a list of processed configuration values.\n\n get_live_data:\n Retrieve historical stove temperature and oxygen level\n data from the last 2 hours.\n\n get_raw_data\n Retrieve a list of unprocessed configuration values.\n\n self_test\n Run stove self test routine and return result.\n\n set_burn_level\n Set the burn level of the stove.\n This command requires a value between 0 and 5.\n\n set_night_lowering\n Set the night lowering option.\n This command takes an optional value: 1=on, 0=off\n A call without value toggles the setting.\n\n set_night_lowering_hours\n Set the night lowering hours on the stove.\n This command requires a <value> in the form of <start>-<end>\n Both <start> and <end> must be in 24h format H[:MM]\n\n set_remote_refill_alarm\n Set the remote refill alarm.\n This command takes an optional value: 1=on, 0=off\n A call without value toggles the setting.\n\n set_time\n Set the time on the stove. Defaults to current time on this system.\n Optional value format: YYYY-MM-DD HH:MM:SS\n\n show_info\n Show the stove identification information.\n\n start\n Set the stove in ignition mode.\n\n```\n",
"bugtrack_url": null,
"license": "GPLv3+",
"summary": "A library to interface with HWAM wood burning stoves.",
"version": "0.3a1",
"project_urls": {
"Homepage": "https://github.com/mvn23/pystove"
},
"split_keywords": [
"stove",
"hwam",
"smartcontrol"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "600c181d21e6b78ba8dcba14be26a7b5accab22898960eb52da44f0f80fc645a",
"md5": "ca3a619b5c4e0f13a30b9e636875442f",
"sha256": "0a7432f79e7e428ba04f897cb6a23108c294c6bf52dc6fdeb58108eff3408581"
},
"downloads": -1,
"filename": "pystove-0.3a1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ca3a619b5c4e0f13a30b9e636875442f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 22594,
"upload_time": "2024-10-07T12:32:12",
"upload_time_iso_8601": "2024-10-07T12:32:12.986704Z",
"url": "https://files.pythonhosted.org/packages/60/0c/181d21e6b78ba8dcba14be26a7b5accab22898960eb52da44f0f80fc645a/pystove-0.3a1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e7f5ea51be5b5a425617f091c06b4b81a219e77eee21d60442198fdabb70f71d",
"md5": "b386896f15664c6e5c098f9c93ca479e",
"sha256": "326691219cf0cb6f1160df0c32e9422bdd119918c88ba8919458ae60f61fc674"
},
"downloads": -1,
"filename": "pystove-0.3a1.tar.gz",
"has_sig": false,
"md5_digest": "b386896f15664c6e5c098f9c93ca479e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 23425,
"upload_time": "2024-10-07T12:32:15",
"upload_time_iso_8601": "2024-10-07T12:32:15.367723Z",
"url": "https://files.pythonhosted.org/packages/e7/f5/ea51be5b5a425617f091c06b4b81a219e77eee21d60442198fdabb70f71d/pystove-0.3a1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-07 12:32:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mvn23",
"github_project": "pystove",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "pystove"
}
JSON
