mixergy 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ba0e27e53239f2c48a1a6ea61fa42e6a4e2b2ecf5d030d588e35d58e47497ac2
+  data.tar.gz: 855226c79aa3e988c883fcbb2fb629e70acbeea7846f4a1b09198c752562911d
+SHA512:
+  metadata.gz: fdc10ec896960d3e8afda031b8810504807b1c6bad3c74af12b8ee0f21379ac8d3e541d3b0e40ec4b2837eb2753f4f0b1c45d853032ba5901a13fdc4cb93a153
+  data.tar.gz: b6d8f53dcdcc806d378c6e9ad1d0dcd4fa9943069e2808d2d2c61924aea11f29311d72b4cca97ee25a52a1c230aee555fda681f39ad58d70d3c6d144ce650da6

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Nicholas Humfrey
+
+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,77 @@
+
+# Mixergy Ruby Client
+
+This gem provides a Ruby interface to the Mixergy Hot Water Tank REST API, making it easy to interact with tanks in a Rubyish way. There is also a CLI tool included to help with fetching an authentication token and interacting with the API.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mixergy', git: 'https://github.com/njh/ruby-mixergy.git'
+```
+
+Or install it directly:
+
+```bash
+git clone https://github.com/njh/ruby-mixergy.git
+cd ruby-mixergy
+bundle install
+```
+
+
+## Command Line Interface
+
+Included in the gem is a command line tool, to perform actions with the Mixergy API:
+
+```sh
+$ mixergy help 
+Commands:
+  mixergy boost           # Charge tank to 100%
+  mixergy charge PERCENT  # Charge tank to target percentage
+  mixergy help [COMMAND]  # Describe available commands or one specific command
+  mixergy login           # Login to Mixergy API and store token
+  mixergy status          # Display the current status of a tank
+  mixergy tanks           # List all your tanks
+  mixergy version         # Prints the Mixergy gem version
+```
+
+The `mixergy status` command displays some stats and a visualisation of the tank:
+
+<img src="doc/screenshot.png" height="400" alt="A screenshot of a Mac OS terminal running `mixergy status`" />
+
+To disable colour, set the `NO_COLOR` environment variable.
+
+
+## Config file format
+
+To avoid logging-in before each API request, there is support for saving the authentication token to a configuration file, stored as YAML in `~/.mixergy`.
+
+This file can be generated using the `mixergy login` CLI command.
+The default tank ID is also stored, to avoid having to lookup a list of tanks each time too.
+
+Example `~/.mixergy` file:
+
+```yaml
+---
+token: user/ooShoh7naaR1lai0Ahtie5miechaig7ei/12ab/Tie6sha0vah7onohchifeich2aipheifaiqu9beiphoim4queitheinoMoo2a
+default_tank_id: fcee127d-dad9-4ab4-a734-64586d0c0d68
+```
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. 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](https://rubygems.org).
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/njh/ruby-mixergy.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "standard/rake"
+require "yard"
+
+# YARD documentation task
+YARD::Rake::YardocTask.new(:yard) do |t|
+  t.files = ["lib/**/*.rb"]
+  t.options = ["--output-dir", "doc"]
+end
+
+task default: :standard

data/exe/mixergy

@@ -0,0 +1,117 @@
+#!/usr/bin/env ruby
+
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "thor"
+require "mixergy"
+require "mixergy/ascii_art"
+require "io/console"
+
+module Mixergy
+  class CLI < Thor
+    # Exit with a non-zero status code on failure
+    def self.exit_on_failure?
+      true
+    end
+
+    desc "version", "Prints the Mixergy gem version"
+    def version
+      puts Mixergy::VERSION
+    end
+
+    desc "login", "Login to Mixergy API and store token"
+    option :username, aliases: "-u", desc: "Username"
+    option :password, aliases: "-p", desc: "Password"
+    def login
+      username = options[:username] || prompt_for_username
+      password = options[:password] || prompt_for_password
+      client = Mixergy::Client.new
+      token = client.login(username, password)
+      if token
+        puts "Login successful!"
+        config = Mixergy::Config.new
+        puts "Writing token to #{config.filepath}"
+        config.load
+        config[:token] = token
+        if !config[:default_tank_id]
+          tank_id = client.tanks.first&.id
+          if tank_id
+            puts "Setting default tank ID to #{tank_id}"
+            config[:default_tank_id] = tank_id
+          end
+        end
+        config.save
+      end
+    end
+
+    desc "tanks", "List all your tanks"
+    def tanks
+      client = Mixergy::Client.new
+      client.load_config
+      tanks = client.tanks
+      if tanks.empty?
+        puts "No tanks found."
+      else
+        tanks.each do |tank|
+          puts "Serial: #{tank.serial_number}"
+          puts "Id: #{tank.id}"
+          puts
+        end
+      end
+    end
+
+    desc "status", "Display the current status of a tank"
+    def status
+      client = Mixergy::Client.new
+      client.load_config
+      # FIXME: add support for chosing a specific tank
+      status = client.status
+      puts "Charge: #{status.charge} %"
+      puts "Top Temperature: #{status.top_temperature} °C"
+      puts "Bottom Temperature: #{status.bottom_temperature} °C"
+      puts
+      puts Mixergy::AsciiArt.draw_tank(status.charge)
+      puts
+    end
+
+    desc "charge PERCENT", "Charge tank to target percentage"
+    def charge(percent)
+      percent = percent.to_i
+      unless percent.is_a?(Integer) && percent >= 0 && percent <= 100
+        raise ArgumentError, "percent must be an integer between 0 and 100."
+      end
+
+      client = Mixergy::Client.new
+      client.load_config
+      current_charge = client.status.charge
+      if client.set_charge(percent)
+        puts "Tank charging from #{current_charge} to #{percent}..."
+      else
+        puts "Failed to charge tank."
+      end
+    end
+
+    desc "boost", "Charge tank to 100%"
+    def boost
+      charge(100)
+    end
+
+    private
+
+    def prompt_for_username
+      print "Username: "
+      $stdin.gets.chomp
+    end
+
+    def prompt_for_password
+      print "Password: "
+      password = $stdin.noecho(&:gets)
+      puts
+      password.chomp
+    end
+  end
+end
+
+Mixergy::CLI.start

data/lib/mixergy/ascii_art.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "pastel"
+
+module Mixergy
+  module AsciiArt
+    # Draws an ASCII art hot water cylinder representing a charge level.
+    # @param charge [Numeric] The charge percentage (0-100).
+    # @param width [Integer] The width of the tank (default: 7).
+    # @param height [Integer] The height of the tank (default: 10).
+    # @return [String] The ASCII art representation of the tank.
+    def self.draw_tank(charge, width: 7, height: 10)
+      fill_height = (height * charge / 100.0).round
+      pastel = Pastel.new
+
+      tank = []
+      tank << " ╭#{"─" * width}╮"
+      height.times do |i|
+        tank << if i < height - fill_height
+          " │#{pastel.blue.on_blue(" ") * width}│"
+        else
+          " │#{pastel.red.on_red("█") * width}│"
+        end
+      end
+      tank << " ╰#{"─" * width}╯"
+      tank.join("\n")
+    end
+  end
+end

data/lib/mixergy/client.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require_relative "config"
+require_relative "error"
+require_relative "tank"
+require_relative "status"
+
+module Mixergy
+  class Client
+    API_ROOT = "https://www.mixergy.io/api/v2"
+
+    # Create a new Mixergy API client.
+    def initialize
+      @connection = Faraday.new(
+        url: API_ROOT
+      ) do |faraday|
+        faraday.request :json      # Automatically encode request bodies as JSON
+        faraday.response :json     # Automatically parse response bodies as JSON
+      end
+    end
+
+    # Loads configuration from ~/.mixergy and sets the API token if present.
+    # @return [Mixergy::Config] the loaded config object
+    def load_config
+      @config ||= begin
+        config = Mixergy::Config.new
+        config.load
+        # FIXME: find a better place to put this
+        @connection.headers["Authorization"] = "Bearer #{config[:token]}"
+        config
+      end
+    end
+
+    # Authenticates with the Mixergy API and stores the token in the connection.
+    # @param username [String] the username
+    # @param password [String] the password
+    # @return [String] the authentication token
+    # @raise [Mixergy::Error] if login fails
+    def login(username, password)
+      resp = @connection.post(
+        "account/login",
+        {username: username, password: password}
+      )
+      data = resp.body
+
+      if data["token"]
+        @connection.headers["Authorization"] = "Bearer #{data["token"]}"
+        data["token"]
+      else
+        raise Mixergy::Error, "Login failed (status: #{resp.status}, body: #{resp.body.inspect})"
+      end
+    end
+
+    # Fetches all tanks associated with the account.
+    # @return [Array<Tank>] list of Tank objects
+    def tanks
+      resp = @connection.get("tanks")
+      tank_list = resp.body.dig("_embedded", "tankList") || []
+      tank_list.map do |tank_data|
+        Tank.new(tank_data)
+      end
+    end
+
+    # Returns the default tank ID from config, or the first tank's ID.
+    # @return [String, nil] the default tank ID
+    def default_tank_id
+      @default_tank_id ||= begin
+        load_config
+        @config[:default_tank_id] || tanks.first&.id
+      end
+    end
+
+    # Fetches the latest status/measurement for a tank.
+    # @param tank [Tank, nil] the tank object (optional)
+    # @return [Status] the status object for the tank
+    def status(tank = nil)
+      tank_id = tank.id if tank.is_a?(Tank)
+      tank_id = default_tank_id if tank_id.nil?
+      resp = @connection.get("tanks/#{tank_id}/measurements/latest")
+      Status.new(resp.body)
+    end
+
+    # Sets the target charge for a tank via the control endpoint.
+    # @param percent [Integer] the target charge percentage
+    # @param tank [Tank, String, nil] the Tank object or Tank GUID (optional)
+    # @return [Boolean] true if successful, false otherwise
+    def set_charge(percent, tank = nil)
+      tank_id = tank.id if tank.is_a?(Tank)
+      tank_id = default_tank_id if tank_id.nil?
+      resp = @connection.put("tanks/#{tank_id}/control", {charge: percent})
+      resp.success?
+    end
+  end
+end

data/lib/mixergy/config.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+# Mixergy::Config handles loading and saving user configuration as a YAML file.
+# The default config file is ~/.mixergy.
+module Mixergy
+  # Configuration handler for Mixergy CLI and API clients.
+  # Loads and saves config as YAML, provides hash-like access.
+  class Config
+    # Default path for the config file (~/.mixergy)
+    DEFAULT_CONFIG_PATH = File.expand_path("~/.mixergy")
+
+    # @return [String] Path to the config file
+    attr_reader :filepath
+    # @return [Hash] The loaded config data
+    attr_reader :data
+
+    # Create a new Config object and load config from disk.
+    # @param config_path [String] Optional path to config file
+    def initialize(config_path = DEFAULT_CONFIG_PATH)
+      @filepath = config_path
+      @data = load
+    end
+
+    # Load config from disk.
+    # @return [Hash] The loaded config data
+    def load
+      if File.exist?(@filepath)
+        YAML.load_file(@filepath) || {}
+      else
+        {}
+      end
+    end
+
+    # Save current config data to disk.
+    # @return [void]
+    def save
+      File.write(@filepath, YAML.dump(@data))
+    end
+
+    # Get a config value by key.
+    # @param key [String, Symbol]
+    # @return [Object, nil] Value for the key
+    def [](key)
+      @data[key.to_s]
+    end
+
+    # Set a config value by key.
+    # @param key [String, Symbol]
+    # @param value [Object]
+    # @return [void]
+    def []=(key, value)
+      @data[key.to_s] = value
+    end
+  end
+end

data/lib/mixergy/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Mixergy::Error is the base exception class for all Mixergy-related errors.
+# Raise this for API, configuration, or client errors.
+module Mixergy
+  # Base exception class for Mixergy errors.
+  # All custom errors should inherit from this.
+  class Error < StandardError; end
+end

data/lib/mixergy/status.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Mixergy::Status represents the latest measurement/status of a tank.
+# It provides access to charge, temperature, and other metrics.
+module Mixergy
+  # Represents the latest status/measurement for a Mixergy tank.
+  class Status
+    # @return [Float] Current charge percentage
+    attr_reader :charge
+    # @return [Float] Top temperature in Celsius
+    attr_reader :top_temperature
+    # @return [Float] Bottom temperature in Celsius
+    attr_reader :bottom_temperature
+    # @return [Float] Frequency in Hz
+    attr_reader :frequency
+    # @return [Float] Voltage in Volts
+    attr_reader :voltage
+    # @return [Float] Current in Amps
+    attr_reader :current
+
+    # Create a new Status object from API data.
+    # @param data [Hash] API response data for latest measurement
+    def initialize(data = {})
+      @charge = data["charge"]
+      @top_temperature = data["topTemperature"]
+      @bottom_temperature = data["bottomTemperature"]
+      @frequency = data["frequency"]
+      @voltage = data["voltage"]
+      @current = data["current"]
+    end
+  end
+end

data/lib/mixergy/tank.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Mixergy::Tank represents a physical Mixergy tank and its metadata.
+# Provides access to tank ID, type, model, volume, firmware version, and serial number.
+module Mixergy
+  # Represents a Mixergy tank and its metadata.
+  class Tank
+    # @return [String] Unique tank ID
+    attr_reader :id
+    # @return [String] Tank type
+    attr_reader :type
+    # @return [String] Tank model code
+    attr_reader :model
+    # @return [Float] Tank volume in liters
+    attr_reader :volume
+    # @return [String] Firmware version
+    attr_reader :firmware_version
+    # @return [String] Serial number
+    attr_reader :serial_number
+
+    # Create a new Tank object from API data.
+    # @param data [Hash, nil] API response data for the tank
+    def initialize(data = nil)
+      if data
+        @id = data["id"]
+        @type = data["type"]
+        @model = data["tankModelCode"]
+        @volume = data["volume"]
+        @firmware_version = data["firmwareVersion"]
+        @serial_number = data["serialNumber"]
+      end
+    end
+  end
+end

data/lib/mixergy/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Mixergy gem version constant.
+module Mixergy
+  # The current version of the Mixergy gem.
+  # Update this value for each gem release.
+  VERSION = "0.1.0"
+end

data/lib/mixergy.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "mixergy/version"
+require_relative "mixergy/client"
+require_relative "mixergy/config"
+require_relative "mixergy/error"

data/sig/mixergy.rbs

@@ -0,0 +1,4 @@
+module Mixergy
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: mixergy
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nicholas J. Humfrey
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-09-16 00:00:00.000000000 Z
+dependencies:
+- !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: thor
+  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: pastel
+  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: This gem provides a simple interface for interacting with the Mixergy
+  API, allowing users to manage their hot water tanks programmatically.
+email:
+- njh@aelius.com
+executables:
+- mixergy
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- doc/screenshot.png
+- exe/mixergy
+- lib/mixergy.rb
+- lib/mixergy/ascii_art.rb
+- lib/mixergy/client.rb
+- lib/mixergy/config.rb
+- lib/mixergy/error.rb
+- lib/mixergy/status.rb
+- lib/mixergy/tank.rb
+- lib/mixergy/version.rb
+- sig/mixergy.rbs
+homepage: https://github.com/njh/ruby-mixergy
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/njh/ruby-mixergy
+  source_code_uri: https://github.com/njh/ruby-mixergy.git
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Ruby gem for controlling Mixergy hot water tanks
+test_files: []