stekker_zaptec 1.0.0

data/lib/zaptec/charger.rb

@@ -0,0 +1,38 @@
+module Zaptec
+  class Charger
+    attr_reader :id,
+                :name,
+                :device_id,
+                :device_type,
+                :installation_name,
+                :installation_id
+
+    def initialize(
+      id:,
+      name:,
+      device_id:,
+      device_type:,
+      installation_name:,
+      installation_id:
+    )
+
+      @id = id
+      @name = name
+      @device_id = device_id
+      @device_type = device_type
+      @installation_name = installation_name
+      @installation_id = installation_id
+    end
+
+    def self.parse(data)
+      new(
+        id: data.fetch("Id"),
+        name: data.fetch("Name"),
+        device_id: data.fetch("DeviceId"),
+        device_type: data.fetch("DeviceType"),
+        installation_name: data.fetch("InstallationName"),
+        installation_id: data.fetch("InstallationId")
+      )
+    end
+  end
+end

data/lib/zaptec/client.rb

@@ -0,0 +1,111 @@
+module Zaptec
+  class Client
+    BASE_URI = "https://api.zaptec.com".freeze
+    USER_ROLE = 1
+    OWNER_ROLE = 2
+
+    attr_reader :http_client, :credentials
+
+    delegate :expired?,
+             :access_token,
+             :expires_at,
+             to: :credentials,
+             prefix: true
+
+    def initialize(credentials: nil)
+      @credentials = credentials
+
+      @http_client = Faraday.new(url: BASE_URI) do |conn|
+        conn.request :json
+        conn.response :json
+        conn.response :raise_error
+      end
+    end
+
+    # https://zaptec.com/downloads/ZapChargerPro_Integration.pdf
+    def authorize(username:, password:)
+      raise Errors::ParameterMissing if username.blank? || password.blank?
+
+      start = Time.zone.now
+
+      response = http_client.post(
+        "#{BASE_URI}/oauth/token",
+        {
+          username: username,
+          password: password,
+          grant_type: "password"
+        }.to_query,
+        {
+          "Content-Type": "application/x-www-form-urlencoded"
+        }
+      )
+
+      @credentials = Zaptec::Credentials.new(
+        response.body["access_token"],
+        start + response.body["expires_in"].to_f
+      )
+    rescue Faraday::BadRequestError
+      raise Errors::AuthorizationFailed
+    end
+
+    # https://api.zaptec.com/help/index.html#/Charger/get_api_chargers
+    def chargers
+      get("/api/chargers", { Roles: USER_ROLE | OWNER_ROLE })
+        .body
+        .fetch("Data")
+        .map { |data| Charger.parse(data) }
+    end
+
+    # https://api.zaptec.com/help/index.html#/Charger/get_api_chargers__id__state
+    def state(charger_id, device_type)
+      get("/api/chargers/#{charger_id}/state")
+        .body
+        .to_h do |state|
+          [
+            Constants.observation_state_id_to_name(state_id: state.fetch("StateId"), device_type: device_type),
+            state.fetch("ValueAsString", nil)
+          ]
+        end
+        .then { |data| State.new(data) }
+    end
+
+    def pause_charging(charger_id) = send_command(charger_id, :StopChargingFinal)
+
+    def resume_charging(charger_id) = send_command(charger_id, :ResumeCharging)
+
+    private
+
+    # https://api.zaptec.com/help/index.html#/Charger/post_api_chargers__id__sendCommand__commandId_
+    def send_command(charger_id, command)
+      command_id = Constants.command_to_command_id(command)
+
+      post("/api/chargers/#{charger_id}/sendCommand/#{command_id}")
+    end
+
+    def get(endpoint, query = {})
+      require_valid_credentials!
+
+      http_client.get(
+        "#{BASE_URI}#{endpoint}",
+        query,
+        { Authorization: "Bearer #{credentials.access_token}" }
+      )
+    end
+
+    def post(endpoint, body = nil)
+      require_valid_credentials!
+
+      http_client.post(
+        "#{BASE_URI}#{endpoint}",
+        body,
+        { Authorization: "Bearer #{credentials.access_token}" }
+      )
+    rescue Faraday::Error => e
+      raise Errors::RequestFailed, "Request returned status #{e.response_status}"
+    end
+
+    def require_valid_credentials!
+      raise Errors::Unauthorized if credentials.blank? || credentials.expired?
+    end
+  end
+end

data/lib/zaptec/constants.rb

@@ -0,0 +1,57 @@
+module Zaptec
+  class Constants
+    class << self
+      def observation_state_id_to_name(state_id:, device_type:)
+        device_type_observation_ids(device_type)
+          .fetch(state_id)
+      end
+
+      def charger_operation_mode_to_name(operation_mode)
+        constants
+          .fetch("ChargerOperationModes")
+          .detect { |_name, mode| mode == operation_mode }
+          .then { |name, _mode| name }
+      end
+
+      def command_to_command_id(command)
+        constants
+          .fetch("Commands")
+          .fetch(command.to_s) { raise "Unknown command '#{command}'" }
+      end
+
+      private
+
+      def device_type_observation_ids(device_type)
+        @device_type_observation_ids ||= {}
+
+        @device_type_observation_ids[device_type] ||=
+          begin
+            global_observation_ids = constants.fetch("Observations").invert.transform_values(&:to_sym)
+
+            device_specific_observations =
+              constants
+                .fetch("Schema")
+                .fetch(device_type_to_name(device_type))
+                .fetch("ObservationIds")
+                .invert
+                .transform_values(&:to_sym)
+
+            global_observation_ids.merge(device_specific_observations)
+          end
+      end
+
+      def device_type_to_name(device_type)
+        constants
+          .fetch("DeviceTypes")
+          .detect { |_name, type| type == device_type }
+          .then { |name, _type| name }
+      end
+
+      def constants
+        @constants ||= JSON.parse(constants_file.read)
+      end
+
+      def constants_file = Pathname.new(__dir__).join("../../data/constants.json")
+    end
+  end
+end

