Handedness value


I’m working on a Lockitron iPhone app and I noticed that when I send a GET request to https://api.lockitron.com/v2/locks I’m seeing that the value for “handedness” is showing as “unlocked”, “locked”, or in the case of a virtual lock “unsupported” when the the documentation at https://api.lockitron.com/#locks states that the expected responses should be “true”, “false”, or null.

handedness: string
The handedness of a new Lockitron (whether it turns clockwise or counter-clockwise to lock). It can be “true”, “false”, or null (unsupported).


[{“id”:“xxxx-xxx-xxx-xxxx-xxxx”,“name”:“Hanlon’s Lockitron”,“next_wake”:“2015-02-19T03:27:06Z”,“last_heard_from”:“2015-02-18T03:26:57Z”,“state”:“unlock”,“button_type”:“slider”,“updated_at”:“2015-02-18T02:31:44Z”,“handedness”:“unlocked”

It’s causing issues when my app parses the JSON response into Core Data. Is it possible to fix the API backend or the API documentation?


If I’m not mistaken (I use that phrase way too much), the documentation is off.

It should be treated the same way it gets set in the iPhone app:
“When your lock is turned clockwise, is your door locked or unlocked?”

Therefore, Handedness: unlocked, means that turning the knob clockwise unlocks the door, and turning it counterclockwise locks it.

Since this is the way the API reports it, I’d say it’s probably best to assume the documentation needs to be corrected, and test for this case appropriately.


@Hanlon @anthonylavado thanks for catching this. This is a problem in the documentation. Given that our iPhone app would also throw a fit if we switched this to true/false, we’ll opt for fixing the docs (sorry, I realize that this means you need an additional function to parse it if you were planning on storing this as a boolean).

I will edit the documents to indicate exactly what @anthonylavado says with an addition:

“When Lockitron’s thumbturn is turned fully clockwise, is your door locked or unlocked?”

Being very explicit here since “clockwise” interpreted from the key side of the door fouls this up.


I do see the correct interpretation here: https://api.lockitron.com/#change_the_handedness

So it would appear that the correction is needed on the Locks section.
@Cameron Good point on requiring an explicit definition, so perhaps add that to both? Also, I don’t know if this question is asked during the setup process, but the iPhone app should probably match as well.

@Hanlon - Can’t wait to see your app! Is this the one with widgets from before?


@anthonylavado what you noted above is in the iPhone app - I think we can get away with being a bit less verbose there because during the majority of the set up process you’re dealing with the inside of the lock (although this changes a bit with Bolt).


Updated; also just noticed a duplicate “handedness” explanation that I’ll have removed and will be going away in subsequent deploys.

This will be the last mention here, however, the translation was that “unlocked” == true == 1 and “locked” == false == 0. It looks like we still accept 1/0 and true/false as params when you change the handedness, however, this will likely be deprecated in the future.