Configuration and Updates (V1/V2)

Device configuration and updates are done using AutomationManager.

To begin you first load the MPP firmware onto the ESP device (see Flashing Firmware) and connect it to your wifi (using a reserved IP address in your router DHCP service is best). Record the device IP address.

1. Open AM Manager
2. Touch menu>ESP8266 Devices to open the MppDevice manager
3. Wait for MppDevices to automatically download the current firmware from this site (the files it uses are found below)
   • Touch the refresh button to reload the MppDevices or to recheck the current firmware
4. Touch the search button (or menu>Find MppDevices) and enter the IP address you recorded above if the device is not already known.
5. All known MppESP8266 devices will be shown (use "Forget" for any devices that are no longer used/valid).
6. If the device is new touch it's icon and select the "Change Device Type" option. Device types are described below.
7. You can re-purpose a previously assigned device type. Note that this will change the device's UDN.
8. Return to AM Manager to clean up (forget) any unused or setup UDNs.

This ESP8266 app is also used for base and device specific updates, and to configure the device properties (e.g. pin configuration)

Device Types

See below for details on configuring each device type.

Powered (use an inexpensive USB power block)

• MppSensor - sensing/reporting a binary (e.g. contact switch) state change
• MppSensors - for multiple sensors
• MppAnalog - sensing/reporting binary changes and an analog value
• MppRelay - for controlling an output relay or switch
• MppMaker - combines MppSensor and MppRelay
• MppRelays - controlling multiple relays/switches
• MppToggle - controlling momentary switches, e.g. triggering door remotes
• MppDual - sonoff dual relay controller
• MppPower - sonoff power measuring relay controller
• MppServerDHT - sonoff temperature, humidity sensor with relay
• MppGateway - use with MppContacts
• MppLevel - e.g. custom dimmer or thermostat
• MppStepper - stepper motor with Uln2003 control board

Battery (2.6V - 3.3V, use a pair of AA's or AAA's)

• MppSleeper - deep sleep, wakes on edge trigger or momentary low, long battery life
• MppReporter - deep sleep, wakes when triggered and periodically to report battery condition. Long battery life. Requires GPIO16 to RST connection (use an ESP12).
• MppAlert - light sleep, wakes when triggered (no extra circuit required) and periodically to report battery condition. Medium battery life.
• MppContact - light sleep, wakes similar to MppAlert. Immediate report to MppGateway (no wifi connection delay). Medium battery life.

Devices with Buttons

• Short click for relay toggle (where available)
• Hold for 5s to reboot / retry wifi connection - the WifiLED will flash slowly. Release the button and wait about 10s for it to reboot.
• Hold longer for "AP" mode - the WifiLED will flash quickly. When it reboots after about 10s you can connect to the card's wifi directly and use a web browser for emergency recovery. Once connected use the WemoManager/ESP8266 tool to reconfigure it.
• If the WifiLED is flashing slowly the device is not able to connect to your wifi. Double check the SSID and password.

Properties and Device Customization

The pins in this table are the values to use in the Properties. They match the pin numbers of the ESP8266 and do not (normally) correspond to the pin outs of the device board connectors. See your particular board for details.

Notes [n]:

1. With wemos relay shield
2. Custom wiring, any available pin except pin 0/GPIO16 which does not support interrupts
3. Off when connected
4. Pin 9 is the RX0 pin so no commands via USB port but is otherwise a good choice.
5. If pin 3 is low at power up the device enters flash mode.
6. Pin 4 must be high on boot for normal startup.
7. The basic sonoff exposes pin 5 / GPIO14 on pin 5 of its programming header
8. Pin 0/GPIO16 (usr button) cannot be used as a sensor/interrupt
9. Wemos mini switch is connected to RST
10. This is the spring connected to the glass touch screen. It's also GPIO0, touching it while rebooting will put the device into flash mode.

Pins on the ESP8266 and typical use (not always the same as the board connectors!):

