Rules/Automation

Why aren't my rules running?

On android the AM Server widget must be on one of your home pages (see below for instructions) and the rule engine must be enabled in the AM Manager menu.

Is there a "long press" trigger like belkin supports for their lightswitches?

Unfortunately not, Belkin has chosen to not expose the long button press event locally.  The "WhenClicked" trigger below will allow you to take action on a double click of any wemo.  You could also use a belkin long press rule to trigger another wemo device and use that wemo device state change to trigger a AM Server rule, and now you can use IFTTT to handle the event.

Some rule actions or restores were not completed after I closed the rule editor, what happened?

When you exit the rule editor the rule engine is restarted, cancelling any pending operations.  A "rule engine restarted" message will appear in the log.  Use the "Rule Status" viewer to check your rules without restarting the rule engine. 

Can I use Belkin's or TP Links' "onboard" rules as well as AM Server rules?

Yes.  Those rules run on the device itself.  Their rule engine implementation is too messy for me to integrate with, but there's no problem with using vendor app defined rules along with AM Server rules.

What can I do with rules (see below for some more examples)?  Rules are triggered by events to take some action:

• • Set up schedules to automate your devices - based on time, or around sunrise or sunset

  • Use the change of state of a motion detector or a switch to trigger a rule, e.g. to turn a light on, control two switches in a 3-way switch scenario.

  • Log and/or act on changes to your devices

  • Turn devices off automatically after they've been turned on

  • Report changes to your devices including after a given period, e.g. be notified if you leave the garage door open.

  • Announce changes or events using android Text To Speech to report changes (android only) or by sending emails or notifications.

Remember, on android the rules only run if the AM Server WIDGET has been added to one of your home pages or if you've enabled "widgetless rules"!

AutomationManager/AM Server "Rules"

Rules are what you use to tell AutomationManager how to automate your devices.  You create rules that react to external events called "triggers" when "conditions" are met to perform given "actions".

Triggers are events caused by your automation devices reporting changes (e.g. a motion sensor or a light switch) or externally via a web page, through WemoRemote, or using your own automation tools like Tasker or other applications.  Think of triggers as "OR" events - when any of the trigger events occur the rule actions will be executed.

WAIT - a delay between when the event occurs (the trigger is triggered) and when the rule actions are dispatched.  The delay can be marked random to simulate occupation.

restartable - if a rule is re-triggered the rule is cancelled and restarted.  Any wait time is restarted, any restore actions are cancelled.

interruptable - any STATE event NOT in a trigger will cancel the rule. Of course only state events for the devices in that trigger are monitored.

Cancel - cancelling a rule using a cancel action, a restart, or an interrupt stops any WAIT timer and cancels any restore action.  If restarted the rule is re-triggered.

A second trigger on a rule that is already active (the WAIT timer is counting down or a restore action is pending) has no effect unless that trigger is restartable or interruptible.  If the rule is not active it will be triggered.

Conditions are decisions to be made when a trigger is fired or rule is ready to execute (after a non-zero WAIT time). 

All of the conditions must be true for a rule's actions to be scheduled.  Conditions are "AND" decisions.  When a trigger event occurs AND all of the conditions are true AND the WAIT time reaches zero the rule actions are executed.  A condition can be time based, check the state of your automation devices (e.g. if it's night, or if a switch is already on), or test flags that you can set or reset with other actions.  Use multiple devices/states in a single condition for an OR check.

Actions are executed when a rule is fired (when triggered any WAIT).  If the action is marked for a restore the action is "undone" after the restore period.  For example if a light is turned on when a rule fires, it's turned off when the restore period is up.  Not all actions can be restored. A restore has no effect if the target device is already in the restore state (unless it's a toggle action).  Restores are cancelled if the rule is cancelled.

Devices

Devices generate events (triggers), for example when a device like a sensor or switch changes from off to on, or a value like power use changes.  Devices can also be used in conditions in the same way.  Finally, devices are things that can be acted on - switches can be turned on or off, etc.

Flags are pseudo devices that can be used for logical operations just like real devices.  The can be used in triggers and conditions, and turned on or off in actions or manually.  When the rules engine is started (the engine is restarted if a rule is changed or when AM starts fresh) flags are cleared to the off state unless the "persist" property is set.  Flags are created as custom devices under the search menu.

