Controlling HomeBridge through cURL [Solved w/ documentation]

I’ve been attempting to control HomeBridge accessories through terminal the entire evening, and at this point I simply have no clue what I’m doing wrong.

I must have read through #506 5 times by now, attempting different pastes of commands, with no succes.

I’ve been attempting to run the cURL commands from the Pi which the HomeBridge server is hosted from. I am running the -I for HomeBridge, and I use homebridge-config-ui-x where accessories work just fine, using same method. I’m getting the accesory ID and AID from homebridge-config-ui-x.

No matter what I do, I get:

1. `"status":-70402`
   

   curl -X PUT http://192.168.1.171:51826/characteristics --header "Content-Type:Application/json" --header "authorization: 589-00-356" --data '{"characteristics":[{"aid":17,"iid":8,"value":false,"status":0}]}'

2. `{"characteristics":[{"aid":"17","iid":"2","status":-70402}]}`
   

   curl -X PUT http://localhost:51826/characteristics --header "Content-Type:Application/json" --header "authorization: 589-00-356" --data "{ \"characteristics\": [{ \"aid\": \"17\", \"iid\": \"2\", \"value\": \"0\"}] }"

3. even: > ?? curl -X PUT http://192.168.1.171:51826/characteristics --header 'Content-Type:Application/json' --header 'authorization: 589-00-356' --data '{ \'characteristics\": [{ \'aid\': 2, \'iid\': 9, \'value\': 0}] }'

4. {"characteristics":[{"aid":17,"iid":9,"status":0}]} From changing id’s randomly, but only outputs status: 0 sometimes, and other times -70402

I’ve tried:

• localhost and IP

• From a different pc on the network

• GET and PUT

• Different id/aid and even random ones

• I’ve checked the port, ip and authorization thousands of times

• There was a suggestion #506 to not use whitespace, which is of cause also tried

• Pretty much tried copying every single command from #506 and changing ip, port, auth, id’s and such.

• Value/Status both 0/1 and true/false

• Everything I could think of, except giving up

As I was writing this I was able to return a “status”:0 chaning the IID and AID numbers randomly, but it only seems to work sometimes? And doesn’t actually alter anything. {"characteristics":[{"aid":17,"iid":9,"status":0}]}

There is no console output, except for a few times where I crashed HomeBridge as I sent wrong quotes.

Please for the love of god help me

#EDIT: I realized that passing "value":false changed the name of the accessory even though the result was status":-70402. Although neither On: true or brightness: 20 does anything at all.

[NorthernMan54]

@jandreaucodes - Please keep in mind that there are 2 API here and it looks you have them confused. There is the HAP interface which is what I have been explaining to people, and this is documented in the HomeKit Accessory Protocol specification from Apple. And there is an API which is part on Homebridge-config-ui-x, which is documented here https://github.com/oznu/homebridge-config-ui-x/wiki/API-Reference which is very similar.

And it looks like you are trying to use the HAP message format against the Homebridge-config-ui-x configuration endpoint. Try changing this http://myhostname:8581/api/characteristics to your Homebridge instance port, and remove api from the url ie http://jesse.local:51826/characteristics.

Another option to control your homebridge accessories is to install node-red and the Homebridge-automation, that is what I use to control my homebridge accessories. it keeps it simple, and removes the need to determine the AID and IID of you accessory.s

PS This assumes you have enabled insecure mode

[tokeraabjerg]

@NorthernMan54 to the rescue, as always!

After copying your example for getting accessories (which worked), I realized that, correct me if I’m wrong, every device has an IID for different purposes, such as name, brightness, “On” and so on.

This means I was simply using the wrong IID (and probably a wrongly formatted command), thus also ending up changing the name of the device, instead of actually turning it on.

---

So for anyone who may be struggling with this;

If you already have the correct IID and AID’s, make sure you’re formatting the command correctly, as NorthernMan54 said:

from the command line back slashes are important

Make sure you’re calling the correct IID and AID, which you can find by running NothernMan54’s example;

Accessory Dump curl -X PUT http://jesse.localt:51826/accessories --header "Content-Type:Application/json" --header "authorization: 031-45-154"

Where you obviously have to replace jesse.localt:51826 with your IP and Port for HomeBridge (port 51826 is the standard port) and 031-45-154 with your authorization code found in your config.json as "pin: "...".

The accessory dump is a json dump with no whitespace, so it’s not very readable, but what you’re looking for is first of an AID which has the "value": of the manufactorer, in my case 17. Below that there will be the device IID’s for the certain device, this is where you have to locate the correct IID depending on what you’re trying to do, in my case the "On": IID as indicated by "Description": "On"

