screenlogicpy

Fixes:

• Fixed super chlorination stopping if any SCG settings were changed.
  • Super chlorination would be turned off if any SCG setting(s) were set without also explicitly defining the super chlorinate setting.
  • SCG settings now use existing super chlorinate setting instead of defaulting to 0.

Breaking Changes:

• Require python 3.10+
  • Portions of codebase now use union type hints
• Refactor exception handling
  • Methods that lead to making a request to the protocol adapter will no longer return a bool indicating success. Instead an appropriate exception will be raised if an error is encountered.
  • Add more granular ScreenLogicException:
    • ScreenLogicCommunicationError - Base class for all communication errors.
      • ScreenLogicLoginError - The login was explicitly rejected.
      • ScreenLogicConnectionError - Connection to the protocol adapter was lost.
      • ScreenLogicRequestError - Protocol adapter indicated an unknown or malformed request.
      • ScreenLogicResponseError - Protocol adapter returned an unexpected response.

Changes:

• Make set_scg_config and set_chem_data kwargs only.
  • Supports needing to only supply the changed value(s), not all values set with pool command.
• Refactor unit/integration testing.
  • Make actual unit tests for many functions.
  • Add support for pulling testing data from .json files.
  • Support testing against multiple data sets.
  • Support for creating data sets from HA diagnostic exports.

Added:

• Add support for getting and setting pool controller date/time.
  • Support for syncing pool controller date/time to the host's date/time.
• Support getting/setting Super Chlorination settings.
• CLI support for:
  • Setting user-set IntelliChem values:
    • Calcium Hardness
    • Cyanuric Acid
    • Total Alkalinity
    • Salt/TDS
  • Setting super chlorinate values:
    • Enabled (On/Off)
    • Run Time Hours
  • Getting and setting pool controller date and/or time.
  • Exporting a testing data set.

Fixes:

• Reset colors list on each config update
  • This fixes unintended internal data growth each time a gateway reconnects to a protocol adapter.

Changes:

• Cancel/cleanup outstanding requests (futures) on connection loss
• Add additional debug logging.
  • Client ID on gateway subscription
  • Any errors when attempting to create connection

Changes:

• Change SCG setpoint step value for pool and spa to 1

Changes:

• Filter Chlorinator state to low bit (0x01) in data.
  • Limits Chlorinator state to 1 or 0.

Changes:

• Don't exclude any data keys regardless of equipment config
  • Decisions on what data to include in the data dict based on equipment config or seemingly 'invalid' values will no longer be made within screenlogicpy. Any calling application will be responsible for filtering irrelevant information from their user.
• Don't attempt to reconnect during ping or remove_client requests.
  • These requests are not critical and can interrupt or block the desired connection sequence.
• Don't retry a failed request if no longer connected to the protocol adapter.

Breaking Changes:

• Python 3.8 is no longer supported as of this release. Minimum supported Python version is now 3.9.
  Future note: Support for Python 3.9 will be deprecated after the 0.9.x release series, after which Python 3.10 will be the minimum supported version.
  • Updated types to python 3.9 generics typing
• Major data refactor
  This release contains a major reorganization of the internal data dict, and in-turn the resulting json output. Changes include:
  • Data reorganized by device and common group.
    • Flags values get their own group.
  • Multiple data keys renamed for correctness, clarity, or newly discovered functionality.
    You can check out the new json format here.

Changes:

• Use constants for all data dict keys.
• Use Enums for flags and int values

Added:

• ScreenLogicGateway.get_data() now supports returning subsets of data or individual values. get_data() accepts a "path" in the form of multiple parameters of keys to the desired data, and will return only that data.
  • Shortcut methods get_name() and get_value() have also been added. These will return the value of the "name" or "value" key that exists - if it exists - within the data specified by the data "path".
  • By default get_data(), get_name(), and get_value() will return None if the specified path or key is not found. Keyword arg strict=True can be specified to raise KeyError exception if the path or key is not found.

Breaking Change:

• ScreenLogicWarning is no longer raised on request or connection errors. See Changes below for details on what is raised when.

Changes:

• Reconnect on request failure
  • screenlogicpy will now attempt to reconnect to the protocol adapter once after a failure to complete a request (for any reason), after retrying the set number of times. If reconnected, screenlogicpy will attempt the request once again.
  • If reconnection or the second full request attempt fails, screenlogicpy will raise a full ScreenLogicError exception. This supports Home Assistant handling the communication failure accordingly.
  • ScreenLogicRequestError is raised for failure in making a request to the protocol adapter.
  • A full ScreenLogicError is raised immediately on any failure to connection to the protocol adapter.

Added:

• New exception classes
  • ScreenLogicException Base exception class for screenlogicpy
  • ScreenLogicRequestError raised specifically for failing to complete a request due to:
    • Communication timeout
    • Any error response from the protocol adapter

Fixes:

• Fixed crash when attempting to keep a client connection alive by pinging the protocol adapter

Changes:

• Updated testing support code

Breaking Change:

• Passing host connection parameters to the ScreenLogicGateway constructor was deprecated in v0.7.0 and has now been removed. Consuming code should use async_connect() instead.

Changes:

• Support for Python 3.8 and 3.9 is being phased out.
  • Home Assistant - this library's target audience - only supports that last two major releases of Python and has already removed support for Python 3.8 and 3.9. It is expected that support for Python 3.10 in Home Assistant will also be deprecated when Python 3.12 releases.
  • The next "major"(minor in semantic versioning) release of screenlogicpy (v0.9.0) will remove support for Python 3.8, with 3.9 to follow the next "major" release after that.