0/GPIO16 - used for deep sleep wakeup

1/GPIO5

2/GPIO4

3/GPIO0 - low at power up enters flash mode

4/GPIO2 - high at power up for flash boot

5/GPIO14

6/GPIO12

7/GPIO13

8/GPIO15 - high at power up for SD card boot

9/GPIO3 - RXD

10/GPIO1 - TXD

11/GPIO9

12/GPIO10

Use the "Properties" menu to customize your firmware as needed.

Use the "Add" button for properties that are not present.

• WifiPin - pin to follow the wifi state (if separate from LedPin)
• WifiActive - state of the wifi LED when connected (if separate from the LedPin)
• NoMulticast - add as true if multicast is not supported by your router (devices must be discovered manually), advanced
• ip,nm,gw - static IP settings (IP, Gateway, Netmask)
• StaticIp {true|false} - set true for static IP along with the desired ip,nm,gw

Reserved (internal) properties:

• Startup {run|load|fast} - "run" is for normal operation. "load" is for updating files using TCP. "fast" is for MppSleeper quickstart. Don't set this value manually.
• RunMode - the type of device in use. Don't set this value manually.

The LedPin will usually follow the relay or sensor state (depending on device type).

MppAnalog

Is-an MppSensor with the additional of an analog voltage read of the A0 pin. The A0 input can read 0 to 3v3 (max!).

• ButtonPin, WifiPin, SensorPin, RelayPin, Invert, Pullup - as with MppSensor
• ReportInterval - how often the MppAnalog will read and report the ADC value on A0

MppLevel

An analog output device. Use "Extension" to add the desired output when a new level is assigned. State can be used to set the state off/on.

• ButtonPin, WifiPin - as above
• LedPin - reflects the on/off state
• minLevel, maxLevel - set the range

MppStepper

An analog output device for managing a stepper motor via a Uln2003.

• ButtonPin, WifiPin - as above
• LedPin - reflects the on/off state
• minLevel, defaults to 0
• maxLevel - set the range of motion. If non-nil, the location will be calibrated by moving the maximum range back to 0.
• Set ON to move to maxLevel, OFF moves to 0

MppRelay

A standard relay controller providing on/off switching. A short touch of the button will toggle the relay, and the LED will follow the relay state. It can also be used as an indicator since the LED will follow the relay setting. Use a toggle, sync, or follow rule in AutomationManager/WemoServer to link it to other devices.

Note, when using the MomentaryOn/MomentaryOff commands the maximum supported duration is about 1 hour 50 minutes (1:50:00).

• LedPin, ButtonPin, WifiPin (as above)
• Initial {true|false} - relay state at power up
• Momentary {0} - non-zero int for momentary (when not provided on a request). Use with Initial to keep relay in a desired state.
• RelayPin for controlling the relay
• IpCheck {nnn} - Monitoring of a target URL, frequency of check, nnn is 0 (to disable) or 1 to 110 minutes
• IpAddress {url | ip} - IP or URL to check, relay will be toggled for 20s if no response after 20s
• IpPort {nnn} - target port (use 80 for an HTTP server like www.google.com)

MppMaker

A sensor + relay controller similar to a Wemo Maker. A short touch of the button will toggle the relay, and the LED will follow the relay state.

Note, when using the MomentaryOn/MomentaryOff commands the maximum supported duration is about 1 hour 50 minutes (1:50:00).

This device supports Long Press - hold the sensor active for at least 1s to trigger a long press event to the AM Server.