data/lib/zaptec/credentials.rb

@@ -0,0 +1,14 @@
+module Zaptec
+  class Credentials
+    attr_accessor :access_token, :expires_at
+
+    def initialize(access_token, expires_at)
+      @access_token = access_token
+      @expires_at = expires_at
+    end
+
+    def expired?(at = Time.zone.now)
+      expires_at.nil? || at >= expires_at
+    end
+  end
+end

data/lib/zaptec/errors.rb

@@ -0,0 +1,9 @@
+module Zaptec
+  module Errors
+    class Base < StandardError; end
+    class ParameterMissing < Base; end
+    class Unauthorized < Base; end
+    class RequestFailed < Base; end
+    class AuthorizationFailed < Base; end
+  end
+end

data/lib/zaptec/meter_reading.rb

@@ -0,0 +1,10 @@
+module Zaptec
+  class MeterReading
+    attr_reader :reading_kwh, :timestamp
+
+    def initialize(reading_kwh:, timestamp:)
+      @reading_kwh = reading_kwh
+      @timestamp = timestamp
+    end
+  end
+end

data/lib/zaptec/state.rb

@@ -0,0 +1,32 @@
+module Zaptec
+  class State
+    CHARGING_MODES = %w[Connected_Requesting Connected_Charging].freeze
+    DISCONNECTED = "Disconnected".freeze
+
+    def initialize(data)
+      @data = data
+    end
+
+    def total_charge_power = @data.fetch(:TotalChargePower).to_f
+
+    def max_phases = @data.fetch(:MaxPhases).to_i
+
+    def total_charge_power_session = @data.fetch(:TotalChargePowerSession).to_f
+
+    def charging? = charger_operation_mode.in?(CHARGING_MODES)
+
+    def disconnected? = charger_operation_mode == DISCONNECTED
+
+    def online? = @data.fetch(:IsOnline).to_i.positive?
+
+    def meter_reading
+      @meter_reading ||= MeterReading.new(reading_kwh: total_charge_power_session, timestamp: Time.zone.now)
+    end
+
+    private
+
+    def charger_operation_mode
+      Constants.charger_operation_mode_to_name(@data.fetch(:ChargerOperationMode).to_i)
+    end
+  end
+end

data/lib/zaptec/version.rb

@@ -0,0 +1,3 @@
+module Zaptec
+  VERSION = "1.0.0".freeze
+end

data/lib/zaptec.rb

@@ -0,0 +1,18 @@
+require "faraday"
+require "faraday_middleware"
+require "faraday/detailed_logger"
+require "faraday-cookie_jar"
+require "active_model"
+require "active_support/all"
+
+require "zaptec/charger"
+require "zaptec/client"
+require "zaptec/constants"
+require "zaptec/credentials"
+require "zaptec/errors"
+require "zaptec/meter_reading"
+require "zaptec/state"
+require "zaptec/version"
+
+module Zaptec
+end

data/zaptec.gemspec

@@ -0,0 +1,36 @@
+require_relative "lib/zaptec/version"
+ruby_version = File.read(".ruby-version").strip
+
+Gem::Specification.new do |spec|
+  spec.name          = "stekker_zaptec"
+  spec.version       = Zaptec::VERSION
+  spec.authors       = ["Team Stekker"]
+  spec.email         = ["support@stekker.com"]
+
+  spec.summary       = "Connect to your Zaptec charger"
+  spec.description   = "Zaptec connector"
+  spec.homepage      = "https://stekker.com"
+  spec.required_ruby_version = Gem::Requirement.new(">= #{ruby_version}")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/stekker/zaptec"
+  spec.metadata["changelog_uri"] = "https://github.com/stekker/zaptec"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "activemodel"
+  spec.add_runtime_dependency "activesupport"
+  spec.add_runtime_dependency "faraday"
+  spec.add_runtime_dependency "faraday-cookie_jar"
+  spec.add_runtime_dependency "faraday-detailed_logger"
+  spec.add_runtime_dependency "faraday_middleware"
+
+  spec.metadata["rubygems_mfa_required"] = "true"
+end

metadata

@@ -0,0 +1,156 @@
+--- !ruby/object:Gem::Specification
+name: stekker_zaptec
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Team Stekker
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-02-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday-cookie_jar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday-detailed_logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Zaptec connector
+email:
+- support@stekker.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ruby.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- StekkerWeb/gems/zaptec/.gitignore
+- StekkerWeb/gems/zaptec/.rspec
+- StekkerWeb/gems/zaptec/.rubocop.yml
+- StekkerWeb/gems/zaptec/.ruby-version
+- bin/console
+- bin/setup
+- data/constants.json
+- lib/zaptec.rb
+- lib/zaptec/charger.rb
+- lib/zaptec/client.rb
+- lib/zaptec/constants.rb
+- lib/zaptec/credentials.rb
+- lib/zaptec/errors.rb
+- lib/zaptec/meter_reading.rb
+- lib/zaptec/state.rb
+- lib/zaptec/version.rb
+- zaptec.gemspec
+homepage: https://stekker.com
+licenses: []
+metadata:
+  homepage_uri: https://stekker.com
+  source_code_uri: https://github.com/stekker/zaptec
+  changelog_uri: https://github.com/stekker/zaptec
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.22
+signing_key:
+specification_version: 4
+summary: Connect to your Zaptec charger
+test_files: []