Events are pseudo devices representing OnEvents.  They can be used in triggers and will fire when the event is received by the rules engine (AutomationServer).  Events are typically triggered externally (from AutomationRemote or an incoming REST call, Tasker, etc) but can also be caused by using SetOn rule, the buttons from the AutomationManager UI, or a DeviceWidget against the Event device (the Event device will return to off state immediately after firing).  Events can be added as custom devices under the search menu.

Triggers

• • WhenDevice (interruptible) - fired when a device changes to any of a number of states. Can be configured to interrupt if a change to another state occurs.  Handy for lights turned on by motion and off after a period with no motion.

  • OnSchedule - trigger rules at given times of a day, can be restricted to trigger on specified days of the week.  

  • OnDate - trigger once on the given date/time.

  • Periodic - trigger rules continuously (use with conditions to limit)

  • AtSunrise, AtSunset - trigger a rule at, before ,or after a solar event

  • Hourly - trigger hourly zero or more minutes before or after the top of the hour

  • WhenState (restartable) - monitor multiple devices a set of states, e.g. when one of a set of light switches is turned on.  Can be configured to restart the WAIT if one of the state changes reoccurs.  Handy if there are multiple motion detectors controlling the lights.

  • OnEvents (restartable) - used to trigger a rule if any the indicated external event occurs.  Can be configured to restart the WAIT if the event is sent again.  OnEvent events can be sent from AM Remote, over the REST interface, IFTTT notifications, or via SMS (see the MppSMSer app in Betas ).

  • WhenClicked - use double clicks of a swtich to trigger alternate actions (e.g. turn on all lights)

  • ValueChange, ValueAbove, ValueBelow, ValueIs, ValueUpdate - Triggers on an analog range, e.g. the power from a Wemo Insight or an HS110, a dimmer brightness level, the temperature sensor on a WemoHeater or a custom analog device measuring voltage, current, humidity, power, temperature, etc.  Note that this trigger only fires once; e.g. a "ValueBelow" trigger will only be fired again if the value exceeds this threshold or the rules engine is restarted.  ValueUpdate works best with devices that report periodically (e.g. battery powered on wakeup) - the analog value is tracked from each report.

  • WhenTrigger - when the sensor of a device like a Maker is triggered or untriggered

  • WhenMessage - when the message assigned to a device changes or has a given value

  • WhenBattery - Triggers below an analog value.  Useful for battery powered devices reporting voltage as an analog value.  Pair with actions like "SendGmail" using the substitution values for notification.  This trigger only fires when the analog (battery) value is below the threshold.  Use the device's "delta" setting to limit the trigger frequency.

  • OnStart - triggered when the rules engine is started or restarted.

  • LongPress, ShortPress - trigger events from devices that support long press (ESP8266 devices).  A press event will either be long or short, use to distinguish from normal state changes.  Note that these triggers occur on the trailing edge of the active transition (unlike on/off states).

  • WhenCompare - compare two analog device values, triggering when the reference is above, below, or equal to the source.

  • WhenMissed - used to monitor and report missed events within a given period (minutes).  Events are External Events (like OnEvents).  For example, use this trigger to monitor one or more battery devices for checkin events - if the checkin period is 1 hour, use 66 minutes (1hr  + 10%).  Use an action like SendGMAIL where the subject/body references "&trigger;" to be notified if a device is delinquent (the &trigger; will identify the delinquent event/device).  This can be used to detect failed devices, e.g. when a battery runs down.

  • NoActivity - used to monitor and detect if one or more devices fails to change state within an activity period (in hours).  For example door or motion sensors to notify via email suggesting a wellness check, or to report if a battery device has not triggered recently and may require a battery change. 

  • Deprecated:

    • WifiConnected/WifiDisconnected - use the Wifi Status device

    • PowerConnected/PowerDisconnected - use the Power Status device

    • PowerAbove/PowerBelow - use the Value triggers.

Conditions

