Get Device Information

1

Can the json reply format for “/v2/devices” be changed? I think the device ids should be on left side - not right side, i.e. instead of

{"_":"f7e407f1","79135791":{"_":"599b0fc5"}}

the reply should be something like:

{"_":"f7e407f1","id":"79135791"}

To explain the problem, when I parse json reply I convert the json string to C# class, so for your implementation it’s impossible -

public class __invalid_type__79135791
{
    public string _ { get; set; }
}

public class RootObject
{
    public string _ { get; set; }
    public __invalid_type__79135791 __invalid_name__79135791 { get; set; }
}

Using my suggestion {"_":“f7e407f1”,“id”:“79135791”}:

public class RootObject
{
    public string _ { get; set; }
    public string id { get; set; }
}
2

Or to avoid breaking changes - another option is to add a new request i.e. “/v2/devicelist” which will return a whole list of devices with all device info, also to avoid two-stage requests to get device info. I don’t think it’s a huge overhead because nobody is going to have 1000’s of devices…

3

Unfortunately we can’t change it, since there’s a lot of logic dependent on this API.
What I suggest to you is work with json object, or dictionaries, until you have expanded the whole object (queried all topics). Then you can parse it to your C# class later. That’s what we do on the mobile apps :wink:

2 Likes
4

As I said, you can add a new request i.e. “/v2/devicelist” to avoid breaking changes

5

It’s JSON. Doesn’t matter which order it is in as you just convert it to an array, dictionary, table, or whatever your programming language supports.

1 Like
6

It does matter. Json id dictionary “keyword => value”. So, to be able to get the device id the reply should be “ID : xxxx”. Then you get the id like this: json[ID].

But in current implementation the device id is the “keyword”. So how do I get it?

I know, I can parse anything, but why bother? It’s wrong implementation. The strings on the left should be known constants.

7

And BTW, because there are multiple devices - it should be a list i.e.

{"ids":["xxx","yyy"]}

public class RootObject
{
    public List<string> ids { get; set; }
}
8

What you want is something like this (pseudo-code):

json_obj = get('v2/devices')
dev_id_list = [ id for id in json_obj.keys() if not id.startswith('_') ]

Expl: v2/devices is an emumeration, so all children are devices with the ID in the keys, with the exception of “hidden” keys which always start with an underscore.

9

Haha, that’s what I just did:

ids = (from id in response where (string)id != "_" select (string)id).ToList();

But better cast response to:

class DevicesResponse : List<Dictionary<string,object>>
{
}

Still, would be much better to just get a list of devices (not just ids)

10

Bond firmware is highly portable and needs to be able to be run on many platforms. If we add just one new API, we are committing long-term to supporting it on millions of connected appliances. Thus, we keep the API as simple as possible!

But, we do need to create some better “getting started” content on how to use the API in typical scenarios… how to get device lists for example. Examples would be necessity be in some language… Python probably…

1 Like
11

I reckon it’s even better to provide a library (Python, Java, C#, C++) - so you don’t need to explain the API details much. I know - it’s a bit of work, but for end users it’s huge help. Like Google Calendar API.

When I finish my HomeSeer plugin I can provide my feedback on your documentation, if you don’t mind.

12

We wrote 4 drivers for 4 different control systems using lua, TCL and javascript. The API works and is fine as is. It is actually quite detailed in comparision to the hundreds of other APIs we encounter every year.

This is how we do the initial setup. This gives us all the details we need to get started (minus polling/udp feedback/control which i can get into if you need more tips - though that is pretty straight forward).

  1. mDNS query (_bond._tcp.local) for bond device (limit by Bond ID in case there are multiple)
  2. We do a get version which we use for logs - so that our users can report back details for our support desk (/v2/sys/version)
  3. Do a get token if no token is present (/v2/token)
  4. Do a get devices (/v2/devices)
  5. for each device get the device’s details (/v2/devices/deviceID)
  6. for each device get the device’s properties (/v2/devices/deviceID/properties)
1 Like
13

That’s because you know how to use it. “Any software is user friendly if you know which button to press”.

Sure, I already worked out the sequence, but it took me 2 days.

Instead of just

protected virtual bool GetStatus()
{
    GetVersion();

    if(String.IsNullOrEmpty(Token))
        GetToken();

    if (!String.IsNullOrEmpty(Token))
        ChildDevices = GetDevices();

    return true;
}

That’s exactly my point! You could already have your libraries in 4 different languages! Not only for “some users” - just for your selves in the first place. That’s how I work - create a library first. But it’s up-to-you anyways.

14

The point I’m trying to make is that what the guys have done is perfectly fine.

We had 3 different developers at our company work on 4 different integrations/home automation systems.

The documentation is good and provides everything you need to do the work.

Sure the Olibra guys could make it even easier by doing the work for you but I would rather them do what their good at and that’s further improving integration of RF products.

15

ok, it was just a suggestion - not a subject for discussion. That’s a common excuse “we don’t have time to do it properly”. And believe me - I’ve seen it many times in my 30 years in the industry.

16

Specific feedback/suggestions on how to improve the API docs is welcome!

17

Could we, as a community, try to use something like this topic to track these so @merck and crew have a single place to go, versus 50,000 unique topics? :grinning:

18

Better yet, here’s a repo with the source code to the docs. https://github.com/bondhome/api-v2

Best way to contribute: Open a PR there with a fix/improvement.

Or: Open an issue on that repo.

3 Likes