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.
- To view states, see States @ Web Interface
- For immutable system information see Atoms library
- For complete list of available python functions, see: States - Yombo Python API Docs
- _states_preset_ - Called just before the state value is set.
- _states_set_ - Called just after the state value is set.
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.
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.
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.
For complete list of functions, see: States - Yombo Python API Docs
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)
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'.
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