Maker API New Features

🚧 Developers
1

With Release 2.1.6 we are introducing a couple of new features to Maker API.

Multiple parameters to device commands

When sending a command to a device via an endpoint, it is now possible to specify multiple parameters for the command. These parameters go in the [Secondary value] field of the endpoint, and are separated by commas. Command parameters can be integer, decimal or string. It's up to you to be sure to use the correct type of parameter.

Example sets a lock code for slot 3, code 4321, named Guest:

http://192.168.1.156/apps/api/3845/devices/1321/setCode/3,4321,Guest?access_token=YOUR_ACCESS_TOKEN

HTTP POST to URL for device events

Instead of polling devices through Maker API to learn of device events, just enter a URL for events to be sent to via an HTTP POST. The body of the POST will contain a JSON object with the device event details:

    data = [name:              event.name,
            value:             event.value,
            displayName:       event.displayName,
            deviceId: 		   event.device.id,
            descriptionText:   event.descriptionText,
            unit:              event.unit,
            data:              event.data]

You can enter the URL to use in the Maker API UI, or you can send it to an endpoint. Example below (the endpoint URL to use is displayed in Maker API UI):

http://192.168.1.156/apps/api/3845/postURL/[URL]?access_token=YOUR_ACCESS_TOKEN

Replace [URL] with actual URL to send POST to (URL encoded). Once this URL exists, either from hitting Done after entering it into the UI, or once the URL is sent to the endpoint, Maker API will start sending every device event for the selected devices. There is an option to select that Location events also be sent by Maker API along with device events.

To clear the URL, which stops the event stream, omit the /[URL], like this example:

http://192.168.1.156/apps/api/3845/postURL?access_token=YOUR_ACCESS_TOKEN

7 Likes
2

holy crap!!! @bravenel this is AWESOME! But, now I worry that this means the web sockets are going away. :cry:

3

Web sockets are not supported, and may very well go away. This is the recommended method to get device events.

2 Likes
4

OK. Have it up and running. So far so good. I'll poke around on it some more - thanks!!!

REQUEST 1: It would be nice if UNIT was passed in the JSON as well. Not the end of the world, but I think it is poor form to pass a number/value with no units/context in general.

BUG 1: EDIT: Not a bug. Maker API uses the capabilities listed in the driver to know what to subscribe to. My hubconnect stub driver did not have the needed capabilities.

Not all events for a device get passed via the POST message. Example - I use hubconnect with GE Motion Dimmers, using the HubConnect Dimmer driver. The HubConnect Dimmer driver doesn't expressly support motion sensors, but I never worried about it since the events get passed to the device anyway (see screenshot below). I'm sure I can work around this by making a more proper stub driver, but as the events show up on the repeated side, I don't think I should have to.

With the Maker API push events, only the SWITCH events were passed, and the MOTION ones were not - at all - even though they show up in the device's event table...

Expected behavior: all events that make it to the event table should be POSTed by Maker API.

Device events shown below. The SWITCH events were POSTed, but none of the MOTION ones were.

Capture
Capture.PNG1423×388 33.6 KB

Device details for the device, notice the motion state populated as expected.

Capture
Capture.PNG1162×1185 45.1 KB

1 Like
5

Edit: I've tried adjusting the stub driver for the device above 5 different ways, but the motion events are never POSTed via Maker API - just SWITCH and LEVEL events.

Thoughts?

My guess is that even though the motion events are showing up, because I'm specifying it as a dimmer in HubConnect that the motion events are happening in a way MAkerp API doesn't see. I'll probably need to stop bringing it across as a "dimmer" and do something different with the driver. Annoying, but not impossible.

6

Maker API looks at the device capabilities to determine what events to subscribe to. So your device must not have the motion capability. That can be easily fixed in the driver. It has to subscribe to get the events, and it has to know what it can subscribe to.

1 Like
7

I added both sensor and motion sensor capabilities to the stub driver, but still no POST events.

I did not try removing the device from Maker API and adding back again, though after that change. I'll try that when I get time.

8

Just open it and hit Done.

9

Look at its App Status page to see its Event Subscriptions.

10

That fixed it. Thanks for the tips. I always forget to look at the app status...

Now that I know it is specifically doing subscriptions based on capabilities, it should be easy to get them all working as expected.

Cool feature, Thanks!

1 Like
11

What's wrong with WebSockets? They seem like the natural choice for the MakerAPI, and they appear to be working well. Why would that need to change?

(I'm not against change; I'm just wondering why WebSockets would be considered "unsupported.")

Andrew

2 Likes
12

@bravenel, is there a way to activate the location events via an endpoint? We can set the remote URL via an endpoint but not enable the location events. In addition, location events can only be enabled once a remote URL is set. It will be confusing to guide users through this process for any kind of integration that is being build

13

I'm all for more remote configuration. However, in this case I don't see it as a big deal.

The end user still has to know enough to install Maker API, record/find the app #, record the auth/token, and add devices to it (wither all or select), so they have to go into the Maker API anyway.

Having them check the option at this time seems incremental to the other activities.

1 Like
14

I am working on updating my homebridge plugin.
That plugin will need to open a port and it will tell MakerAPI where it is located to receive the events based on the postURL endpoint. The user would then have to go back into MakerAPI to enable the option after the plugin was started once. Really counter-intuitive if you ask me......

1 Like
15

Good point - I hadn't thought of that use case.

Maybe they will add it in a future release (after they add UNITS in the JSON response, since I asked 1st [<- that was a joke :smile:]).

2 Likes
16

Personally, I LOVE the websocket implementations in HE and have built a lot of my house infrastructure around them. But, I did it in a way that if HE did close them off, I could recover pretty quick. However, we, the community found the sockets and they were used intended for internal use only. I totally get that. But, I would also love to see a Maker API: Sockets implementation as well.

1 Like
17

Agreed, presumably web sockets has a much lower overhead (since it's already doing it anyway and an extra client is just a subscription on the socket) compared to having to do a HTTP POST for every event.

I actually just moved my own integration from the old ported ST MQTT/REST plugin (Hubitat MQTT Integration) to a web sockets and maker api equivalent for this reason. It would seem a step back to revert to a http post version .....

3 Likes
18

@bravenel, I have a second request :slight_smile:

After someone sets the endpoint URL via the postURL request, can you start sending events via the event stream. Right now, the user needs to go back into MakerAPI and hit done.

2 Likes
19

There's pros and cons to both. The HTTP Post approach means that it's stateless and doesn't need to keep resources open continually; it's a stateless, fire and forget mechanism and works really well in an environment that has constrained resources. With a socket implementation, the socket needs to be kept open in order to function (due to it being a duplex connection). This places additional strain on the system engine.

So, for HE, going the HTTP Post route makes sense if they are having any kind of resource or contention issues in the system engine. It doesn't require a server process running all the time and HTTP connections/DB objects can be disposed each and every time an event fires.

20

Isn't it already open anyway though?

I thought that was why we already "found" it, because it was already in use internally for dashboards and general UI? Similar for the "logging" socket?

My assumption (perhaps incorrectly) is that it's just a broadcast on those sockets which is happening anyway, another client subscribing to the socket doesn't add much overhead in comparison to an HTTP POST that has to wait for the receiving system to respond.

I know if I turn off a dozen devices in a Scene I get all those events pretty much instantly on the web socket, whereas the Maker API route would be 12 individual HTTP POSTS outbound.....

1 Like