• LedPin, ButtonPin, WifiPin (as above)
• Initial {true|false} - relay state at power up
• Momentary {0} - non-zero int for momentary (when not provided on a request). Use with Initial to keep relay in a desired state.
• Follow {true|false} - If true, the relay will follow sensor (automatic switching). If false, the relay will toggle on sensor change. Set empty to disable (the default).
• Invert - if true the sensor input value will be inverted
• RelayPin for controlling the relay
• SensorPin for sensor input
• IpCheck {nnn} - Monitoring of a target URL, frequency of check, nnn is 0 (to disable) or 1 to 110 minutes
• IpAddress {url | ip} - IP or URL to check, relay will be toggled for 20s if no response after 20s
• IpPort {nnn} - target port (use 80 for an HTTP server like www.google.com)
• PullUp - if true the sensor input will have the pullup resistor applied. Default float
• LongPress - set to true or false (reflecting the active state of your input, usually false). Nil disables the long press command.

MppRelays

A standard relay controller providing on/off switching for multiple relays.

• LedPin, WifiPin (as above, be sure they don't conflict with relay and relay led pins)
• ButtonPin (disabled)
• State {true|false} - relay state at power up for all relays
• Invert - use true for Normally Closed (NC) relays, default/false for Normally Open (NO)
• Relays - pin numbers for each relay (max 8)
  • For wemos d1 (pin == Dn) e.g use: 1,2,5,6,7
  • D1/GPIO5, D2/GPIO4, D6/GPIO12, D7/GPIO13, D5/GPIO14, D8/GPIO15, D3/GPIO0 (default on), D4/GPIO2 (default on)
• Buttons - pin numbers for input buttons, will toggle the corresponding relay (be sure to match order and length with Relays) when clicked (upon release)

MppToggle

On/off controller where the actual state is not known and on/off actions are pulses (e.g. a door lock or similar remote)

• LedPin - as above, not useful
• WifiPin - as above
• Initial {on|off} (pulse to apply on startup)
• OnPin - will be pulsed for a SetOn action
• OffPin - will be pulsed for a SetOff action
• Momentary (duration of pulse in ms)

MppDual

For use with Sonoff Dual only.

Note that the button does not work for wifi configuration (unless you've made the button to GPIO0 modification). 5 clicks of the button within 5s will restart the device, 7 clicks will bring it up into configuration mode to allow you to join and reconfigure the wifi.

• LedPin, WifiPin (as above)
• ButtonPin toggle both relays (wifi control only with modification to GPIO0)
• Initial {true|false} - both relay states at power up
• LedPin - not used

MppPower

Appears as multiple grouped devices to AutomationManager: relay+power, current, voltage.

Each UDN will have a common UDN with an appropriate suffix: _P (relay control plus power), _C, _V respectively.

The Led will follow the relay state.

Requires ITEAD Sonoff Power or equivalent.

For calibration Sonoff uses:

Vref = 2.43, Fosc = 26MHz / 8 = 3250000, Rv = 5 * 470 = 2350, Rc = 0.001

• LedPin, ButtonPin, WifiPin (as above)
• RelayPin for controlling the relay
• Initial {true|false} - relay state at power up
• PowerPin - Sonoff uses pin 5 (default 5)
• VoltAmpPin - Sonoff uses pin 7 (default 7)
• SelectPin - Sonoff uses pin 1 (default 1)
• PowerCalibration:
  • ( 1000000.0 * 128 * Vref * Vref * Rv / Rc / 48.0 / Fosc ) (watts)
  • ( 1000000.0 * 128 * 2.43 * 2.43 * 2350 / 0.001 / 48.0 / 3250000 )
  • default = 11385858
• VoltageCalibration:
  • ( 1000000.0 * 512 * Vref * Rv / 2.0 / Fosc ) (volts)
  • ( 1000000.0 * 512 * 2.43 * 2350 / 2.0 / 3250000 )
  • default = 449811
• CurrentCalibration:
  • ( 1000000.0 * 512 * V_REF / Rc / 24.0 / Fosc) (amps)
  • ( 1000000.0 * 512 * 2.43 / 0.001 / 24.0 / 3250000 )
  • default = 15950

MppServerRHT (Sonff only)

Appears as 3 separate devices to AutomationManager: relay, humidity, temperature.

Each UDN will have a common UDN with an appropriate suffix: _R, _H, _T respectively.

The Led will follow the relay state.

Requires ITEAD's Sonoff DHT board.

• LedPin, ButtonPin, WifiPin (as above)
• RelayPin for controlling the relay
• Initial {true|false} - relay state at power up
• Units {C|F} - temperature units, default C
• DhtDelay - connection delay. Default is 18000 for AM2301, use 500 Si7021. Base firmware 4.1.2 or later.

MppDHT (generic)

Appears as 2 separate devices to AutomationManager: humidity, temperature.

Each UDN will have a common UDN with an appropriate suffix: _H, _T respectively.

wemos d1 DHT shield v1 uses the DHT11 which is limited to 1C degree of precision .

• LedPin, ButtonPin, WifiPin (as above)
• Units {C|F} - temperature units, default C
• DhtDelay - connection delay. Default is 18000 for AM2301, use 500 Si7021. Base firmware 4.1.2 or later.

MppSleeper

MppSleeper is a battery powered device that wakes when the input is toggled to send an event and report battery voltage.

Battery usage is very low in deep sleep, < 100uA. Each trigger results in 20s or so of 70mA power use. You can expect a battery life of years on a pair of AAAs, though less if the device reports often.

NOTE: if your board has a USB interface it is not suitable for battery use. ESP-01's are a good choice, but if there is a power LED on the board you must remove it.

See also MppReporter which will actively report low battery conditions. If you have access to GPIO16, RST and EN and need to monitor the device use the MppReporter. The MppSleeper is generally quicker to send a notification than the MppReporter.

The device takes 3-6s or so to wake and report an event. Using a static IP eliminates the DHCP exchange and can be slightly faster.

• LedPin, WifiPin, StaticIp (as above)
• ButtonPin as above, plus button click triggers event message
• SensorPin - sensor state pin will be reported, toggling state triggers event message
• ServerIp - ip address of the AutomationServer
• IpMessage - OnEvent trigger to send each time device wakes/triggers to indicate a toggle event
• SleepTime - in minutes, max 60 - how often the MppSleeper will wake and check in with the ServerIp. Don't use with IpMessage as a toggle event. GPIO16 must be connected to RST for the timer to work.
• PullUp - if true the sensor input will have the pullup resistor applied. Default float

Use a momentary low signal to trigger.

• Use with a push button (fires on button release).
• Activation on any edge requires a few additional components, see: 3 Way Switches.

Typically you would configure a WemoServer rule to toggle a target device when the IpMessage OnEvent was received. Sensor status is sent but note that events can be missed while the device is waking or is restarted while sending.

The battery voltage is checked when MppSleeper wakes and reports. This voltage is reported along with the state and can be checked and acted upon with a value below trigger.

Using the WifiPin, LedPin, or power LED will add battery load. If there is a power LED it is best to remove it.

To update or configure the device, put the WemoManager/ESP8266 Devices app into "configure" mode for the MppSleeper device. Toggle the the sleeper device input, when it wakes WemoManager will find and start it in configuration mode. Remember to return it to "sleeper" mode to save power if it's running on batteries!

If you can't recover it using the ESP8266 Manager app you will need to take the plug-able ESP01 card from it's location and connect it to a computer using the USB adapter. Use the LuaLoader or equivalent to restart it, during the reboot cancel the timers and then enter the command 'restart("run")' to restore it to setup mode. Once the reboot completes AutomationManager can be used to manage the device configuration.

Set the device into switching (sleeper) mode (which reduces battery use) using the AutomationManager ESP8266 management utility. It can then be returned to service.

Connection at power up may be a little faster if StaticIp is used.

NOTE: needs the nodemcu_integer_4mpp.bin that includes ADC support from Nov 2017 or later.

MppReporter

A battery powered device that wakes up when the input is toggled, periodically to report liveliness, and to check battery life. Power consumption is very low and using a longer report period greatly extends battery life.

Battery usage is very low in deep sleep, < 100uA. Each trigger results in 20s or so of 70mA power use. You can expect a battery life of years on a pair of AAAs, though less if the device reports often (a typical use would be daily reports).

NOTE: if your board has a USB interface it is not suitable for battery use. Bare ESP-12's are a good choice, but if there is a power LED on the board you must remove it.

Hardware requirements:

GPIO16 tied to RST

Low going Edge trigger on sensor change to EN (open/high otherwise)

For edge triggering see: 3 Way Switches.

The device takes 3-10s or so to wake and report an input event. Using a static IP eliminates the DHCP exchange and can be slightly faster. If faster reporting is needed and battery monitoring is not required use the MppSleeper.

• LedPin, WifiPin, StaticIp (as above)
• SensorPin - sensor state pin will be reported, toggling state triggers event message (while awake)
• ServerIp - ip address of the AutomationServer
• IpMessage - OnEvent trigger to send each time device wakes/triggers to indicate a toggle event
• IpBattery - OnEvent trigger when the battery voltage is below BatteryMin (check every SleepTime period wakeup)
• IpReport - OnEvent trigger to report the device is still active. Sent every (SleepTime * ReportCount) minutes.
• BatteryMin - threshold (mv) before the device begins to report a low battery condition. 2500 is very low, 2700 is safer.
• SleepTime - in minutes, max 60 - how often the MppReporter will wake to check whether to send a report. GPIO16 must be connected to RST for the timer to work.
• ReportCount - the number of SleepTime wakeups before an IpReport is sent.
• PullUp - if true the sensor input will have the pullup resistor applied. Default float
• ConnectDelay - when waking a delay is needed before the attempt to connect, duration depends on your network. Default 200ms, try longer if the device does not connect.

Typically you would configure a AM Server rule to take action (e.g. toggle a target device) when the IpMessage OnEvent was received. Sensor status is sent but note that events can be missed while the device is waking or is restarted while sending.

When the IpBattery OnEvent was received you might send an email to yourself (test by temporarily using the properties to cause a low battery condition).

The battery voltage is checked when MppReporter wakes on its own or is triggered. This voltage is reported along with the state and can be checked and acted upon with a value below trigger. It will also be reported in the case of an IpBattery event.

Using the WifiPin, LedPin, or power LED will add battery load. If there is a power LED it is best to remove it.

To update or configure the device, put the WemoManager/ESP8266 Devices app into "configure" mode for the MppReporter device. Toggle the the device input, when it wakes WemoManager will find and start it in configuration mode. Remember to return it to "sleeper" mode to save power if it's running on batteries!

If you can't recover it using the ESP8266 Manager app you will need connect it to a computer using the USB adapter. Use the MppController or LuaLoader or equivalent to restart it. During the reboot use pause or otherwise cancel the timers and then enter the command 'restart("run")' to restore it to setup mode. Once the reboot completes AutomationManager can be used to manage the device configuration.

Set the device into switching (sleeper) mode (which reduces battery use) using the AutomationManager ESP8266 management utility. It can then be returned to service.

At the command line LightsOn() can be used to exit sleeper mode.

Connection at power up may be a little faster if StaticIp is used.

NOTE: needs the nodemcu_integer_4mpp.bin that includes ADC support from Nov 2017 or later.

MppAlert

A battery powered device that wakes when the input is activated to send an event. It will catch and report every input level change, and (unlike the MppReporter and MppSleeper) does not need an edge triggering circuit. Use this device when you can power it with rechargeable high capacity batteries.

When in light sleep the power consumption is typically < 1mA (I measured 0.75 to 0.9mA). When awake/reporting the consumption jumps to an average of about 70mA. A pair of AA's has about 5000-6000mAhrs capacity (wikipedia) which should provide 6-8 months of power.

NOTE: if your board has a USB interface it is not suitable for battery use. ESP-01's are a good choice, but if there is a power LED on the board you must remove it.

The device takes 3-6s or so to report an input event. Using a static IP eliminates the DHCP exchange and can be slightly faster.

• ServerIp - ip address of AutomationServer
• CheckIn - hours between check in with the AutomationServer over wifi.
• IpReport - OnEvent trigger to send each time device wakes/reports
• ButtonPin, WifiPin (as above)
• LedPin will show the state of the sensor (on or off)
• SensorPin used as the input pin
• Invert - if true the sensor input value will be inverted for the RelayPin and LedPin
• PullUp - if true the sensor input will have the pullup resistor applied. Default float

MppAlert puts the device into light sleep mode (0.5ma-1.2ma).

When a sensor state change is received you might take an action, e.g. use it as a door/alarm sensor. Or use it as a trigger for a remote light switch or controller.

Using the WifiPin, LedPin, or power LED will add battery load. If there is a power LED it is best to remove it.

The device will check in with the server once every CheckIn period (hours).

Use periodic alerts set up a restartable notification trigger - if a state message is not received within the restart/notification period alert that the device is offline.

The battery voltage is reported in the value propery each time the MppAlert sensor is triggered as well as periodically. It's a good idea to set a rule with a threshold, 2.75V is probably the lowest it should be allowed to get. Use the ValueBelow rule trigger to take action on a low battery. For example send an email to yourself.

To return the device to setup mode, press the device button (if configured) while it is starting after a sensor change, or use the AutomationManager ESP8266 management utility (activate the sensor while it is searching). To return to low power mode restart it using the AutomationManager ESP8266 management utility.

NOTE: needs nodemcu_integer_4mpp.bin v4.0.1 or later.

MppGateway

A ESP NOW gateway that will bridge ESP NOW sensors to the AM Server. Peers are monitored for delinquency, any peer that does not report within a 5 minute period is reported as offline (error state).

• ButtonPin, WifiPin (as above)
• PeerMacs - comma separated MAC address of peer (bridged) ESP NOW sensors
• GatewayChannel - communication channel (1-13)
• GatewayKey - 16 byte / 128 bit security key for ESP NOW.
• GatewayCode - any secret string shared with the peers.
• ServerIp - if set, the gateway will send peer update messages directly (and only) to the gateway and to the broadcast IP; subscriptions will not be honored. This reduces the overall load on the gateway and its communication pipe if you have many AM Manager devices, improving response times.

NOTE: needs nodemcu_integer_4mpp.bin v4.2.0 or later.

MppContact

A ESP NOW binary (switch) sensor that will report sensor state changes and battery voltage to an MppGateway.

This device supports Long Press - hold the sensor active for at least 1s to trigger a long press event to the AM Server.

• ButtonPin, WifiPin (as above)
• SensorPin used as the input pin
• PullUp - if true the sensor input will have the pullup resistor applied. Default float
• GatewayMac- MAC address of the MppGateway
• GatewayChannel - communication channel (1-13)
• GatewayKey - 16 byte / 128 bit security key for ESP NOW.
• GatewayCode - gateway secret code
• GatewayPin - if set this pin will be active when the device is awake & sending
• GatewayPinInvert - set to be sure the LED stays OFF when the device is sleeping to save battery.
• LongPress - set to true or false (reflecting the active state of your input, usually false). Nil disables the long press command.

NOTE: needs nodemcu_integer_4mpp.bin v4.2.0 or later.

MppCustom

Loads the file "Custom.LUA" during startup that can contain whatever you need (copy/paste from the other types as examples). You define the discovery information for each device being supported using "setupDiscovery(udn)", then add those resources as keyed (for GET responses) into Resources and into Discovery. Replace (re-assign) CustomHttp for command handling (e.g. setting a relay on).

• Custom - Custom.lua file to load. Default "Custom.lua"

NOTE: use nodemcu_integer_4mpp.bin v4.2.0 with Base 7.0.0 for lower RAM consumption.

Version History

Version 2 (run from flash) download files and version history are here.

Version 1 files are here. No further changes will be made to these files.