HomeSeer Integration questions

[alexbk66]

Hey Chris @merck. I have now some questions about implementing actions in my HS plugin.

Main problem for me is that the plugin should work with any device supported by BB and SBB. And I guess there’s a lot. And they all have different functionality. So the plugin should be generic enough to support them all.

Currently I do get the list of actions for the device and create control buttons fro each action. Which should work for actions without arguments (Open/Close etc.)

So my questions are:

1. Is it possible to get a list of required arguments for each action? Is it available via API? Or do you have a document?

2. How do I get the confirmation after I execute the action (in generic manner)? I know that I use /v2/devices/{device_id}/state - but which field do I use? Same questions - Is it available via API? Or do you have a document?

3. Similar to above, do you have a list of state replies for all possible devices? SO I can display the state info in HS?

Thank you.

[EDIT] How is it done in other Integrations?

[jacob]

Docs are hosted here: http://docs-local.appbond.com/

The information about relationships between actions, arguments, and state is in the Feature subsection

A side note: we just open-sourced the API docs, so if anyone has any language they’d like clarified, please open an issue here: GitHub - bondhome/api-v2: Bond V2 API Documentation

@alexbk66

How do I get the confirmation after I execute the action (in generic manner)?

Seeing a 204 response should be good enough. If you want to get the state of the device though, you can request the device’s state endpoint. If you’d prefer the state to be pushed to you, and you can listen for UDP packets, you could use BPUP.

@alexbk66

How is it done in other Integrations?

For our own integrations (Alexa, Google Home, SmartThings. All cloud-to-cloud.) we send the action request, check for 204, then wait for state to be pushed to our backend, at which point we forward the state on.

I think a lot of the local integrations are polling for state in a loop.

[alexbk66]

Thank you @jacob.
Actually, are you saying that all possible actions (and their arguments) are listed in the Feature subsection?

It’s good. But would be better to have an API function for getting argument info for given action. Much better for future extension.

[jacob]

@alexbk66

It’s good. But would be better to have an API function for getting argument info for given action. Much better for future extension.

Interesting, hadn’t thought of that. For now, GET actions/<action_name> is unused. Perhaps if we populated that with a type and accepted input, that’d make the API a bit more “discoverable”?

The type would be easy, I’d just need to think if there’s a straightforward way to convey accepted inputs for all possible actions in JSON. I’m open to suggestions.

[alexbk66]

@jacob

Perhaps if we populated that with a type and accepted input, that’d make the API a bit more “discoverable”?

The type would be easy, I’d just need to think if there’s a straightforward way to convey accepted inputs for all possible actions in JSON. I’m open to suggestions.

Would be really great!

One suggestion - as a quick/temporary fix - just return a string from the docs, i.e. {"description": "(integer) 1 = forward, -1 = reverse"}

Later can extend it.

[EDIT] or {"type": "integer, "vals":{"1":"forward", "-1":"reverse"}}

[alexbk66]

Another question. User reported that his fan has 6 speeds (in the app), but the API returns “SetSpeed”, “IncreaseSpeed”, “DecreaseSpeed”. So it looks like the app artificially creates 6 buttons, but internally it uses “SetSpeed”?

Is it possible to get the app button setup to duplicate it in HomeSeer? How do I know that I need to create 6 buttons for Speed? Most fans have only three speeds.

[alexbk66]

I think I found it - “max_speed” property?

[jacob]

@alexbk66

I think I found it - “max_speed” property?

Yes, that’s right

@alexbk66

Another question. User reported that his fan has 6 speeds (in the app), but the API returns “SetSpeed”, “IncreaseSpeed”, “DecreaseSpeed”. So it looks like the app artificially creates 6 buttons, but internally it uses “SetSpeed”?

The buttons are “commands”, which are documented here. The Actions API is built from the list of commands, simplifying it for use by integrations.

[alexbk66]

So “command” is a shortcut for “action” and includes arguments?
API provides function to get the command, but I don’t see how I can execute the command. Or can I?

[jacob]

@alexbk66

So “command” is a shortcut for “action” and includes arguments?

I’d say “Action” is more a shortcut for “Command”. For example, the user records 6 speed buttons, which create 6 commands. If we didn’t have the Actions API, an integration would have to 1) find out the list of command IDs 2) request each one in turn and 3) store in memory this table of available commands.

Additionally, this table would potentially have to be rebuilt pretty often, say if a user later recorded a “Speed 7” button.

The Actions API just takes care of this for you. It collapses available commands into available actions, so you can get all you need in one request. (GET device has an array of actions, looks like the docs are wrong! They show just a sub-endpoint hash)

