saynwerk-pystove

An async python library with command line interface to interact with HWAM SmartControl wood burning stoves.

The release candidate 0.3.0rc2 preserves the published 0.3a1 successful API and HWAM request contract. Audit H3 now cleans up owned sessions and tasks after failed or cancelled initialization. H4 makes invalid or incomplete status data return None; successful data retains the exact baseline values and types. The narrow H6 follow-up returns False for malformed/non-object JSON in POST setter confirmations. This means success is unconfirmed, not that the command was not executed; no retry is added. A separate H6 follow-up handles only ClientPayloadError, ServerDisconnectedError and existing TimeoutError during POST command body reading, using the same unconfirmed-success meaning. Request setup, context errors, HTTP statuses and timeout settings remain unchanged. Other runtime defects remain unchanged. See the exact compatibility contract and development checks.

Maintained by Saynwerk at tofrie/pystove. This GPLv3+ fork credits the original author Milan van Nugteren and mvn23/pystove. It is an independently maintained distribution, not an official upstream release.

The distribution is saynwerk-pystove; Python imports remain from pystove import Stove. It depends on aiohttp, not on the original pystove distribution. Never install both distributions in one environment: they own the same files. Use a fresh virtual environment and the release checks. Pip cannot enforce this exclusion. Integrations must validate each dependency upgrade in an isolated environment before changing their production pin.

Cached diagnostics

stove.cached_diagnostics returns a new dictionary without I/O, containing only optional wifi_version and remote_refill_beeps from the last successful status read. It is empty initially. Successful reads replace the cache, clearing absent or malformed optional values; failed reads retain the last successful snapshot. This is not a freshness guarantee. get_data() still returns exactly its original 25 keys, and performs the same single status request. No door/service-date contract or new entities are introduced. Version 0.3.0rc2 is prepared for separate publication approval.

Contents

• Usage Example
• Library Reference
  • Properties
  • Methods
• Command Line Invocation

Usage Example

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:

{
  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.