• • ActiveTime - enable time of day ranges for a rule to be active, including times relative to sunrise or sunset

  • ActiveDays - which days of the week a rule should be active

  • ActiveMonths - of the year a rule should be active (e.g. xmas lights on only in December)

  • DeviceStates - enable the rule when ANY ONE of the devices specified is in ANY ONE of the indicated state (these are OR conditions).  Uuse multiple DeviceStates conditions if all of the devices must be in the given state (for AND conditions), e.g. only when all switches are ON.

  • ValueAbove, ValueBelow, ValueIs, ValueBetween - for Analog devices like the WemoHeater, Wemo Insight, HS110, dimmers, custom analog devices, etc.

  • DeviceTrigger - enable the rule when a sensor on a device like a Maker is reading triggered or untriggered

  • FlagsState - check the state of flags set in actions (for state engine type decisions).  On restart flags are all off; use the OnStart trigger to set them up if required or set the "persist" setting in AM Manager for that flag device.

  • DeviceMessage - when the message assigned to a device has a given value

  • ErrorMessage - when the error message reported by a device has a given value

  • DeviceCompare - when an analog device value is are above, below, or equal another.

Actions

Actions can be ordered (do earlier/later) and there is a Pause action.

• • SetDevices (restoreable) - set one or more switches to off or on.

    • Optionally use restore to return to the original state after the given time.  

    • "if applied" on the restore means the restore action will only be started if this action changes the targets, and all triggers are treated as restartable/interruptible.  DO NOT use restartable/interruptible on the triggers when using "if applied" on the action.

    • To cancel an "if applied" restore use a WhenDevice "off" trigger for the target(s) to the rule.  Turn the device off and back on to suppress the restore (auto off).  Alternately use a separate rule, e.g. use a long press to trigger a rule with an "InterruptEvents" action.

  • Toggle (restoreable) - toggle one or more switches.  Optionally toggle again after the restore time.

  • SetMomentary - use with devices supporting the momentary function that allows them to switch back even when no longer connected (the timer is kept by/on the device).  Handy for power cycling the router used for the devices.

  • SynchronizeDevices - changes a set of target switches to match the state of an incoming WhenState trigger.

  • ExclusiveDevices - when triggered with a WhenState "ON" event all of the target switches (other than the trigger device) are turned off.

  • Away - randomly turn devices on or off (or toggle) to give the appearance of an active location.  Away actions are timed by "delay" (till on) and "restore" (how long to stay on) values.  The time used for each is the sum of two random values (new each cycle) in the given range (minimum 1 minute).  For example a restore time of 3 would leave the light on for 1 to 6 minutes, usually about 3 minutes.

    • Use a trigger like OnSchedule for sunset or a set time to start the away action.  The action begins with a delay - meaning for example the light will turn on AFTER the first delay period.

    • End the action with an ActiveTime condition, say sunset to sunrise or midnight.  The away action stops after the next restore when the condition is false (so the light may stay on longer than the active period).  The away rule can also be cancelled immediately with an InterruptEvent rule (use "wait" random for variety).

    • See also the wait random for a single on/off action.

  • Flash - blink (or stop blink) a device using the provided period.  For example, flash the outside lights if a security alarm is triggered, stop if restored.

  • SetAttributes - for setting attributes in the wemo devices that use them, e.g. the heater or air filter.

  • Refresh - force a recheck of device states (perhaps firing other rules).  This will cancel any actions previously submitted to the device (SetOn,SetOff, etc).

  • SendHTTP - GET, PUT or POST to a web page.  Trigger other rules by event name on success or failure.  Choosing SetMessage targets will cause the body of the response to be read and set into the message of the target devices.

  • SendReachable - Test an IP for isReachable.  Trigger other rules by event name on success or failure.  Choosing SetMessage targets will cause the result to be set into the message of the target devices.

  • SendSMS - send SMS (TXT) message.  Only on activated phones

  • SendGMAIL - send GMAIL to target (you need to set/select the Gmail Rules Account)

  • SendTTS - cause the device to utter the given phrase (android only).  

    • By linking your WemoServer device to your Dot/Echo via bluetooth you can make announcements (e.g. Garage Door is Open).

    • By using "cast" to send audio from your WemoServer device to your Google Home device you can make announcements using the SendTTS action.

  • SendNotification - send an android notification to all AM Remote clients connected to AutomationOnDrive  for this AM server (android only, clients must be re-connected using the AM Remote refresh button if the AutomationOnDrive server is restarted).

  • PlayNotification - play a notification sound on your android server device (android only).  Duration in seconds, 0 plays the sound once.  Add media sounds using your android notification sound settings.

  • PushBullet - send a PushBullet "note" to the target's devices.  Target is an email known to your PushBullet account, title and message use subtitutions (see below), and the token comes from your PushBullet account settings Access Tokens (for APIs).

  • SetBrightness, SetColor, SetTemperature - Dimmable device actions (the device must of course also support that action).  WemoLEDs is required to use this action with the Wemo Link.

  • CycleColor - for color devices only, cycle smoothly through colors using the provided change in degrees (1-360) over the period provided.  The rule will run until any conditions on the rule are no longer true.  Specifying a change of 0 uses a random value 0-60 degrees with immediate changes each period.

  • SynchronizeBrightness - changes a set of (dimmable) devices to match the state of an incoming device brightness value or a pre-defined source device.

  • ChangeBrightness - If the device is on change it's current brightness up or down by the specified amount (the device must of course also support that action).  WemoLEDs is required to use these actions with the belkin link.

  • RestoreBrightness - If the device is off, restore brightness (and color or temperature) to the values when last on (the device must of course also support that action).  WemoLEDs is required to use these actions with the belkin link.

  • PrepareBrightness - Set Dimmer brightness without turning it on (for example, set nightlight mode at bedtime, full bright early evening).  Only the Wemo Dimmer supports this action at the time of writing.

  • TriggerEvents - fire any OnEvents triggers with the given events

  • InterruptEvents - cancel any rule waiting or any action restoring for rules with any of those events in an OnEvents trigger.

  • SuppressDevices, UnsuppressDevices - prevent a device from triggering a rule, e.g. turn off a camera motion detector for a few seconds when turning off the light it controls

  • SuppressEvents, UnsuppressEvents - prevent an event from triggering a rule

  • EnableTags, DisableTags - enable/disable the identified rules

  • BroadcastIntent - send an android broadcast intent, e.g. to Tasker, Automagic, or other android app (available on android only).  The applicable substitutions (see below) are added as string extras to the broadcast intent, e.g. as setExtra("udn","&udn;")

  • IftttMakerEvent - trigger an event on the IFTTT Webhooks (fka Maker) channel.  Check here: IFTTT WebHooks Service for more info, follow the "Documentation" button for your personal hook key.  Don't use incoming as it's not secure!  Use IFTTT notifications to the AM Server device to report incoming events from IFTTT.

  • DscCommand - if you're running the DscServer and WemoServer on the same android device you will find the DSC status, zones, and partitions are available for use in the WemoServer and rules engine as triggers and conditions.  This action allows you to send a panel command directly to the DscServer (android only).  See DscCommands for the command format.

  • WriteLog - write an event to the AutomationManager log to help with debugging.

  • SendLog - send the AutomationManager log to help with debugging using GMail.   Note the log can be large, sending can be problematic to some target accounts.  Use SaveLog in this case.

  • SaveLog - save the AutomationManager log to the file system to help with debugging.  On android the file is saved to local device storage/ Android/data/mpp.android.wemo/files/Logs/<filename>.  The java WemoServer will save to the current directory.  File names can use substitution variables.  Use a file system explorer to find and then open/share/send the file to where it is most easily examined, e.g. a PC, Google Drive, etc.

  • SetFlags - set or clear flags used in conditions

  • SetMessage - set a message into a device

  • Execute - execute (run) a device command (rooted androids or java WemoServers)

  • Pause - between actions, time in seconds.  Note the pause is blocking - no other rule will be executed while this rule is paused (only one rule is executed at a time).  Keep it short!

  • SetThermostat - for use with WifiThermostat allowing you to set the thermostat target temperature either directly, or to bump it up or down (like "Ok Google make it warmer in here") (android only)

  • IsReachable - uses the provided ip address or hostname to check whether the host is reachable.  If a port is provided the check is made by connecting to that host/port.  If a port is not provided the check is performed using android InetAddress.isReachable() using ICMP echo.  Use the "success" or "failure" events to trigger a rule to take any necessary recover actions.  No need to use this for AM managed devices - use a device trigger on the error state instead.

  • SetIgnore - use to ignore (or un-ignore) devices when you know an event/action has caused a device to go offline.  For example when using the rules engine on a personal phone wifi disconnected can be used to ignore devices left at home.

  • SetValue - set the level for custom devices (e.g. MppLevel), values are set using the range (%s).

  • Coordinate - when triggered by a value change by an analog device (any device showing a numeric value, e.g. dimmers, temperature), this action can be used to translate from the incoming value to set a value on the target: CoordinateBrightness, CoordinateHue, CoordinateSaturation, CoordinateTemperature (K).  For example, translate a temperature to a bulb colour.

  • SynchronizeValues - trigger with the devices that use values (e.g. MppLevel).  SetValues will be synchronized across all.  Be sure to use devices with the same range!

  • SynchronizeThermostats - synchronizes thermostats with an analog value.  Trigger with thermostats to be synchronized or temperature (analog) device to be followed.  Be sure to use devices with the same range and units!

  • SetTracker - use with custom Tracker (Analog) flags for tracking or counting (increment/decrement) trigger events.  ValueChanged triggers can be used to provide the incoming value to be tracked.

  • TrackValue - match an analog output device to an input analog value, e.g. MppLevel to an MppSensor.  Use a "ValueChanged" trigger for the analog sensor to be tracked.  The target analog output will be matched (by %) to the (analog) device associated with the trigger event.

  • PostData - post (record) device data to a google sheet on Drive.  Available on android only, requires AutomationOnDrive to be installed and running.  For "FileId" copy/paste the sharing or edit link from Google Drive.  For "Sheet" use the name of sheet to update (from the sheet file tabs).  For Columns add columns in order.  Keyword substitutions for the trigger event (see below) can be used for the sheet name and column values.

  • PostUsageData - post (record) usage data (sensor and switch on times) to a google sheet on Drive.  See "PostData" for google drive setup.

  • PostPowerData - post (record) power consumption data  (power devices only) to a google sheet on Drive.   See "PostData" for google drive setup.

  • FileData - appends a line with that value to the file in a folder.  Use the log to find the absolute file location.  Substitutions from the trigger event will be applied to the file and folder names, and to the value.