@alexbk66

API provides function to get the command, but I don’t see how I can execute the command. Or can I?

Yes, with PUT command/x/signal/tx

[alexbk66]

@jacob

I’d say “Action” is more a shortcut for “Command”. For example, the user records 6 speed buttons, which create 6 commands. If we didn’t have the Actions API, an integration would have to 1) find out the list of command IDs 2) request each one in turn and 3) store in memory this table of available commands.

Additionally, this table would potentially have to be rebuilt pretty often, say if a user later recorded a “Speed 7” button.

The Actions API just takes care of this for you. It collapses available commands into available actions, so you can get all you need in one request. (GET device has an array of actions, looks like the docs are wrong! They show just a sub-endpoint hash)

Confused (may be because it’s 1:35 am)
So. The user says he has 6 buttond for speeds (pic. 1).
In my code I get the list of available actions (pic .2).
So the action is “SetSpeed” and I guess it takes argument from 1 to 6.
So “Speed 1” command is the shortcut for SetSpeed(1) action?

[alexbk66]

Ok @jacob, I’m reading the docs. RTFM!

Actions represent a user’s intent, but do not nessisarly map one-to-one onto the commands that are sent to a device.

Bond Bridges operate by translating actions into “commands”. While actions are in a user’s language, commands are in the device’s remote control’s language.

[jacob]

@alexbk66

So “Speed 1” command is the shortcut for SetSpeed(1) action ?

Yes, but I hesitate to call it a shortcut because you’d have to request the whole table of commands to find the action/argument you’re looking for. You then have to store the dictionary of IDs and action/argument pairs, which may be invalidated by the user recording a new command or deleting a command.

In the above case, calling the SetSpeed action with argument 1 (PUT device/<dev_id>/actions/SetSpeed {“argument”: 1}) just transmits the signal associated with the “Speed 1” command. The same thing happens when you directly tx the command’s signal (PUT device/<dev_id>/commands/<command_id>/signal/tx),

Our mobile apps use the Commands API (they use the individual commands to build the panel), but our Google Home, Alexa, and SmartThings integrations use the Actions API (they just need to be aware of available actions). I’d suggest anyone building their own integration to use the Actions API as well, because it requires much fewer GETs to find out what you need to know about a device.

[jacob]

Another advantage to Actions:

The user’s device has a power off Command, as well as 6 speed Commands. There’s no power on Command.

But the user does have a TurnOn Action. This action uses one of the speed commands (that of the last-seen speed) to turn the fan on. So, by using the Actions API you don’t need to think about this relationship between SetSpeed and PowerOff.

[jacob]

One more reason

The user has a ToggleLight Command (just named “Light”). When the user presses this button, it will always transmit the toggle signal, just like the remote.

We expose two Actions: TurnLightOn and TurnLightOff. And we allow users to customize what happens when an unexpected action comes in. Say the Bond Bridge thinks the light is off, but the user asks it to “TurnLightOff” (and, again, we can only toggle the light). There’s two potentially correct behaviors:

1. The Bond is wrong about the light being off, it’s on and the Bond should send the signal, turning it off.
2. The light is really off but the user may not be around to see that it’s off, or the user is, for example, wanting to turn off all lights in their home. In this case, the Bond should ignore the action and do nothing.

The way we handle these two possible behaviors is with the trust_state property, documented here. Situation 1) is the behavior with a disabled trust_state (the default). Situation 2) is the behavior with an enabled trust_state. The commands API doesn’t take these kinds of things into consideration.

[alexbk66]

Now I seem to have better understanding.
So actions are convenience wrappers for commands.
Still I don’t get - if I call SetSpeed(5) - and there’s no corresponding command?

[alexbk66]

@jacob

I’d suggest anyone building their own integration to use the Actions API

Just to confirm - I can do without Commands API, just use Actions?

[jacob]

@alexbk66

Still I don’t get - if I call SetSpeed(5) - and there’s no corresponding command?

You’ll get a response with a status of 400 (Bad Request) with an error message in the body describing the error, in this case it’s something like “invalid argument”. EDIT: actually, for this one, if the argument is above max_speed it gets set to max_speed.

@alexbk66

So actions are convenience wrappers for commands.

Yes, that’s a good way to think of it.

@alexbk66

Just to confirm - I can do without Commands API, just use Actions?

Yes, definitely.

[alexbk66]

Great, thank you @jacob

[merck]

@alexbk66

Just to confirm - I can do without Commands API, just use Actions?

In fact, if you base your driver on the Commands API, your driver will not work with the SBB devices. The Actions API is the higher level portable API.