Any feedback or questions related to Web Socket API

[SecureComp]

good stuff @fort

Seeing the same things, handling the case sensitivities isn't a big deal, just tedious.
Using the same solution and declaring two variables at times when really one should be enough. (mii)

Wondering whether the to send "true" "false" or 1, 0 has tripped me up a few times.

Fixing these items and a few others would speed up development just because I wouldn't be chasing down issues but I do understand the level of effort that would need to happen on Securifi's part as well.

[Ashok]

@ fort,

Incomplete documentation

This is somewhat expected seeing as the API is all shiny and new. It's cropped up mostly when I'm looking for a list of acceptable values for a particular parameter. For instance, I was trying to activate a specific rule, so I sent the following:

Code: [Select]

{ 
 "mii":"<random key>",
 "cmd":"validaterule",
 "ruleid":"<ruleid>",
 "value":"true"
}
Well, this didn't work. Turns out, the value attribute was expecting either a "1" or a "0" — even though the response data shows "true" or "false" (ex: "data":{"value":"true","ruleid":"<ruleid>").

Yes, that is what the command expects either 1 or 0.

Structural weirdness (possibly typos?)

Here's the sample request for ActivateScene:

Code: [Select]

{ 
 "CommandType":"ActivateScene",
 "MobileInternalIndex":"324",
 "Scenes":{ 
   "ID":"11"
 }
}
Should the "Scenes" attribute be an array?

Yes, it is in Array format, however, we will not allow multiple scenes at a time.

[fibrs86]

Since this websocket is completely insecure, I assume/hope it is only exposed on the internal interface.

Is the intention to keep it local network only, even if it is secured?

[bmwilson55]

Hello all.  Trying to access the websocket on my almond 3 using the chrome simple web socket client.  Which/what password do I need to use in the URL?  Is it the same password to access the local web interface?  Thanks

[cr0ybot]

@bmwilson55 If you haven't found the answer by now, you need to use the username & password for the local web interface.

I'd love to see some explanatory text added to the DeviceList doc. The Websockets API doc is not very helpful with regards to knowing what "Type" values map to what "Device" with specific "DeviceValues" (capabilities). In fact, I glossed past the sections of the websockets doc most relevant to me because I didn't grok that a "DeviceIndex" is how we're supposed to interact with and read/change a devices properties.

There's an entire column for "Remarks" that is just begging for some explanations. For starters, what do the 5 different values for DoorLock LOCK_STATE symbolize? I'm assuming something along the lines of open, closed, opening, closing, and maybe unknown, but I don't have a lock to test with and they are unlabeled in the doc. Also, what are the practical differences between the data types Byte, Int, Decimal, Unsigned-Char, and Unsigned-Char(Decimal) when the value ranges seem almost interchangeable? I'm familiar with the usual difference between, say, a byte (8-bit, 0-255) vs an integer (at least 16-bit, 0-65,536), but I see a lot of interchangeable types (Byte, Decimal) for number ranges of 0-255 and 0-100.

Why are my non-colored Hue bulbs showing up as Type 4 (MultilevelSwitchOnOff) with extra undocumented device values that correspond with Type 48 (HueLamp) but in a different order? And is there any documentation on the Type values associated with each DeviceValue?

And what are all the references to XML about? The websockets API is JSON, is there another API that handles XML? Is there documentation on the XML that may have more information?

I might be interested in edit rights for the Wiki while I develop my addon for Mozilla's Things Gateway: https://github.com/cr0ybot/almond-adapter

[Square Cherry]

cr0ybot,

I've had to figure a lot of these things out myself in rewriting a homebridge-almond plugin. You're welcome to look at how I interpreted the Almond's JSON values. Particularly, the GarageDoorOpener and DoorLock states needed a lot of trial-and-error. There are still a bunch of device types I haven't tackled yet, as I only have so many sensors on hand. Pardon my disdain for semicolons.

[cr0ybot]

@Square Cherry your work will be an invaluable reference, thank you! I may be interested in using your almond-client as a dependency, though I see your edits have not been merged upstream to the npm-connected repo. I've already got the websocket connection working, but this looks like it has many useful features and it would be silly to duplicate the effort.

[Square Cherry]

cr0ybot,

Please use whatever you'd like! I am new to Git, and I'm not quite sure how to merge upstream. I introduced some breaking changes in my fork, anyway. It's not backwards-compatible to Thomas Purchas' original. If I knew how to push my changes upstream, even to NPM, that'd be cool (if no one objected). I just haven't looked into the process.

Some warnings about almond-client:

You might notice that I'm not using its callback feature in homebridge-almond. In some of the early versions, I realized the Almond is quite slow in sending "updates" after a change has been written. That's why I made the feature optional (see the function signatures). A consequence is that I have not gotten around to testing this logic thoroughly, so be careful. All almond-client does by default is wait for the "Success" response, which seems more like an acknowledgment than a confirmation.

Also, beware that the keepalive timing is quite aggressive (about once per second, if I recall). You may need to adjust this if you need multiple client connections for your project. It could get "spammy" easily.

[cr0ybot]

Thanks @Square Cherry.

You won't be able to take ownership over a published npm package without the owner's permission, and since your fork is from another fork, I'm not sure what the GitHub-specific process is to create a pull request to the originating repo.

I think I'll end up referencing some of the work you did with keeping the socket alive and possibly incorporating the EventEmitter class, but it may end up being more work to incorporate almond-client wholesale. I've also got my own system for tracking responses to requests using a Promise-based system which I'd like to develop further.

Since this thread is ostensibly for API feedback, I'm working on my own mapping from the DeviceTypes list to Mozilla's Web of Things Capabilities schema (it's early days, so pretty limited in scope currently), and I've noticed a few more discrepancies. For starters, definitions for IDs 35, 42, 47, and 51 are missing. I suppose IDs don't necessarily need to be sequential, but a note like "Unused" might be helpful. Also, #56 EnergyReader is listed twice.

[Square Cherry]

I think I'll end up referencing some of the work you did with keeping the socket alive and possibly incorporating the EventEmitter class, but it may end up being more work to incorporate almond-client wholesale. I've also got my own system for tracking responses to requests using a Promise-based system which I'd like to develop further.

Fair. I know Promises are the way to go, but I'd finally wrapped my head around EventEmitter. I will probably rewrite using Promises someday, once I get more comfortable with them. Perhaps I should take a look at your client system for reference.

Since this thread is ostensibly for API feedback, I'm working on my own mapping from the DeviceTypes list to Mozilla's Web of Things Capabilities schema (it's early days, so pretty limited in scope currently), and I've noticed a few more discrepancies. For starters, definitions for IDs 35, 42, 47, and 51 are missing. I suppose IDs don't necessarily need to be sequential, but a note like "Unused" might be helpful. Also, #56 EnergyReader is listed twice.

Yeah, I consulted that Devicelist Documentation when making my short version in JSON. I'm not sure where it came from, but it isn't terribly consistent. It seems like the only resource we have for now. There's a reason I'm only supporting a few types in my homebridge-almond fork.