This is the MppDevice interface used by AutomationManager/WemoManager and the ESP8266/ESP32 devices that use the MppDevice Configuration and Firmware. You can implement this same interface to adapt any device to AutomationManager. If you're running on an ESP device you can extend any of the existing device types using an Extension or starting with the MppCustom device, or with arduino an MppServer and MppDevice.
MppArduino will connect to an MppDevice to provide a remote console for command line access.
Device calls (resource is the target UDN, see below) that should be supported in a device (depending on type):
PUT http://ip:8898/state/udn?state=[true|false] - set the device relay state
PUT http://ip:8898/state/udn?state=[true|false]&momentary={nnn} - set the device relay state for nnn milliseconds then set to the "not" state
PUT http://ip:8898/state/udn?toggle=true - toggle the device relay state
PUT http://ip:8898/state/udn?toggle=true&momentary={nnn} - toggle the device state for nnn milliseconds then toggle back
PUT http://ip:8898/state/udn?level={nnn} - set a level/stepper device output value
PUT http://ip:8898/state/udn?level={nnn}&time={mmm} - set a dimmer device output value, transition time in ms (0 is immediate)
PUT http://ip:8898/state/udn?value={fff}&time={mmm} - set an analog tracker device output value, transition time in ms (0 is immediate)
PUT http://ip:8898/state/udn?hue={nnn}&sat={nnn}&state=[true|false]&time={mmm} - set hue 0-360, sat 0-100%, transition time (ms) for color output
PUT http://ip:8898/state/udn?temperature={kkk}&state=[true|false]&time={mmm} - set temperature, transition time (ms) for color output
PUT http://ip:8898/state/udn?red={nnn}&green={nnn}&blue={nnn}&state=[true|false]&time={mmm} - set RGB (0-255), transition time (ms) for color output
PUT http://ip:8898/state/udn?flash={mmm} - start flashing with mmm (ms), flash=0 or a state/toggle PUT to stop
These requests are handled by the MppServer implementation in the library and are optional for custom devices:
GET http://ip:8898/restart - reboots the device
GET http://ip:8898/version - returns the base and device version
GET http://ip:8898/survey - returns a json array of the available wifi signals
PUT http://ip:8898/setup - set the wifi with a JSON body: {"ssid":"your ssid","password":"wifi password"}
These requests are handled by the MppServer implementation in the library and are optional but encouraged for custom devices:
GET http://ip:8898/ - returns a body of JSON array of all managed device states (see below)
PUT http://ip:8898/subscribe - source ip is used for the subscriber. Notifications are sent to this IP on port 8898 as UDP with a JSON body with the current device attributes (e.g. state, value). Subscriptions are valid for 10 minutes and can be renewed any time.
PUT http://ip:8898/name/udn?name=new_name - set the friendly name of the device
GET http://ip:8898/state/udn - where resource is the device UDN of a device. Returns the current device state as a JSON body (see below)
Discovery
A UDP message to 239.255.255.250:8898 containing the string "discovery" will cause the device to respond to the sender with the device discovery information as a JsonArray of JSON from each device it manages.
Management calls (optional):
GET http://ip:8898/defaults - returns a JSON body containing the current configuration settings
PUT http://ip:8898/defaults - change configuration with a JSON body containing configuration updates. Returns the new configuration as JSON.
Asynchronous Notifications
Typically a device will send a state update notification to subscribed hosts (see above).
Update notifications are messages that contain a JSON representation of the device as below. Only UDN and any state or level changes are required, the other attributes are optional and if not present the device definition will not be changed in the AM server.
Update notifications are sent via UDP to subscribers automatically by the MppDevice base library (see above).
Devices can also send direct update notifications over HTTP if confirmation of delivery is needed. These notifications are sent as POST messages to the AM REST server with the format http://ip:4030/devices/{device udn} where the POST body is a JSON notification. The AM REST server must be enabled on port 4030.
When a specific event to be reported to the AM Server is detected on an IoT device a direct UDP message can be sent to the AM Server on port 8898 with the contents "notify {onEventName}" (without braces or quotes). The AM Server will find and trigger any OnEvents trigger that references that event name, or any Event device that is using that event.
Note that HTTP/REST events can also be sent to the AM Server as defined in HowTo over port 4030 (if enabled).
Device (UDN) Types:
Each device (or resource in multiple devices) must be assigned a unique UDN in AutomationManager, e.g.
MppSwitch_nnnnnnnn
where MppSwitch is the device type. The n's can be anything, I use the device MAC (see MppRelay for an example). When the device has multiple on board resources I add a postfix like "_X" where the X is unique for each onboard device (see MppPower or MppRelays for an example).
AutomationManager uses the device type to decide the capabilities to expose for that device. The device type (which is different than the file or bin name) is assigned to a device when it's added/assigned to the MppServer instance to manage in the device firmware. The device type is part of the UDN for each device.
MppSensor: a binary sensor, reporting a binary state
MppAnalog: analog sensor, reporting an analog value and optional state
MppSwitch: on/off relay (with an optional current state) or a device that can be toggled
MppMomentary: an MppSwitch with an onboard timer for short duration state changes
MppPower: an MppMomentary with an analog value (usually power use)
MppLevel: dimmer or stepper - integer level
MppTracker: analog output - float value
MppColor: dimmer/temperature/color RGB based bulbs
MppSleeper, MppAlert, MppReporter: digital sensors that sleep (to conserve battery live) with an analog battery voltage report
MppSetup: a setup device, used to enable OTA upgrades
Discovery and state update information (JSON) (Notifications and State updates)
udn - unique, prefixed with a UDN type
mac - string, optional
firmware - string, optional
name - friendly name - string, optional
location - ip address
state - optional, default is unknown. values: on, off, standby, true, false, unknown
value - optional, default is unknown
float for analog sensors, missing means not known or not used
float for current output level for analog output
int brightness % for dimmers/bulbs
level - optional, for integer output value, brightness % for dimmers/bulbs
hue, saturation 0-360 degrees / 0-100% for color devices
temperature, minTemp, maxTemp in degrees K for temperature devices (RGB)
red,green,blue - current RGB (0-255) values for color devices
JSON example (for an MppSwitch):
{ "udn":"MppSwitch_deviceMAC", "name":"My Device", "location":"192.168.1.10", "value":15,"state":"on" }