Library: states

From Yombo
Jump to: navigation, search
states
Commonly Used Yes
Status Active

Summary
Provide current states of items, such as if it's light, dark.

Introduction

The states interface provides a common method to share automation states. States can include any arbitrary information, such as weather, sunrise/sunset, moonrise, someone's location, alarm system status, etc.

A few naming conventions have been determined and should be followed. This allows modules and libraries to share state information without duplication or confusion.

Developers should take care not to overwrite a state of the same name for a different purpose or meaning.

See also

Hooks

Usage

The States library can act as an act as a dictionary for reading and writing, or can call get and set functions. In every library and module (even custom modules), a pre-defined variable called self._States is defined as a pointer to the States library.

Reading Values

It's simple to read or get a state value, there are two ways to access: the_value = self._States['is.dark'] # More pythonic the_value = self._States.get("is.dark") # For those that are used to other programming languages. To update or write a value is just as easy: self._States['is.dark'] = new_value # More pythonic self._States.set("is.dark") = new_value # For those that are used to other programming languages.

Value Types

State values can be one of: string, dictionary, or list. When possible, it's preferred to use a string (or int, float, etc) over a dictionary. However, don't put too much weight into this request.

Functions

For complete list of functions, see: States - Yombo Python API Docs

Examples

 1 try:
 2      raining = self._States['is.raining']
 3    except:
 4      raining = None
 5 
 6    if raining is not True:
 7        # enable sprinklers
 8 
 9    try:
10      jeffIsHome = self._States['is.personhome.jeff']
11    except:
12      jeffIsHome = None
13 
14    if jeffIsHome is True:
15        # turn on HVAC system
16    elif jeffIsHome is false:
17        # turn off HVAC
18    else:
19        # we don't know if Jeff is home or not, leave HVAC alone</pre>
20 <pre class="lang:python decode:true">a = "help"
21 print("%s" % a)


Naming Standards

Yombo provides loose naming standards. However, like AMQP, it the name should use dot notation format, starting from most general to most specific. For example, a module that implements forecast collection from a data source may set many states regarding forecast. In this example, it can collect forecast data for 7 days ahead and can provide current humidity for current location.For example for weather forcast, the name should be "weather.forcast.now" if using weather for now for 2 days from now: "weather.forcast.2days".

High level definitions

Yombo does not set naming standards for state names. However; some guidelines have been set.

  • All state names should start with the the type of state being stored, such as: weather, alarm, garagedoor, etc.
  • Don't use multiple states when one is good enough. Don't use "is.whole_house_fan_on" and "house_whole_house_fan_status". This is redundant, just use one: is.whole_house_fan = Off
  • True/False values should start with "is", such as: is.raining=True, is.alarm_ringing=False, is.house_is_occupied=True, is.garage_door_is_all_closed=True
    • Don't use "True" or "False", use True or False.
    • When practical, don't use 1 or 0, use True or False.
  • Items holding the status of state, should simply add 'State': alarm.state="Disarmed"
  • Think about supporting multiple items. In this case, we can support multiple garage doors problematically.
    • garage_door.count = 2
    • garage_door.1 = 'Open' - Multiple garage doors can be supported easily.
  • Don't set any values to None or "None" to delete a value. Simply use "self._States.delete('State Name').

Some suggested high level definitions. This list will be updated regularly as they become defined from the community.

  • For items that are true/false or on/off.
    • is - For items that are true/false or on/off.
  • For things that happen in the future.
    • next - next.sunrise, next.moonrise
  • Capabilities. For example, if a module implemements a feature, it can advertise this. The value would '1'.
    • has:
      • has.alarmsystem=1
      • has.sprinklers=1
      • has.forecast=1
      • has.forcast.numberofdays=7
      • has.forcast.humidity

Specific definitions

This list will be updated as they become defined from the community. Note: Eventually, this will become it's own beast and a full list will be maintained elsewhere.

  • Alarm Systems
    • has.alarmsystem - 1 for yes
    • alarmsystem.zones - Number of zones alarm system has.
    • alarmsystem.currentalarmzones - A list of zones that are currently active.
    • alarmsystem.monitored - 1 for yes if monitored by an alarm company
  • Weather - Forecast. Useful when no outdoor monitoring equipment is available.
    • has.forecast - 1 if available
    • weather.forecast.numberofdays - number of days forecast is available
    • weather.forccast.day1 - forecast for 1 day ahead. A dictionary containing high, low, chance or rain, cloud cover %
    • weather.forecast.now A dictionary for current weather conditions
This page was last edited on 15 September 2018.