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

• Airthings::DeviceSampleResponse
• Airthings::DeviceSimpleResponse
• Airthings::DeviceType
• Airthings::GetDeviceDetailedResponse
• Airthings::GetDevicesResponse
• Airthings::GetLocationResponse
• Airthings::GetLocationsResponse
• Airthings::LocalTime
• Airthings::Location
• Airthings::LocationSimpleResponse
• Airthings::LocationUsage
• Airthings::SegmentSimpleResponse
• Airthings::SensorType
• Airthings::SingleSampleData
• Airthings::SingleSampleResponse

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