Local API Issues with latest beta

I just installed the latest beta app on my android phone and the latest firmware to my Bond. I confirmed in the app that the device is running v2.5.1-44-g9d5c43d-jacob-uglydb (even though the documentation says 2.5.2). I also confirmed the same version via API call to /v2/sys/version.

{"target":"snowbird","fw_ver":"v2.5.1-44-g9d5c43d-jacob-uglydb","fw_date":"Thu Feb 28 03:51:30 UTC 2019","uptime_s":468,"_":"xxxxxxxx"}

I made a call to /v2/token and received the token response and then used that token to get a list of devices via /v2/devices. This is where the trouble begins.

Using the device Id’s from the /v2/devices response, I called /v2/devices/{device-id} to retrieve details for each device. The documentation states that the response will contain a list of actions available for that device however, the response that I receive does not contain the actions array. Here is an example of the response that I receive.

{"name":"Couch Fan","type":"CF","location":"","_":"xxxxxxxx","commands":{"_":"xxxxxxxx"}} 

The next issue occurs when trying to call /v2/devices/{device-id}/state. I get a 404 for each of my devices.

What am I doing wrong??

Well, you can’t use state and action yet, per the intro to the documentation.

BOND API is currently in BETA. This means that:

• the API may change without provisions for backwards compatibility
• some features of the API may not be implemented

Specifically, two major aspects of BOND API are not yet implemented:

• Actions are not implemented
• State feedback is not implemented

For now, it is only possible to control devices by explicitly calling the commands/{}/tx endpoint for the command corresponding to the desired action.

So for now, you can only traverse the device / data tree and find the tx nodes to call.

If that answers your question, cool. If you’re having trouble finding the nodes you want … here is my paraphrasing / understanding of the nested traversing.

Any nodes which are enclosed by { } indicate to me there is another level to drop down and traverse, so I can append the root string (“commands” in this case) to the end of the path in the curl command.

Say I have a device 00000003 on my BOND. This gives me the list of commands, which I can then traverse each one further to get name, action, argument, icon, a signal array (which can then also be traversed down into to reveal freq, bps, reps, modulation, encoding, and data), and a tx array.

curl -i -H “BOND-Token: xxxxxxxxxxxxxxxx” http://BDxxxx.local/v2/devices/00000003/commands/

Each node which has a { } around it, is a node you can traverse down into.
So for the example above, I can look at command 00000006 like so:
curl -i -H “BOND-Token: xxxxxxxxxxxxxxxx” http://BDxxxx.local/v2/devices/00000003/commands/00000006

This shows me command 00000006 is for toggling the light. I now have enough information to call the tx command for toggling the light.
curl -i -H “BOND-Token: xxxxxxxxxxxxxxxx” http://BDxxxx.local/v2/devices/00000003/commands/00000006/tx -X PUT -d {}

Just for grins, if I was randomly curious and wanted to look at the signal node’s array to see what BOND was actually sending when I PUT to the tx node, I could call one more level down:
curl -i -H “BOND-Token: xxxxxxxxxxxxxxxx” http://BDxxxx.local/v2/devices/00000003/commands/00000006/signal/

Don’t know if this is helpful as is, or if there is something specific I (or others) could address.

Thanks for taking the time to type all of this up. I guess I skipped over the part that said state and action were not yet supported.

No worries, sorry for the overkill if you didn’t need all that detail. Maybe it will help someone else :slight_smile:

This was helpful to me. I was starting to wonder what good the API is if its not usable.

I’ll give your examples a try to make sure the API is working.

1 Like

Any ETA as to when these features will be implemented? Working on a Home Assistant plugin and would rather not to have to write it twice. Next sprint, next month, next quarter?

Of course, I can’t speak to what the company is doing as I am just a customer.

However, I’ve integrated with ISY994i without any need for State or Action nodes - I track State and other variables myself.

I’m curious if Home Assistant (and other integrations) would tangibly benefit from State or Action commands, particularly since Action is effectively close to the same thing as calling the tx (aside from BOND tracking states etc).