API Documentation Requests

UPDATE:
NOTE to Community Contributors:
Chris Merck provided this suggestion on 1/20/2020:

ORIGINAL POST:

When ADDING A DEVICE:

  1. Update “type” parameter to include “AC” for air conditioners.
    I tested and this is working (shows in both Android and iOS apps after adding via API), but this parameter option is not listed in documentation – and I expect I just got lucky with my common sense guess working. Also note: the device I added is a placeholder; I do not have an actual A/C unit to test with this

When ADDING A COMMAND:

  1. Provide list of “action” parameters which are available (and any related “argument” values)
    I was able to find TurnOff by querying existing devices and their commands, but PowerOff, PowerToggle, etc were my first common sense guesses and failed due to ‘unknown action’.
  2. Provide list of “icon” slugs
    I was able to find “button_io” by querying existing devices and their commands.
    SIDE NOTE: the “button_io” shows appropriately in Android app with Power label, but only shows as a blank circle in iOS app with no label

When ADDING A SIGNAL:

  1. “bps” seems to be required, at least with IR commands - documentation seems to indicate it has a default value of 40000 if not supplied, but the PUT fails without “bps” defined.
  2. “reps” seems to be required, at least with IR commands - documentation seems to indicate it has a default value of 1 if not supplied, but the PUT fails without “reps” defined.

all testing done 3/7/2019 with BD***** (Snowbird revision) BOND on firmware v 2.5.1-44-g9d5c43d-jacob-uglydb and both Android and iOS apps on v 1.139.0

When ADDING A COMMAND:

  1. Provide a list of other parameters and their respective valid values.
    (e.g., for an action of “StartDimmer”, there is an “action_release” parameter with “Stop” as a valid value for that parameter)

When GETTING LIST OF DEVICES:

  1. Screenshots show curl command mistakenly using -X instead of the correct -H for passing BOND-Token header
1 Like

Is v2/bridge/name (and other elements in v2/bridge/) safe to assume for official and future firmware?
They aren’t (yet) documented in the official spec.
If so, is there an equivalent to bridge and the child elements within v2/ for SBB devices?
(I’ve had to abandon use of my old beta SBB kit for now so it makes it hard for me to check)

1 Like

Thanks for the requests here… we will get some clarifications out!

Yes, they were implemented pretty early on. The documentation was just not properly rendering. (Pull Request).

There is not. All existing SBB devices expose only one device, devices/1. This device has a "name" and a "location". In the event that we add SBB products that offer control of multiple devices, I imagine we’d just go with sequentially-numbered children of devices

Is there an “official” way to differentiate bridges from SBB devices, other than looking at the device IDs? I am thinking something in v2/sys/version that we can rely on that means bridge vs. SBB device?

Maybe target in sys/version would be best? snowbird is the first-generation Bond Bridge, zermatt is the second-generation, everything else is SBB. Or you could just check whether the bridge endpoint exists.

"Execute a device action" lists action_id and device_id as number.

Looks like an unimportant mistake, but for a new user confuses a lot.

image

Good catch!

Pull request for the fix: https://github.com/bondhome/api-v2/pull/5

1 Like

One more question, for the Fan I have “Stop” action - but what does it do?

It is equivalent to DELETE signal/tx, it stops the current signal from transmitting and clears the queue of to-be-transmitted signals. Maybe should be removed in favor of DELETE signal/tx? I assume a lot of clients depend on it now though: It’s used to stop transmitting continuous signals, mainly light dimmers, and is available on every device.

It’s just confusing name - I thought it’s to stop the fan… And not documented.

One more “little” problem: the errors returned have “_” in front of keys, i.e. “_error_msg” - but the documentation shows “error_msg”, etc.

(1) Another request: it would be useful if you could list all possible actions for each device type.

Instead of waiting for emails from my users like “My fan has StartIncreasingBrightness action, but your plugin doesn’t show it”…

(2) And Question: action API shows the argument called “argument”. Is it the case, or it should be “speed”, “brightness”, etc.?

All Actions that take a parameter value call it “argument”

Got it! https://github.com/bondhome/api-v2/pull/7

Or maybe provide a list of most popular templates for each device type at least. So I can simulate the devices for testing.