Keyword Substitutions 

For SendGMAIL, SendSMS, SendHTTP, BroadcastIntent, PushBullet, PostData, FileData, and WriteLog actions.  Values are taken from the event firing the trigger and will be substituted for &keyword; in the text sections of these actions.  Keywords:

• • udn - from device triggers

  • state - from state triggers

  • location - of device for device triggers or IP from ExternalIP trigger

  • external - event name from external triggers

  • source - url, ip, etc for external triggers (if available)

  • name - friendly name of device for device triggers

  • power (Insights)

  • value (Analog sensors)

  • VALUE (int, rounded analog value)

  • now (long milliseconds)

  • message - message from WhenMessage triggers

  • error - error (if any) from device triggers

  • NOW (date/time text)

  • when - rule was triggered (long milliseconds)

  • WHEN - rule was triggered (date/time text)

  • rule - that was fired

  • trigger - that was triggered

  • type - text type of trigger

Custom Devices

Custom devices can be used on an AM Server to increase the capabilities of your home automation.  Some devices have a "persist" setting in the submenu to preserve state across engine restarts.

Use the "Find/Search" menu in your AM Manager server to add custom devices:

• • Flag - e.g. as a local trigger, condition, etc.  Supports on/off.

  • Analog Tracker - a local analog device whose value can be changed from the AM Manager UI or with rules.  E..g as a thermostat set point in your rules.

  • Color Flag - a local analog device whose value and color can be changed from the AM Manager UI or with rules, displays assigned or rule driven colors

  • Event - represents an OnEvent event trigger as a device.  Automatically added for each rule trigger, supports "on", automatically turns off after 500ms.

  • Remote AM Server Event - add a device on your carry phone or an android console that can directly trigger an event on your AM Server (while you're at home, use AM Remote & AM Remote Widgets when away).

  • Weather - configure weather devices (by location) to monitor temperature, humidity, wind, rainfall, etc.  Uses the OpenWeatherMap API (register for a free API key to use in AM).

  • ExternalIp - periodically (every 60 minutes) checks ifconfig.me/ip to find your router external IP address.  Use the trigger "WhenMessage" for this device to execute an action when your external IP changes (e.g. send yourself an email containing &message. so you can update your remote HTTP clients).  When creating the device you can use to an alternate IP such as http://icanhazip.com/.

  • Thermostat - a tracker (for set point) plus associated with devices in AM to support the thermostat function: analog device for current temperature, binary switch as the heat/cool activator.  Thermostat type (heat/cool) indicates whether to turn on the switch below or above the set point.

  • HTTP Devices - integrate devices with a simple HTTP interface into AM by defining the necessary urls.  AM can parse simple text or json responses.

    • Sensor - on/off

    • Analog - on/off and a float value

    • Switch - on/off state, on/off commands

    • Dimmer - on/off state, on/off command, set % brightness

    • Slider - on/off state, on/off command, set value within min & max

When running on android these devices can be used in the defined rules (use "Add Phone Management"):

• • • Device Battery (aka Battery) - a device reporting the battery charge state.  Any error status indicates a battery problem.  The device will be on when charging, off when not.

    • Device Charging - on when the phone is charging, off when not.

    • Device Wifi - on when the wifi is connected to a preferred wifi and the AutomationServer is running, off when not.  Turning this device on/off will enable/disable wifi.

    • Device WifiLock - on when the wifi locked active.  Use when you're allowing the rule engine to sleep; lock the wifi on to connect and execute commands.

    • Device SMS - on telephony devices use this device to whitelist numbers that can send it SMS messages.  Use the messages in WhenMessage triggers and conditions.  Deprecated by google/android.  See  the MppSMSer app in Betas for an alternative.

    • Device Screen - controls the screen lock as on or off (allow dimming).  Note that on some versions of android the OS screen dimming/sleep settings override the lock.  Re-enabling the lock may temporarily restore the screen on state.

And custom IFTTT devices.  Use these to integrate IFTTT events and to monitor or control IoT devices that are integrated via IFTTT from AM (note there will typically be a 2-3 second delay for actions/events).  IFTTT setup instructions are available in the editor for each device.

• • Event Handler - handle events from an IFTTT "THAT".

  • Switch/Sensor Monitor - track changes to a sensor or switch monitored by IFTTT

  • Analog Sensor Monitor - track changes to an analog reader/sensor/monitor available through IFTTT (e.g. temperature, humidity, rainfall, etc).

  • Switch Control - monitor and control an IFTTT managed switch

  • Dimmer Control - monitor and control an IFTTT managed dimmer switch

How do I add the WemoServer widget to enable the rules?

WemoServer engine must be running before rules will execute (other than as tests).

For a conventional AM Server, configure AM on your server device:

• AM Preferences "Refresh and Charging" as "Refresh always" (unchecked)

• AM Preferences "Refresh and Wifi" as "Refresh any time..." (unchecked)

• AM Server "Let Android Sleep" as "device will stay awake" (unchecked)

• AM Server "AM Server Rules" as "Rules rae being applied" (checked)

• AM Server: "Rules on Wifi" as "Rules are active on any connection (unchecked)

Add the WemoServer widget to one of your home pages to enable the engine.

• • On later versions of android open your "all apps" view.  Look for the widget tab at the top and scroll/swipt to find the WemoServer widgets.  Long press and drag it to a convenient place on your home screen.

  • On earlier versions long press on your home screen, pick "widgets" from the menu, then scroll to find it. 

Any of the WemoServer widgets will do, the small one (no devices displayed) is usually the best choice.  It will look like this, the enabled services should be green:

Touch the widget to open WemoManager, you'll find the WemoServer configuration in the settings menu.  Confirm the WemoServer rules in the WemoManager menu are enabled.

Activate "always on while charging" in android settings "Developer Options".  If "Developer Options" is not available, go to "settings>About>Software Information>Build Number" (sometimes it's under "more").  Tap "Build Number" seven times to enable it.

Check your advanced wifi settings to confirm wifi will not be turned off to save power.  If you have a task killer on your device add the WemoServer (and WemoOnDrive if you're using it) to the list of exceptions.

On some android devices you may need to set the screen to stay on at all times.