tapo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0b795da61e6ac0d9e745b5a1008855df9cf4b7aeb5a34bf1e985ab32de9ac49c
+  data.tar.gz: 666774cf9506187ad94b35bded144825b39ca5810bcc1deb23da61f78417d474
+SHA512:
+  metadata.gz: 0107d09fda4b54bef29ccc188e72b62a2888f4723f7b0c21c47f5b6f248162b5b625ae7ea747563b138b5b503e525f0ac4cdc76e07c0e73e67ecbb4aea92f9aa
+  data.tar.gz: a7d92c3da872d88be6b8c30168379fbda9b9e9770539e303f861a857e81f7cea4f3324eb126b0ff510b34a7753a2e51ae2e596145e5cb1215235200fb0d03426

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashish Rao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,76 @@
+# Tapo Ruby Client
+
+A Ruby library for controlling TP-Link Tapo smart devices (P100, P110).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'tapo'
+```
+
+Or install it yourself:
+
+```bash
+gem install tapo
+```
+
+## Usage
+
+### Basic Control
+
+```ruby
+require 'tapo'
+
+# Connect to a device
+client = Tapo::Client.new('192.168.1.100', 'your-email@example.com', 'your-password')
+client.authenticate!
+
+# Control device
+client.on
+client.off
+
+# Check status
+client.on?        # => true/false
+client.nickname   # => "Living Room Lamp"
+
+# Get device info
+info = client.device_info
+```
+
+### Energy Monitoring (P110 only)
+
+```ruby
+# Quick access to electrical measurements
+client.power_usage  # => 12.5 (watts)
+client.voltage      # => 230.5 (volts) (if supported)
+client.current      # => 0.054 (amps) (if supported)
+
+energy = client.energy_usage
+# => {
+#   "power_w" => 12.5,                # Power in watts (W)
+#   "power_kw" => 0.012,              # Power in kilowatts (kW)
+#   "voltage_v" => 230.5,             # Voltage in volts (V)
+#   "current_a" => 0.054,             # Current in amps (A)
+#   "today_energy_wh" => 25,          # Today's energy in watt-hours (Wh)
+#   "today_energy_kwh" => 0.025,      # Today's energy in kilowatt-hours (kWh)
+#   "month_energy_wh" => 350,         # Month's energy in watt-hours (Wh)
+#   "month_energy_kwh" => 0.350,      # Month's energy in kilowatt-hours (kWh)
+#   "today_runtime_min" => 120,       # Today's runtime in minutes
+#   "today_runtime_hours" => 2.0,     # Today's runtime in hours
+#   "month_runtime_min" => 5400,      # Month's runtime in minutes
+#   "month_runtime_hours" => 90.0     # Month's runtime in hours
+# }
+```
+
+### Device Discovery
+
+```ruby
+# Find all devices on your network
+devices = Tapo::Discovery.discover
+
+devices.each do |ip|
+  puts "Found device at #{ip}"
+end
+```

data/lib/tapo/client.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'base64'
+require 'digest'
+
+module Tapo
+  class Client
+    attr_reader :device_ip
+
+    # @param device_ip [String] IP address of the Tapo device
+    # @param username [String] Tapo account email address
+    # @param password [String] Tapo account password
+    def initialize(device_ip, username, password)
+      @device_ip = device_ip
+      @username = username
+      @password = password
+      @session = nil
+    end
+
+    # @return [Boolean] true if authentication successful
+    # @raise [AuthenticationError] if authentication fails
+    def authenticate!
+      protocol = Protocol.detect(@device_ip)
+
+      case protocol
+      when :klap
+        authenticate_klap!
+      when :passthrough
+        raise UnsupportedProtocolError, 'Passthrough protocol not yet implemented'
+      else
+        raise AuthenticationError, 'Unable to detect device protocol'
+      end
+
+      true
+    end
+
+    # @return [Boolean] true if authenticated
+    def authenticated?
+      !@session.nil?
+    end
+
+    # @return [Hash] Response from device
+    def on
+      set_device_info(device_on: true)
+    end
+
+    # @return [Hash] Response from device
+    def off
+      set_device_info(device_on: false)
+    end
+
+    # @return [Hash] Device information including name, state, model, etc.
+    def device_info
+      response = request(method: 'get_device_info')
+      result = response['result']
+
+      # Decode base64-encoded fields
+      result['nickname'] = Base64.decode64(result['nickname']) if result['nickname']
+      result['ssid'] = Base64.decode64(result['ssid']) if result['ssid']
+
+      result
+    end
+
+    # @return [Hash] Energy usage data with proper units
+    def energy_usage
+      response = request(method: 'get_energy_usage')
+      result = response['result']
+
+      # Convert power: milliwatts -> watts
+      if result['current_power']
+        result['power_w'] = (result['current_power'] / 1000.0).round(3)
+        result['power_kw'] = (result['current_power'] / 1_000_000.0).round(3)
+      end
+
+      # Convert voltage: millivolts -> volts
+      if result['voltage_mv']
+        result['voltage_v'] = (result['voltage_mv'] / 1000.0).round(2)
+      end
+
+      # Convert current: milliamps -> amps
+      if result['current_ma']
+        result['current_a'] = (result['current_ma'] / 1000.0).round(3)
+      end
+
+      # Energy consumption with units
+      if result['today_energy']
+        result['today_energy_wh'] = result['today_energy']
+        result['today_energy_kwh'] = (result['today_energy'] / 1000.0).round(3)
+      end
+
+      if result['month_energy']
+        result['month_energy_wh'] = result['month_energy']
+        result['month_energy_kwh'] = (result['month_energy'] / 1000.0).round(3)
+      end
+
+      # Runtime with units
+      result['today_runtime_min'] = result['today_runtime'] if result['today_runtime']
+      result['month_runtime_min'] = result['month_runtime'] if result['month_runtime']
+
+      if result['today_runtime']
+        result['today_runtime_hours'] = (result['today_runtime'] / 60.0).round(2)
+      end
+
+      if result['month_runtime']
+        result['month_runtime_hours'] = (result['month_runtime'] / 60.0).round(2)
+      end
+
+      result
+    end
+
+    # @return [Float] Current power in watts (W)
+    def power_usage
+      energy = energy_usage
+      energy['power_w']
+    end
+
+
+    # @return [Float, nil] Current voltage in volts (V)
+    def voltage
+      energy = energy_usage
+      energy['voltage_v']
+    end
+
+    # @return [Float, nil] Current in amps (A)
+    def current
+      energy = energy_usage
+      energy['current_a']
+    end
+
+    # @return [Boolean] true if device is on
+    def on?
+      device_info['device_on']
+    end
+
+    # Check if device is off
+    #
+    # @return [Boolean] true if device is off
+    def off?
+      !on?
+    end
+
+    # @return [String] Device nickname
+    def nickname
+      device_info['nickname']
+    end
+
+    # @param params [Hash] Parameters to set (e.g., device_on: true)
+    # @return [Hash] Response from device
+    def set_device_info(params)
+      request(method: 'set_device_info', params: params)
+    end
+
+    # @param request_data [Hash] Request data
+    # @return [Hash] Response from device
+    # @raise [SessionExpiredError] if session has expired
+    # @raise [RequestError] if request fails
+    def request(request_data)
+      authenticate! unless authenticated?
+
+      json_payload = request_data.to_json
+
+      encrypted_payload, seq = @session[:cipher].encrypt(json_payload)
+
+      http = @session[:http]
+      request = Net::HTTP::Post.new("/app/request?seq=#{seq}", 'Content-Type' => 'application/octet-stream')
+      request['Cookie'] = @session[:cookie]
+      request.body = encrypted_payload
+
+      response = http.request(request)
+
+      if response.code == '403'
+        @session = nil
+        raise SessionExpiredError, 'Session expired, please re-authenticate'
+      end
+
+      raise RequestError, "Request failed with status #{response.code}" if response.code != '200'
+
+      decrypted_response = @session[:cipher].decrypt(response.body, seq)
+      result = JSON.parse(decrypted_response)
+
+      if result['error_code'] != 0
+        raise RequestError, "Device returned error code: #{result['error_code']}"
+      end
+
+      result
+    rescue SessionExpiredError
+      authenticate!
+      retry
+    end
+
+    private
+
+    def authenticate_klap!
+      base_url = "http://#{@device_ip}/app"
+      uri = URI(base_url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.read_timeout = 5
+      http.open_timeout = 5
+
+      username_hash = Digest::SHA1.digest(@username)
+      password_hash = Digest::SHA1.digest(@password)
+      auth_hash = Digest::SHA256.digest(username_hash + password_hash)
+
+      local_seed = OpenSSL::Random.random_bytes(16)
+
+      handshake1_req = Net::HTTP::Post.new('/app/handshake1', 'Content-Type' => 'application/octet-stream')
+      handshake1_req.body = local_seed
+
+      handshake1_res = http.request(handshake1_req)
+      raise AuthenticationError, "Handshake1 failed: #{handshake1_res.code}" if handshake1_res.code != '200'
+
+      cookie_header = handshake1_res['set-cookie']
+      cookie = nil
+      if cookie_header && cookie_header =~ /TP_SESSIONID=([^;]+)/
+        cookie = "TP_SESSIONID=#{Regexp.last_match(1)}"
+      end
+
+      response_body = handshake1_res.body
+      raise AuthenticationError, 'Response too small' if response_body.bytesize < 48
+
+      response_body = response_body[0, 48] if response_body.bytesize > 48
+
+      remote_seed = response_body[0, 16]
+      server_hash = response_body[16, 32]
+
+      local_hash = Digest::SHA256.digest(local_seed + remote_seed + auth_hash)
+      if local_hash != server_hash
+        raise AuthenticationError, 'Authentication failed - wrong credentials'
+      end
+
+      client_hash = Digest::SHA256.digest(remote_seed + local_seed + auth_hash)
+
+      handshake2_req = Net::HTTP::Post.new('/app/handshake2', 'Content-Type' => 'application/octet-stream')
+      handshake2_req['Cookie'] = cookie if cookie
+      handshake2_req.body = client_hash
+
+      handshake2_res = http.request(handshake2_req)
+      raise AuthenticationError, "Handshake2 failed: #{handshake2_res.code}" if handshake2_res.code != '200'
+
+      cipher = KlapCipher.new(local_seed, remote_seed, auth_hash)
+
+      @session = {
+        cookie: cookie,
+        cipher: cipher,
+        device_ip: @device_ip,
+        http: http
+      }
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise AuthenticationError, "Device not responding: #{e.message}"
+    end
+  end
+end

data/lib/tapo/discovery.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'timeout'
+require 'openssl'
+require 'json'
+require 'digest/crc32'
+
+module Tapo
+  module Discovery
+    DISCOVERY_PORT = 20002
+    BROADCAST_ADDR = '255.255.255.255'
+
+    # @param timeout [Integer] How long to listen for responses in seconds
+    # @return [Array<String>] Array of discovered device IP addresses
+    def self.discover(timeout: 5)
+      socket = UDPSocket.new
+      socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_BROADCAST, true)
+      socket.bind('0.0.0.0', 0)
+
+      payload = build_discovery_payload
+      socket.send(payload, 0, BROADCAST_ADDR, DISCOVERY_PORT)
+
+      listen_for_responses(socket, timeout)
+    ensure
+      socket&.close
+    end
+
+    # @return [String] Binary discovery packet
+    def self.build_discovery_payload
+      rsa_key = OpenSSL::PKey::RSA.new(1024)
+      public_key_pem = rsa_key.public_key.to_pem
+
+      json_body = {
+        params: {
+          rsa_key: public_key_pem
+        }
+      }.to_json
+
+      version = 2
+      msg_type = 0
+      op_code = 1
+      msg_size = json_body.bytesize
+      flags = 17
+      padding = 0
+      device_serial = rand(0..0xFFFFFFFF)
+      crc_placeholder = 0x5A6B7C8D
+
+      header = [
+        version, msg_type, op_code, msg_size, flags, padding,
+        device_serial, crc_placeholder
+      ].pack('CCnnCCNN')
+
+      full_message_for_crc = header + json_body
+      real_crc = Digest::CRC32.checksum(full_message_for_crc)
+
+      header[12, 4] = [real_crc].pack('N')
+
+      header + json_body
+    end
+
+    # @param socket [UDPSocket] The socket to listen on
+    # @param timeout [Integer] How long to listen in seconds
+    # @return [Array<String>] Array of discovered IP addresses
+    def self.listen_for_responses(socket, timeout)
+      discovered_ips = []
+
+      begin
+        Timeout.timeout(timeout) do
+          loop do
+            ready = IO.select([socket])
+            next unless ready
+
+            _, addr_info = socket.recvfrom_nonblock(2048)
+            device_ip = addr_info[2]
+
+            discovered_ips << device_ip unless discovered_ips.include?(device_ip)
+          end
+        end
+      rescue Timeout::Error
+        puts "Timeout reached"
+      rescue IO::WaitReadable
+        puts "No response received"
+      end
+
+      discovered_ips
+    end
+
+    private_class_method :build_discovery_payload, :listen_for_responses
+  end
+end

data/lib/tapo/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Tapo
+  class Error < StandardError; end
+
+  class DiscoveryError < Error; end
+
+  class AuthenticationError < Error; end
+
+  class RequestError < Error; end
+
+  class SessionExpiredError < Error; end
+
+  class UnsupportedProtocolError < Error; end
+end

data/lib/tapo/klap_cipher.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'digest'
+
+module Tapo
+  class KlapCipher
+    attr_reader :seq
+
+    # @param local_seed [String] 16-byte local seed
+    # @param remote_seed [String] 16-byte remote seed from device
+    # @param auth_hash [String] 32-byte authentication hash
+    def initialize(local_seed, remote_seed, auth_hash)
+      combined = local_seed + remote_seed + auth_hash
+
+      # Derive encryption key (16 bytes)
+      @key = Digest::SHA256.digest('lsk' + combined)[0, 16]
+
+      # Derive IV base (12 bytes) and initial sequence number
+      iv_hash = Digest::SHA256.digest('iv' + combined)
+      @iv_base = iv_hash[0, 12]
+      @seq = iv_hash[-4..-1].unpack1('N').to_i
+
+      # Derive signature key (28 bytes)
+      @signature_key = Digest::SHA256.digest('ldk' + combined)[0, 28]
+    end
+
+    # @param plaintext [String] The plaintext to encrypt
+    # @return [Array<String, Integer>] Encrypted payload (signature + ciphertext) and sequence number
+    def encrypt(plaintext)
+      @seq += 1
+
+      # Create message-specific IV
+      iv = @iv_base + [@seq].pack('N')
+
+      # Encrypt with AES-128-CBC
+      cipher = OpenSSL::Cipher.new('AES-128-CBC')
+      cipher.encrypt
+      cipher.key = @key
+      cipher.iv = iv
+      cipher.padding = 1 # PKCS7 padding
+
+      ciphertext = cipher.update(plaintext) + cipher.final
+
+      # Create signature
+      signature = Digest::SHA256.digest(@signature_key + [@seq].pack('N') + ciphertext)
+
+      [signature + ciphertext, @seq]
+    end
+
+    # @param encrypted_data [String] The encrypted data (signature + ciphertext)
+    # @param seq [Integer] The sequence number used for this message
+    # @return [String] Decrypted plaintext
+    def decrypt(encrypted_data, seq)
+      # Skip signature (first 32 bytes) and decrypt the rest
+      ciphertext = encrypted_data[32..-1]
+
+      # Create message-specific IV
+      iv = @iv_base + [seq].pack('N')
+
+      # Decrypt with AES-128-CBC
+      decipher = OpenSSL::Cipher.new('AES-128-CBC')
+      decipher.decrypt
+      decipher.key = @key
+      decipher.iv = iv
+      decipher.padding = 1 # PKCS7 padding
+
+      decipher.update(ciphertext) + decipher.final
+    end
+  end
+end

data/lib/tapo/protocol.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+
+module Tapo
+  module Protocol
+
+    # @param device_ip [String] IP address of the device
+    # @return [Symbol, nil] :klap, :passthrough, or nil if not a Tapo device
+    def self.detect(device_ip)
+      uri = URI("http://#{device_ip}/")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.read_timeout = 5
+      http.open_timeout = 5
+
+      request = Net::HTTP::Post.new(uri.request_uri, 'Content-Type' => 'application/json')
+      request.body = { method: 'get_device_info' }.to_json
+
+      response = http.request(request)
+
+      return :klap if response.code == '401'
+
+      begin
+        json_response = JSON.parse(response.body)
+        error_code = json_response['error_code']
+
+        # Error code 1003 = method not found - device doesn't support Passthrough Protocol
+        return :klap if error_code == 1003
+
+        # Other error codes indicate Passthrough protocol
+        :passthrough
+      rescue JSON::ParserError
+        # HTML/XML response - not a Tapo device
+        nil
+      end
+    rescue StandardError => e
+      warn "Protocol detection error for #{device_ip}: #{e.message}" if ENV['DEBUG']
+      nil
+    end
+  end
+end

data/lib/tapo/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Tapo
+  VERSION = '0.1.0'
+end

data/lib/tapo.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'tapo/version'
+require_relative 'tapo/errors'
+require_relative 'tapo/klap_cipher'
+require_relative 'tapo/discovery'
+require_relative 'tapo/protocol'
+require_relative 'tapo/client'
+
+# TP-Link Tapo Ruby Client
+#
+# A Ruby library for controlling TP-Link Tapo smart devices.
+# Supports device discovery, authentication, and control operations.
+#
+# @example Basic usage
+#   client = Tapo::Client.new('192.168.1.100', 'user@example.com', 'password')
+#   client.authenticate!
+#   client.on
+#   puts "Power usage: #{client.power_usage}W"
+#
+# @example Discovery
+#   devices = Tapo::Discovery.discover
+#   devices.each do |ip|
+#     puts "Found device at #{ip}"
+#   end
+module Tapo
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: tapo
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ashish Rao
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Control TP-Link Tapo smart plugs (P100, P110) with Ruby. Supports device
+  discovery, authentication via KLAP protocol, and energy monitoring.
+email:
+- ashishrao2598@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/tapo.rb
+- lib/tapo/client.rb
+- lib/tapo/discovery.rb
+- lib/tapo/errors.rb
+- lib/tapo/klap_cipher.rb
+- lib/tapo/protocol.rb
+- lib/tapo/version.rb
+homepage: https://github.com/ashishra0/tapo-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ashishra0/tapo-ruby
+  source_code_uri: https://github.com/ashishrao7/tapo-ruby
+  changelog_uri: https://github.com/ashishrao7/tapo-ruby/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for TP-Link Tapo smart devices
+test_files: []