• .requests.utility.getString() will now return a decoded and trimmed str value. Anyone using getString() in their own code (ie. custom message decoding) no longer need to call .decode("utf-8").strip("\0") themselves on the return.
• Color update message decoding was moved into requests\lights.py
• Order of release notes will now list breaking changes first, followed by general changes, then additions.
• Various cleanup, typing, code improvements
• Documentation updates

Added:

• Added support for retrying requests in the event of a timeout (no response within 5 seconds) or if the protocol adapter returns an error code (too many requests at once seems to be able to cause the protocol adapter to return error code 31).
  • The number of times screenlogicpy with attempt to send or resend a message defaults to 2. This can be changed by:
    • Passing a new value in the max_retries parameter during gateway instantiation
    • By using gateway.set_max_retries(new_value)
  • The new value can be None or 1-5. Calling set_max_retries() with no value will reset to the default of 2.
• Support for a unique client_id per instance of screenlogicpy.
  • A random id will be used or the client_id parameter can be specified at gateway creation to use a custom one.

Changes:

• Updated INTERFACE_GROUP with more known values.
  • Changed LIGHTS from 3 -> 4
  • Added LIGHTS_COLOR (3) and DONT_SHOW (5)
• Misc formatting and Debug logging updates.

Full Changelog: https://github.com/dieselrabbit/screenlogicpy/compare/v0.7.1...v0.7.2

Added:

• state_type (SensorStateClass in HA) measurement added to appropriate sensors.
  • This supports proper statistics tracking in Home Assistant.
  • Affected sensors:
    • sensors : air_temperature, ph, orp, saturation, salt_ppm, ph_supply_level, orp_supply_level
    • bodies [body_num] : last_temperature
    • pumps [pump_num] : currentWatts, currentRPM, currentGPM
    • chemistry : current_ph, current_orp, ph_supply_level, orp_supply_level, saturation, ph_probe_water_temp
    • scg : scg_salt_ppm

Added:

• Support for handling pushed state updates from a ScreenLogic system. This includes:
  • Callback manager for calling code to subscribe to push message updates. gateway.async_subscribe_client(callback, code). See readme for details.
  • Auto subscribe/unsubscribe as a client to the protocol adapter.
  • Automatically enable connection keeping to keep connection alive while screenlogicpy is subscribed as a client to the protocol adapter.
• Alternative async message handler code path: gateway.register_async_message_handler(code, coro). See readme for details.
  • Supports user handling of unsolicited messages from the ScreenLogic protocol adapter (ie. Weather Forceast Changed, etc.)
• Support partial data polling.
• Initial support for state_type (SensorStateClass in HA).

Breaking Change:

• Const CIRCUIT_FUNCTION.GROUP_LIGHTING renamed to CIRCUIT_FUNCTION.GROUP_LIGHTS_ALL. This change supports two new CIRCUIT_FUNCTION constants .GROUP_LIGHTS_BASIC and .GROUP_LIGHTS_COLOR.

Changed:

• Host info (IP Address, port, etc.) should now be passed in gateway.async_connect().
  • The previous method of passing host info at gateway instantiation is deprecated and will be removed in a future release.
• device_type (DeviceClass in HA) for *_dosing_state changed to ENUM.

Added:

• Implemented a message buffer to handle messages larger than 1024 bytes.
  • Handles SL messages split across multiple chunks of data as well as multiple SL messages in a single chunk of data.
• Included raw values for parsed chemistry bitmasks to aid debugging.
  • "chemistry": { "alerts": { "_raw": 0, ...
  • "chemistry": { "notifications": { "_raw": 0, ...
• Added some additional chemistry flags for future use.

Changed:

• Renamed unknown bytes keys within circuit defs to include byte offsets.
  • unknown1 -> unknown_at_offset_**
  • unknown2 -> unknown_at_offset_**

Changed:

• Store freeze_mode value in standard 1=on, 0=off instead of it's raw value of 8=on.

Changed:

• Updated Python version classifiers to include 3.10 & 3.11.

Changes:

• Use constants for measurement units.
  • This supports conversion of screenlogicpy's prefered way of displaying measurement units to a consuming application's prefered way.
  • Will be useful in in Home Assistant to support broader/future device types and HA's native unit functionality.
• Use asyncio.timeout/async_timeout to avoid creating tasks.
  • py3.11 has a new asyncio.timeout which is much more efficient. Uses async_timeout on < py3.11. (Thanks @bdraco)

Changed:

• Device types
  • Added
    • duration for pH/ORP Last Dose Time
    • volume for pH/ORP Last Dose Volume
  • Updated
    • energy -> power for Pump Current Watts
• SCG limit for Spa mode upped to 100
• Refactored CLI tests to use @pytest.mark.parametrize()

Added:

• Ability to set IntelliChem chemistry values
  • pH Setpoint
  • ORP Setpoint
  • Calcium Hardness
  • Total Alkalinity
  • Cyanuric Acid
  • Salt Level

Changed:

• Added debugging data:
  • Included all unknown and previously skipped response bytes in data. Hopefully this will be helpful in comparing unknown values between installations with known features.
  • Labeled all unknown values/data with byte offset. ex. unknown_at_offset_24.
• Code cleanup:
  • Consolidated request lifetime management code.
  • Refactored how response data is integrated into the main data dict.
  • Miscellaneous code optimization taking advantage of new patterns

Added:

• Debug gateway function get_debug(). Returns a dict of the last responses to each request in raw bytes.

Fixed:

• Fixed leak of Future objects in protocol.

Changed:

• Updated friendly names for SCG Levels:
  • SCG Level 1 -> Pool SCG Level
  • SCG Level 2 -> Spa SCG Level