YoLink API Ruby Gem

A Ruby library for interacting with the YoLink Smart Home API. This gem provides a simple interface for retrieving device information and sensor data from YoLink devices, particularly temperature and humidity sensors.

Installation

Add this line to your application's Gemfile:

gem 'yolink-api'

And then execute:

bundle install

Or install it yourself as:

gem install yolink-api

Usage

Setting up credentials

You need a YoLink client ID (UAID) and client secret (YOKEY) to use this gem. You can get these from the YoLink developer portal.

There are two ways to provide your credentials:

Option 1: Pass credentials directly

client = YoLink::Client.new('your_client_id', 'your_client_secret')

Option 2: Use credentials from ~/.yolink.yml file

Create a YAML file at ~/.yolink.yml with the following content:

CLIENT_ID: your_client_id
CLIENT_SECRET: your_client_secret

Then initialize the client without parameters:

client = YoLink::Client.new

Retrieving devices

Get a list of all your YoLink devices:

devices = client.devices
puts "Found #{devices.length} devices"

# Filter to specific device types
temp_sensors = devices.select { |device| device['type'] == 'THSensor' }
puts "Found #{temp_sensors.length} temperature sensors"

Working with temperature sensors

Get data for a specific sensor:

if sensor = temp_sensors.first
  # Pass the entire sensor object
  data = client.sensor_data(sensor)
  
  temp_c = data.dig('state', 'temperature')
  temp_f = YoLink::TemperatureUtils.celsius_to_fahrenheit(temp_c)
  humidity = data.dig('state', 'humidity')
  battery = data.dig('state', 'battery')
  
  puts "Sensor: #{sensor['deviceName']}"
  puts "Temperature: #{temp_c}°C (#{temp_f}°F)"
  puts "Humidity: #{humidity}%"
  puts "Battery: #{battery}"
  puts "Last updated: #{Time.at(data['reportAt'] / 1000)} UTC" if data['reportAt']
end

Managing caches

Clear cache if needed:

# Clear token cache
client.clear_cache(:token)

# Clear data cache
client.clear_cache(:data)

# Clear all caches
client.clear_cache

Advanced Options

You can customize the client with additional options:

# Custom logger and cache settings
client = YoLink::Client.new(
  'your_client_id', 
  'your_client_secret',
  {
    logger: Logger.new('yolink.log'),  # Custom logger
    token_ttl: 3500,                    # Token cache TTL in seconds
    cache_ttl: 60                       # Data cache TTL in seconds
  }
)

Error Handling

The gem provides custom error classes for better exception handling:

begin
  devices = client.devices
rescue YoLink::AuthenticationError => e
  puts "Authentication error: #{e.message}"
rescue YoLink::RateLimitError => e
  puts "Rate limit exceeded: #{e.message}"
rescue YoLink::APIError => e
  puts "API error: #{e.message}"
rescue => e
  puts "Unexpected error: #{e.message}"
end

YoLink API Ruby Gem

A Ruby library for interacting with the YoLink Smart Home API. This gem provides a simple interface for retrieving device information and sensor data from YoLink devices, particularly temperature and humidity sensors.

Features

• Simple Interface: Easy-to-use methods for common YoLink API operations
• Authentication: Handles OAuth2 authentication and token refresh automatically
• Caching: Built-in caching system to respect API rate limits
• Error Handling: Custom error classes for better exception handling
• Configuration File Support: Configure via ~/.yolink.yml file or direct parameters

API Reference

YoLink::Client

initialize(client_id = nil, client_secret = nil, options = {})

Creates a new API client instance. If credentials are not provided, attempts to load from ~/.yolink.yml.

devices

Returns an array of device objects from the YoLink API.

sensor_data(device)

Returns sensor data for a temperature and humidity sensor.

• Parameters:
  • device: A device hash from the devices method
• Returns: Hash containing sensor state data

clear_cache(type = :all)

Clears the specified cache.

• Parameters:
  • type: Symbol - :token, :data, or :all

Core Components

The gem consists of the following main components:

1. YoLink::Client - Main API client class
2. YoLink::Cache - Simple cache implementation for rate limiting
3. YoLink::TemperatureUtils - Utility methods for temperature conversions
4. Custom Error Classes - For better error handling

API Rate Limits

The YoLink API has the following rate limits that this client helps manage:

• 100 calls per 5 minutes
• 6 calls per device per minute
• Minimum 200ms interval between requests

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test 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 the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/yolink-api.

License

The gem is available as open source under the terms of the MIT License.