WeatherLink
This is an unofficial implementation of the Davis Instruments WeatherLink API, including both the Local API (v1) and the web API (v2).
Installation
Add this line to your application's Gemfile:
gem 'weatherlink'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install weatherlink
Usage
Local API
To read the data from a local WeatherLink Live device via the "local API" (there is no authentication):
require 'weatherlink'
> wl = WeatherLink::LocalClient.new(host: '<local ip address>')
The current_conditions
method returns a SensorData
object for each sensors:
> cc = wl.current_conditions
=> #<WeatherLink::SensorDataCollection (3 sensors)>
> cc.to_a
=> [#<WeatherLink::SensorData lsid=1 (Local API - ISS Record, 1 records)>,
#<WeatherLink::SensorData lsid=2 (Local API - LSS Temperature/Humidity Record, 1 records)>,
#<WeatherLink::SensorData lsid=3 (Local API - LSS Barometric Pressure Record, 1 records)>]
Each SensorData
is a wrapper for a hash containing the underlying data. Each of its keys can also be used as a method to get the data itself.
> pp cc[0].to_h
{"ts"=>1609130694,
"temp"=>24.2 tempF,
"hum"=>84.9 %,
"dew_point"=>20.3 tempF,
"wet_bulb"=>22.6 tempF,
"heat_index"=>24.2 tempF,
"wind_chill"=>24.2 tempF,
"thw_index"=>24.2 tempF,
"thsw_index"=>22.2 tempF,
"wind_speed_last"=>0 mph,
"wind_dir_last"=>0 deg,
"wind_speed_avg_last_1_min"=>0 mph,
"wind_dir_scalar_avg_last_1_min"=>149 deg,
"wind_speed_avg_last_2_min"=>0 mph,
"wind_dir_scalar_avg_last_2_min"=>149 deg,
"wind_speed_hi_last_2_min"=>1 mph,
"wind_dir_at_hi_speed_last_2_min"=>149 deg,
"wind_speed_avg_last_10_min"=>0 mph,
"wind_dir_scalar_avg_last_10_min"=>149 deg,
"wind_speed_hi_last_10_min"=>1 mph,
"wind_dir_at_hi_speed_last_10_min"=>149 deg,
"rain_size"=>1,
"rain_rate_last"=>0 in/h,
"rain_rate_hi"=>0 in/h,
"rainfall_last_15_min"=>0 in,
"rain_rate_hi_last_15_min"=>0 in/h,
"rainfall_last_60_min"=>0 in,
"rainfall_last_24_hr"=>0 in,
"rain_storm"=>0 in,
"rain_storm_start_at"=>nil,
"solar_rad"=>0 W/m^2,
"uv_index"=>0.0,
"rx_state"=>0,
"trans_battery_flag"=>0,
"rainfall_daily"=>0 in,
"rainfall_monthly"=>18 in,
"rainfall_year"=>128 in,
"rain_storm_last"=>5 in,
"rain_storm_last_start_at"=>1608224100,
"rain_storm_last_end_at"=>1608318061}
Note that the unit support uses ruby-units
which uses Rational
, so some of the results can be... interesting:
> cc[0].temp
=> -3342515348439043/791648371998720 tempC
Use scalar.to_f
to get a Float
most of the time:
> cc[0].temp.scalar.to_f
=> -4.222222222222226
Web API
Obtain API credentials form your WeatherLink account and initialize the API:
require 'weatherlink'
> wl = WeatherLink::Client.new(api_key: '<api key>', api_secret: '<api secret>')
Various aspects of the API and devices can be interrogated:
> wl.stations
=> [#<WeatherLink::Station station_id=1 gateway_id_hex=a (Jackalope)>]
> wl.sensors
=> [#<WeatherLink::Sensor lsid=1 (Davis Instruments - WeatherLink LIVE Health)>,
#<WeatherLink::Sensor lsid=2 (Davis Instruments - Barometer)>,
#<WeatherLink::Sensor lsid=3 (Davis Instruments - Inside Temp/Hum)>,
#<WeatherLink::Sensor lsid=4 (Davis Instruments - Vantage Pro2 Plus /w 24-hr-Fan-Aspirated Radiation shield, UV & Solar Radiation Sensors)>,
#<WeatherLink::Sensor lsid=5 (Davis Instruments - AQS Health)>,
#<WeatherLink::Sensor lsid=6 (Davis Instruments - AirLink)>,
#<WeatherLink::Sensor lsid=7 (Davis Instruments - AQS Health)>,
#<WeatherLink::Sensor lsid=8 (Davis Instruments - AirLink)>,
#<WeatherLink::Sensor lsid=9 (Davis Instruments - AQS Health)>,
#<WeatherLink::Sensor lsid=10 (Davis Instruments - AirLink)>]
> wl.nodes
=> [#<WeatherLink::Node device_id_hex=a (Station - Barn)>,
#<WeatherLink::Node device_id_hex=b (Station - Living Room)>,
#<WeatherLink::Node device_id_hex=c (Station - Office)>]
Since most users will probably only have one station, a station
method returns the first station for convenience:
wl.station
=> #<WeatherLink::Station station_id=1 gateway_id_hex=a (Station)>
To collect current weather data from all sensor of the first/primary station:
> wl.station.current
=> #<WeatherLink::SensorDataCollection (10 sensors)>
At this point accessing the underlying data is exactly the same as using the Local API above.
Since the station knows the IP addresses of each sensor, if you're on the local network you can also access these sensors directly through the local_sensors
method (which uses the same WeatherLink::LocalClient
API above, but automatically configures it for each known sensor):
> wl.station.local_sensors
=> [#<struct WeatherLink::Station::LocalSensor device=#<WeatherLink::Station station_id=1 gateway_id_hex=a (Station)>, host="1.2.3.4">,
#<struct WeatherLink::Station::LocalSensor device=#<WeatherLink::Node device_id_hex=b (Station - Living Room)>, host="1.2.3.5">,
#<struct WeatherLink::Station::LocalSensor device=#<WeatherLink::Node device_id_hex=c (Station - Office)>, host="1.2.3.6">,
#<struct WeatherLink::Station::LocalSensor device=#<WeatherLink::Node device_id_hex=d (Station - Barn)>, host="1.2.3.7">]
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/jeremycole/weatherlink.
License
The gem is available as open source under the terms of the MIT License.