MppDevices REST

This is the MppDevice interface used by AutomationManager/WemoManager and the ESP8266 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.

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 device states (see below)

    • PUT http://ip:8898/subscribe - body (optional, source ip is used if missing) is the host address (IP). Notifications are sent to this IP on port 8898 as UDP with a JSON body with the device state. Subscriptions are valid for 10m and can be renewed any time.

    • PUT http://ip:8898/name/udn - set the friendly name of the device with a JSON body: { "name":"new_device_name" }

    • 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.

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.

    • GET http://ip:8898/command?run={command} - runs a command on the device using the commands available via the serial port (e.g. using MppArduino). No response is provided.

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" }