Example of accessory dump snippet: (formated with whitespace for readability)

{"aid":17,"services":[{

    "iid":1,"type":"0000003E-0000-1000-8000-0026BB765291","characteristics":[{"iid":2,"type":"00000014-0000-1000-8000-0026BB765291","perms":["pw"],"format":"bool","description":"Identify"},

    {"iid":3,"type":"00000020-0000-1000-8000-0026BB765291","perms":["pr"],"format":"string","value":"MiLight","description":"Manufacturer"},

    {"iid":4,"type":"00000021-0000-1000-8000-0026BB765291","perms":["pr"],"format":"string","value":"rgbww","description":"Model"},

    {"iid":5,"type":"00000023-0000-1000-8000-0026BB765291","perms":["pr"],"format":"string","value":"Desktop","description":"Name"},

    {"iid":6,"type":"00000030-0000-1000-8000-0026BB765291","perms":["pr"],"format":"string","value":"Default-SerialNumber","description":"Serial Number"},

    {"iid":7,"type":"00000052-0000-1000-8000-0026BB765291","perms":["pr"],"format":"string","value":"1.0","description":"Firmware Revision"}],"primary":false,"hidden":false},

    {"iid":8,"type":"00000043-0000-1000-8000-0026BB765291","characteristics":[{"iid":9,"type":"00000023-0000-1000-8000-0026BB765291","perms":["pr"],"format":"string","value":"Desktop","description":"Name"},

    {"iid":10,"type":"00000025-0000-1000-8000-0026BB765291","perms":["pr","pw","ev"],"format":"bool","value":false,"description":"On"},

    {"iid":11,"type":"00000008-0000-1000-8000-0026BB765291","perms":["pr","pw","ev"],"format":"int","value":100,"description":"Brightness","unit":"percentage","maxValue":100,"minValue":0,"minStep":1},

    {"iid":12,"type":"00000013-0000-1000-8000-0026BB765291","perms":["pr","pw","ev"],"format":"float","value":0,"description":"Hue","unit":"arcdegrees","maxValue":360,"minValue":0,"minStep":1},

    {"iid":13,"type":"0000002F-0000-1000-8000-0026BB765291","perms":["pr","pw","ev"],"format":"float","value":0,"description":"Saturation","unit":"percentage","maxValue":100,"minValue":0,"minStep":1},

    {"iid":16,"type":"3c2684ee-d18c-460c-bec6-250b147b3e6f","perms":["pr","pw","ev"],"format":"bool","value":false,"description":"White mode"}],"primary":false,"hidden":false}
  ]
},

So you’ll see AID and IID as the first value of the object, and at the end you’ll see "description": indicating what the AID/IID is for. As mentioned, I was trying to change the value “On” for my device which had the AID 17, and “On” has the IID 10. So in that case, my command would be:

curl -X PUT http://192.168.1.171:51826/characteristics --header "Content-Type:Application/json" --header "authorization: 589-00-356" --data "{\"characteristics\":[{\"aid\":17,\"iid\":10,\"value\":true}]}"

---

More on accessory dump iid/aid’s: (from issue #506, comment by @ebaauw)

• I think iid 1 is reserved for the Accessory Information service, hence not present in the file;
• iids 2-8 are the characteristics of the Accessory Information service (03E): Identify (014), Manufacturer (020), Model (021), Name (023), Serial Number (030), and Firmware Revision (052);
• iid 8 is for the Service Label service (0CC);
• iids 9, 10, 12, 13 are for standard characteristics of the Service Label service: Name (023), Service Label Namespace (0CD), Status Fault (077), Status Active (075);
• iids 11, 14 and 15 are custom characteristics for the Service Label service (see: https://github.com/ebaauw/homebridge-hue-utils/blob/master/lib/MyHomeKitTypes.js): _Last Updated (023), Enabled (022), Resource (021);
• iid 16 is the fist Stateless Programmable Switch service (089) for the first button (subtype “On”);
• iids 17-19 are the characteristics for the fist Stateless Programmable Switch service: Name (023), Programmable Switch Event (073), and Service Label Index (0CB);
• This repeats for the other three buttons;
• iid 32 is the Battery (096) service;
• iids 33-36 are the characteristics fo the Battery service: Name (023), Battery Level (068), Charging State (08F), and Status Low Battery (079).

---

I felt like there should be some more documentation on this matter for anyone like me who may be new with this kind of stuff, or for anyone else just struggling. I hope some of you find it useful, and if you have any questions feel free to ask.