Project

airthings

0.0
No release in over a year
Airthings Consumer API Ruby Gem
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 1.4
~> 13.0
~> 3.11
~> 1.23

Runtime

~> 2.0
~> 1.0
 Project Readme

airthings

Airthings - the Ruby gem for the Airthings consumer API

This SDK is automatically generated by the OpenAPI Generator project:

  • API version: v1
  • Package version: 1.0.0
  • Build package: org.openapitools.codegen.languages.RubyClientCodegen

Installation

Add this to the Gemfile:

gem 'airthings', '~> 1.0.0'

Credentials

You can obtain the necessary API ID and Secret for your user account by going to https://dashboard.airthings.com/integrations/api-integration and clicking "Request API Client".

MQTT Bridge

An MQTT bridge is provided to allow easy integration into other systems. You will need a separate MQTT server running (Mosquitto is a relatively easy and robust one). The MQTT topics follow the Homie convention, making them self-describing. If you're using a systemd Linux distribution, an example unit file is provided in contrib/airthings_mqtt_bridge.service. So a full example would be (once you have Ruby installed):

sudo gem install airthings
sudo curl https://github.com/ccutrer/ruby-airthings/raw/main/contrib/airthings_mqtt_bridge.service -L -o /etc/systemd/system/airthings_mqtt_bridge.service
<modify the file to pass the correct id and secret for your account, and URI to your MQTT server>
<If you use MQTT authentication you can use the following format to provide login information mqtt://username:password@mqtt.domain.tld >
<Make sure to change the "User" parameters to fit your environnement>
sudo systemctl enable airthings_mqtt_bridge
sudo systemctl start airthings_mqtt_bridge

Library Usage

Please follow the installation procedure and then run the following code:

# Load the gem
require 'airthings'
require 'airthings/oauth2'

# Setup authorization
Airthings.configure do |config|
  # Configure OAuth2 access token for authorization: AirthingsAccounts
  config.id = 'YOUR ID'
  config.secret = 'YOUR SECRET'
end

api_instance = Airthings::DevicesApi.new

begin
  result = api_instance.devices_list
  p result
rescue Airthings::ApiError => e
  puts "Exception when calling DevicesApi->devices_list: #{e}"
end

Documentation for API Endpoints

All URIs are relative to https://ext-api.airthings.com/v1

Class Method HTTP request Description
Airthings::DevicesApi device_info GET /devices/{serialNumber}
Airthings::DevicesApi device_samples_latest_values GET /devices/{serialNumber}/latest-samples
Airthings::DevicesApi devices_list GET /devices
Airthings::LocationsApi location_info GET /locations/{locationId}
Airthings::LocationsApi locations_list GET /locations

Documentation for Models

Documentation for Authorization

AirthingsAccounts

  • Type: OAuth
  • Flow: application
  • Authorization URL:
  • Scopes:
    • read:device:current_values: Allowing a user to read current data from devices in their account

Development

Regenerating

export RUBY_POST_PROCESS_FILE="bin/rubocop -A"
wget -O airthings-openapi.json https://ext-api.airthings.com/v1/consumer-api-docs
npx @openapitools/openapi-generator-cli generate -i airthings-openapi.json -g ruby -o . "--additional-properties=gemAuthor='Cody Cutrer',gemAuthorEmail=cody@cutrer.us,gemHomepage=https://github.com/ccutrer/ruby-airthings,gemLicense=mit,gemName=airthings,gemRequiredRubyVersion=2.5,library=faraday,moduleName=Airthings,useAutoload=true"
bin/rubocop -A