a ruby implementation for the withing WIFI connected bodyscale
Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
test - removed dependency on shoulda Sep 24, 2014
.document initial commit Aug 2, 2010
.gitignore Add Gemfile, update Rakefile Mar 4, 2013
Gemfile Add Gemfile, update Rakefile Mar 4, 2013
LICENSE
README.rdoc
Rakefile
simplificator-withings.gemspec Bump gem version Sep 24, 2014

README.rdoc

simplificator-withings

This is a ruby implementation for the Withings API. Description of the API can be found here: www.withings.com/en/api

Versions

0.7.0

  • Removed shoulda

  • Fixed failing tests

  • Refactored Gemspec

  • Closed PR from github

0.6.10

  • Do not raise an exception on unknown types of measurement groups.

0.6.9

  • Added support for activities (thanks to invernizzi)

0.6.8

  • updated README (thanks to jmaddi)

0.6.7

  • Swap ruby-hmac for openssl

  • Allow string userid in User.authenticate

0.6.6

Added list_notifications method to user.

0.6.3

Fixed escaping for parameters.

0.6.2

Updated Readme and Gemspec

0.6.0

OAuth implemented. This version is not compatible to previous releases. Authentication via userid/publickey is not supported anymore.

0.4.5

E-Mail Address is downcased before hashing it (authentication)

0.4.4

Various fixes for the support of Blood Pressure Monitor

0.4.0

Note that this release breaks the API of previous releases:

User.authenticate

User.authenticate() has been replaced by User.userlist

There is no description available and no guarantee on the order that users are returned by the API (and yes, there can be many users for a single Account) so it seems best to leave the decision to the users of the API.

The old method is still there but please update your code. It will be removed in the next release.

MeasurementGroup

MeasurementGroup#created_at has been replaced by MeasurementGroup#taken_at

Created at is usually the timestamp at which a record was created. But MeasurementGroup#created_at was the timestamp when you actually took the measurement. You can also take measurements (via the Web UI on withings.com) which are for a past date. The record is created today, but the measurement was taken on 2 weeks ago.

The old method is still there but please update your code. It will be removed in the next release.

Installation

gem install simplificator-withings gem install ruby-hmac

Authentication

The WBS API now uses OAuth. See the API documentation for details.

TODO

  • Integration Test? But i don't want to share my credentials… Perhaps with a test account on withings? Solution from Withings support: Hi,

    The easiest is that you just create a regular account (start.withings.com), associate it with one scale, then create a user (like any regular customer).

    Once this is done, the account is activated. You may then go to My account/My scale and dissociate the scale, the account will stay opened. That account may be used by who ever you think it should for test purposes and will not be associated to a specific scale.

    Thanks for your enquiry !

    fred

Remarks

  • The gem is still under development and the API might change a bit.

  • Authentication by user_id/public_key is only supported when the user has activated sharing. He can do this either in the sharing overlay on my.withings.com or through the api (user.share <LIST OF DEVICES>) after authentication by email/password

  • As soon as the user sets sharing to false (user.share = false) the public_key is reset and upon next activation of sharing a new public_key is assigned.

  • All the methods making remote calls can throw Withing::ApiError if something goes wrong (wrong public_key, missing parameters, …). You can find more details on the error by looking at the status code in the error.

How To

Require the API implementation

require 'rubygems'
require 'withings'

All classes are name-spaced, if your other code allows you can include Withings

include Withings

Setup

Withings.consumer_secret = '1234'
Withings.consumer_key = 'abcd'

A user can be authenticated using user id and oauth token/secret

user = User.authenticate('<YOUR USER ID>', '<YOUR OAUTH TOKEN>', '<YOUR OAUTH TOKEN SECRET>')

You can handle subscriptions through the API (all devices currently known => Scale + Blood Pressure Monitor)

user.subscribe_notification('http://foo.bar.com', 'test subscription')

Specify what devices you are interested

user.subscribe_notification('http://foo.bar.com', 'test subscription', Withings::SCALE, Withings::BLOOD_PRESSURE_MONITOR)

user.describe_notification('http://foo.bar.com')
user.revoke_notification('http://foo.bar.com')

List notifications is now possible

user.list_notifications

And finally you can get measurements, after all this is what it's for

user.measurement_groups(:per_page => 10, :page => 1, :end_at => Time.now)
user.measurement_groups(:category => MeasurementGroup::CATEGORY_TARGET)
user.measurement_groups(:last_updated_at => Time.at(12345))
user.measurement_groups(:start_at => Time.at(12345), :end_at => Time.at(67890))
user.measurement_groups(:measurement_type => MeasurementGroup::TYPE_FAT)
user.measurement_groups(:device => Withings::SCALE)

Since 0.6.9 you can also get activities

user.get_activities

Note on keys in hashes

Keys to constructors (User, MeasurementGroup and NotificationDescription) and methods (User.measurement_groups) can be either String or Symbol

Note on naming convention

The WBS API has parameter with shortened names (e.g. 'grpid') or names not following a consistent naming pattern. While this API implementation tries to stick as close to the API as possible it also tries to unify and simplify the parameter names. The constructors for User, MeasurementGroup and NotificationDescription accept the names provided by the API but convert the names then to a more “ruby” way. An exception to this are the “id” and “publickey” parameters for User.new, they are accepted as “user_id” and “public_key” as well.

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.

Dependencies

HTTParty is used for making the HTTP requests and Shoulda and Mocha are used for testing. Thanks for these Gems.

Copyright

Copyright © 2012 www.simplificator.com. See LICENSE for details.