particlerb 0.0.1

data/README.md

@@ -0,0 +1,136 @@
+# particlerb [![Build Status](https://travis-ci.org/monkbroc/particlerb.svg)](https://travis-ci.org/monkbroc/particlerb)
+
+Ruby client for the [Particle.io] Cloud API
+
+[Particle.io]: https://www.particle.io
+
+*Note: this is not an official gem by Particle. It is maintained by Julien Vanier.*
+
+## Quick start
+
+Install via Rubygems
+
+    gem install particlerb
+
+... or add to your Gemfile
+
+    gem "particlerb", "~> 0.0.1"
+
+
+### Making requests
+
+API methods are available as module methods (consuming module-level
+configuration) or as client instance methods.
+
+```ruby
+# Provide authentication credentials
+Particle.configure do |c|
+  c.access_token = "38bb7b318cc6898c80317decb34525844bc9db55"
+end
+
+# Fetch the list of devices
+Particle.devices
+```
+or
+
+```ruby
+# Provide authentication credentials
+client = Particle::Client.new(access_token: "38bb7b318cc6898c80317decb34525844bc9db55")
+# Fetch the list of devices
+client.devices
+```
+
+## Device commands
+
+See the [Particle Cloud API documentation][API docs] for more details.
+
+List all devices (returns an `Array` of `Device`)
+```ruby
+devices = Particle.devices
+```
+
+Get a `Device` by id or name
+```ruby
+device = Particle.device('blue_fire')
+device = Particle.device('f8bbe1e6e69e05c9c405ba1ca504d438061f1b0d')
+```
+
+Get information about a device
+```ruby
+device = Particle.device('blue_fire')
+device.id
+device.name
+device.connected?
+device.variables
+device.functions
+device.attributes     # Hash of all attributes
+device.get_attributes # forces refresh of all attributes from the cloud
+```
+
+Claim a device and add it to your account (returns the `Device`)
+```ruby
+Particle.device('blue_fire').claim
+```
+
+Remove a device from your account
+```ruby
+Particle.device('blue_fire').remove
+Particle.devices.first.remove
+```
+
+Rename a device
+```ruby
+Particle.device('red').rename('green')
+```
+
+Call a function on the firmware (returns the result of running the function)
+```ruby
+Particle.device('coffeemaker').function('brew') # String argument optional
+Particle.devices.first.function('digitalWrite', '1')
+```
+
+Get the value of a firmware variable (returns the result as a String or Number)
+```ruby
+Particle.device('mycar').variable('battery') # ==> 12.33
+device = Particle.device('f8bbe1e6e69e05c9c405ba1ca504d438061f1b0d')
+device.variable('version') # ==> "1.0.1"
+```
+
+
+Signal a device to start blinking the RGB LED in rainbow patterns.
+```ruby
+Particle.device('nyan_cat').signal(true)
+```
+
+
+[API docs]: http://docs.particle.io/core/api
+
+### Accessing HTTP responses
+
+While most methods return a domain object like `Device`, sometimes you may
+need access to the raw HTTP response headers. You can access the last HTTP
+response with `Client#last_response`:
+
+```ruby
+device   = Particle.device('123456').claim
+response = Particle.last_response
+headers  = response.headers
+```
+
+## Thanks
+
+This gem is heavily inspired by [Octokit][] by GitHub. I stand on the shoulder of giants. Thanks!
+
+Octokit is copyright (c) 2009-2014 Wynn Netherland, Adam Stacoviak, Erik Michaels-Ober and licensed under the [MIT license][Octokit license].
+
+[Octokit]: http://github.com/octokit/octokit.rb
+[Octokit license]: https://github.com/octokit/octokit.rb/blob/master/LICENSE.md
+
+
+## License
+
+Copyright (c) 2015 Julien Vanier
+
+This gem is available under the [GNU General Public License version 3][GPL-v3]
+
+[GPL-v3]: https://github.com/monkbroc/particlerb/blob/master/LICENSE.txt

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :test => :spec
+task :default => :spec

data/lib/particle/client/devices.rb

@@ -0,0 +1,109 @@
+module Particle
+  class Client
+
+    # Methods for the Particle device API
+    # @see http://docs.particle.io/core/api/#introduction-list-devices
+    module Devices
+
+      # Create a domain model for a Particle device
+      #
+      # @param target [String, Sawyer::Resource, Device] A device id, name or {Device} object
+      # @return [Device] A device object to interact with
+      def device(target)
+        if target.is_a? Device
+          target
+        elsif target.respond_to?(:to_attrs)
+          Device.new(self, target.to_attrs)
+        else
+          Device.new(self, target.to_s)
+        end
+      end
+
+      # List all Particle devices on the account
+      #
+      # @see http://docs.particle.io/core/api/#introduction-list-devices
+      #
+      # @return [Array<Device>] List of Particle devices to interact with
+      def devices
+        get(Device.list_path).map do |resource|
+          Device.new(self, resource)
+        end
+      end
+
+      # Get information about a Particle device
+      #
+      # @param target [String, Device] A device id, name or {Device} object
+      # @return [Hash] The device attributes
+      def device_attributes(target)
+        result = get(device(target).path)
+        result.to_attrs
+      end
+
+      # Add a Particle device to your account
+      #
+      # @param target [String, Device] A device id or {Device} object.
+      #                                You can't claim a device by name
+      # @return [Device] A device object to interact with
+      def claim_device(target)
+        result = post(Device.claim_path, id: device(target).id_or_name)
+        device(result.id)
+      end
+
+      # Remove a Particle device from your account
+      #
+      # @param target [String, Device] A device id, name or {Device} object
+      # @return [boolean] true for success
+      def remove_device(target)
+        result = delete(device(target).path)
+        result.ok
+      end
+
+      # Rename a Particle device in your account
+      #
+      # @param target [String, Device] A device id, name or {Device} object
+      # @param name [String] New name for the device
+      # @return [boolean] true for success
+      def rename_device(target, name)
+        result = put(device(target).path, name: name)
+        result.name == name
+      end
+
+      # Call a function in the firmware of a Particle device
+      #
+      # @param target [String, Device] A device id, name or {Device} object
+      # @param name [String] Function to run on firmware
+      # @param argument [String] Argument string to pass to the firmware function
+      # @return [Integer] Return value from the firmware function
+      def call_function(target, name, argument = "")
+        result = post(device(target).function_path(name), arg: argument)
+        result.return_value
+      end
+
+      # Get the value of a variable in the firmware of a Particle device
+      #
+      # @param target [String, Device] A device id, name or {Device} object
+      # @param name [String] Variable on firmware
+      # @return [String, Number] Value from the firmware variable
+      def get_variable(target, name)
+        result = get(device(target).variable_path(name))
+        result.result
+      end
+
+      # Signal the device to start blinking the RGB LED in a rainbow
+      # pattern. Useful to identify a particular device.
+      #
+      # @param target [String, Device] A device id, name or {Device} object
+      # @param enabled [String] Whether to enable or disable the rainbow signal
+      # @return [boolean] true when signaling, false when stopped
+      def signal_device(target, enabled = true)
+        result = put(device(target).path, signal: enabled ? '1' : '0')
+        # FIXME: API bug. Should return HTTP 408 so result.ok wouldn't be necessary
+        if result.ok == false
+          false
+        else
+          result.signaling
+        end
+      end
+    end
+  end
+end

data/lib/particle/client.rb

@@ -0,0 +1,44 @@
+require 'particle/connection'
+require 'particle/device'
+require 'particle/client/devices'
+
+module Particle
+
+  # Client for the Particle API
+  #
+  # @see http://docs.particle.io/
+  class Client
+    include Particle::Configurable
+    include Particle::Connection
+    include Particle::Client::Devices
+
+    def initialize(options = {})
+      # Use options passed in, but fall back to module defaults
+      Particle::Configurable.keys.each do |key|
+        instance_variable_set(:"@#{key}", options[key] || Particle.instance_variable_get(:"@#{key}"))
+      end
+    end
+
+    # Text representation of the client, masking tokens
+    #
+    # @return [String]
+    def inspect
+      inspected = super
+
+      # Only show last 4 of token, secret
+      if @access_token
+        inspected = inspected.gsub! @access_token, "#{'*'*36}#{@access_token[36..-1]}"
+      end
+
+      inspected
+    end
+
+    # Set OAuth2 access token for authentication
+    #
+    # @param value [String] 40 character Particle OAuth2 access token
+    def access_token=(value)
+      reset_agent
+      @access_token = value
+    end
+  end
+end

data/lib/particle/configurable.rb

@@ -0,0 +1,64 @@
+module Particle
+
+  # Configuration options for {Client}, defaulting to values in
+  # {Default}
+  module Configurable
+    # @!attribute [w] access_token
+    #   @see http://docs.particle.io/core/api/#introduction-authentication
+    #   @return [String] Particle access token for authentication
+    # @!attribute api_endpoint
+    #   @return [String] Base URL for API requests. default: https://api.particle.io
+    # @!attribute connection_options
+    #   @see https://github.com/lostisland/faraday
+    #   @return [Hash] Configure connection options for Faraday
+    # @!attribute user_agent
+    #   @return [String] Configure User-Agent header for requests.
+
+    attr_accessor :access_token, :connection_options,
+      :user_agent
+    attr_writer :api_endpoint
+
+    class << self
+      def keys
+        @keys ||= [
+          :access_token,
+          :api_endpoint,
+          :connection_options,
+          :user_agent
+        ]
+      end
+    end
+
+    # Yields an object to set up configuration options in an initializer
+    # file
+    def configure
+      yield self
+    end
+
+    # Reset configuration options to default values
+    def reset!
+      Particle::Configurable.keys.each do |key|
+        instance_variable_set :"@#{key}", Particle::Default.options[key]
+      end
+    end
+
+    # Compares client options to a Hash of requested options
+    #
+    # @param opts [Hash] Options to compare with current client options
+    # @return [Boolean]
+    def same_options?(opts)
+      opts.hash == options.hash
+    end
+
+    # Clever way to add / at the end of the api_endpoint
+    def api_endpoint
+      File.join(@api_endpoint, "")
+    end
+
+    private
+
+    def options
+      Hash[Particle::Configurable.keys.map{ |key| [key, instance_variable_get(:"@#{key}")] }]
+    end
+  end
+end

data/lib/particle/connection.rb

@@ -0,0 +1,125 @@
+require 'sawyer'
+require 'particle/response/raise_error'
+
+module Particle
+
+  # Network layer for API client
+  module Connection
+
+    # Faraday middleware stack
+    MIDDLEWARE = Faraday::RackBuilder.new do |builder|
+      builder.use Particle::Response::RaiseError
+      builder.adapter Faraday.default_adapter
+    end
+
+    # Make a HTTP GET request
+    #
+    # @param url [String] The path, relative to {#api_endpoint}
+    # @param options [Hash] Query and header params for request
+    # @return [Sawyer::Resource]
+    def get(url, options = {})
+      request :get, url, options
+    end
+
+    # Make a HTTP POST request
+    #
+    # @param url [String] The path, relative to {#api_endpoint}
+    # @param options [Hash] Body and header params for request
+    # @return [Sawyer::Resource]
+    def post(url, options = {})
+      request :post, url, options
+    end
+
+    # Make a HTTP PUT request
+    #
+    # @param url [String] The path, relative to {#api_endpoint}
+    # @param options [Hash] Body and header params for request
+    # @return [Sawyer::Resource]
+    def put(url, options = {})
+      request :put, url, options
+    end
+
+    # Make a HTTP PATCH request
+    #
+    # @param url [String] The path, relative to {#api_endpoint}
+    # @param options [Hash] Body and header params for request
+    # @return [Sawyer::Resource]
+    def patch(url, options = {})
+      request :patch, url, options
+    end
+
+    # Make a HTTP DELETE request
+    #
+    # @param url [String] The path, relative to {#api_endpoint}
+    # @param options [Hash] Query and header params for request
+    # @return [Sawyer::Resource]
+    def delete(url, options = {})
+      request :delete, url, options
+    end
+
+    # Make a HTTP HEAD request
+    #
+    # @param url [String] The path, relative to {#api_endpoint}
+    # @param options [Hash] Query and header params for request
+    # @return [Sawyer::Resource]
+    def head(url, options = {})
+      request :head, url, parse_query_and_convenience_headers(options)
+    end
+
+    # Hypermedia agent for the Particle API
+    #
+    # @return [Sawyer::Agent]
+    def agent
+      @agent ||= Sawyer::Agent.new(endpoint, sawyer_options) do |http|
+        http.headers[:content_type] = "application/json"
+        http.headers[:user_agent] = user_agent
+        if @access_token
+          http.authorization :Bearer, @access_token
+        end
+      end
+    end
+
+    # Response for last HTTP request
+    #
+    # @return [Sawyer::Response]
+    attr_reader :last_response
+
+    protected
+
+    def endpoint
+      api_endpoint
+    end
+
+    private
+
+    def reset_agent
+      @agent = nil
+    end
+
+    def request(method, path, data, options = {})
+      if data.is_a?(Hash)
+        options[:query]   = data.delete(:query) || {}
+        options[:headers] = data.delete(:headers) || {}
+        if accept = data.delete(:accept)
+          options[:headers][:accept] = accept
+        end
+      end
+
+      @last_response = response = agent.call(method, URI::Parser.new.escape(path.to_s), data, options)
+      response.data
+    end
+
+    def sawyer_options
+      opts = {
+        :links_parser => Sawyer::LinkParsers::Simple.new
+      }
+      conn_opts = @connection_options.dup
+      conn_opts[:builder] = MIDDLEWARE
+      conn_opts[:proxy] = @proxy if @proxy
+      opts[:faraday] = Faraday.new(conn_opts)
+
+      opts
+    end
+  end
+end
+

data/lib/particle/default.rb

@@ -0,0 +1,44 @@
+require 'particle/version'
+
+module Particle
+
+  # Default configuration options for {Client}
+  module Default
+    API_ENDPOINT = "https://api.particle.io".freeze
+
+    USER_AGENT = "particlerb Ruby gem #{Particle::VERSION}".freeze
+
+    class << self
+
+      # Configuration options
+      # @return [Hash]
+      def options
+        Hash[Particle::Configurable.keys.map { |key| [key, send(key)] }]
+      end
+
+      def api_endpoint
+        ENV['PARTICLE_API_ENDPOINT'] || API_ENDPOINT
+      end
+
+      def access_token
+        ENV['PARTICLE_ACCESS_TOKEN']
+      end
+
+      # Default options for Faraday::Connection
+      # @return [Hash]
+      def connection_options
+        {
+          :headers => {
+            :user_agent => user_agent
+          }
+        }
+      end
+
+      # Default User-Agent header string from {USER_AGENT}
+      # @return [String]
+      def user_agent
+        USER_AGENT
+      end
+    end
+  end
+end

data/lib/particle/device.rb

@@ -0,0 +1,129 @@
+module Particle
+
+  # Domain model for one Particle device
+  class Device
+    ID_REGEX = /\h{24}/
+
+    def initialize(client, attributes)
+      @client = client
+      @attributes =
+      if attributes.is_a? String
+        if attributes =~ ID_REGEX
+          { id: attributes }
+        else
+          { name: attributes }
+        end
+      else
+        attributes
+      end
+    end
+
+    def id
+      get_attributes unless @attributes[:id]
+      @attributes[:id]
+    end
+
+    def name
+      get_attributes unless @attributes[:name]
+      @attributes[:name]
+    end
+
+    def id_or_name
+      @attributes[:id] || @attributes[:name]
+    end
+
+    %w(connected functions variables product_id last_heard).each do |key|
+      define_method key do
+        attributes[key.to_sym]
+      end
+    end
+    alias_method :connected?, :connected
+
+    def attributes
+      get_attributes unless @loaded
+      @attributes
+    end
+
+    def get_attributes
+      @loaded = true
+      @attributes = @client.device_attributes(self)
+    end
+
+    # Add a Particle device to your account
+    #
+    # @example Add a Photon by its id
+    #   Particle.device('f8bbe1e6e69e05c9c405ba1ca504d438061f1b0d').claim
+    def claim
+      new_device = @client.claim_device(self)
+      self
+    end
+
+    # Remove a Particle device from your account
+    #
+    # @example Add a Photon by its id
+    #   Particle.device('f8bbe1e6e69e05c9c405ba1ca504d438061f1b0d').claim
+    def remove
+      @client.remove_device(self)
+    end
+
+    # Rename a Particle device on your account
+    #
+    # @param name [String] New name for the device
+    # @example Change the name of a Photon
+    #   Particle.device('blue').rename('red')
+    def rename(name)
+      @client.rename_device(self, name)
+    end
+
+    # Call a function in the firmware of a Particle device
+    #
+    # @param name [String] Function to run on firmware
+    # @param argument [String] Argument string to pass to the firmware function
+    # @example Call the thinker digitalWrite function
+    #   Particle.device('white_whale').function('digitalWrite', '0')
+    def function(name, argument = "")
+      @client.call_function(self, name, argument)
+    end
+
+    # Get the value of a variable in the firmware of a Particle device
+    #
+    # @param target [String, Device] A device id, name or {Device} object
+    # @param name [String] Variable on firmware
+    # @return [String, Number] Value from the firmware variable
+    # @example Get the battery voltage
+    #   Particle.device('mycar').variable('battery') == 12.5
+    def variable(name)
+      @client.get_variable(self, name)
+    end
+
+    # Signal the device to start blinking the RGB LED in a rainbow
+    # pattern. Useful to identify a particular device.
+    #
+    # @param enabled [String] Whether to enable or disable the rainbow signal
+    # @return [boolean] true when signaling, false when stopped
+    def signal(enabled = true)
+      @client.signal_device(self, enabled)
+    end
+
+    def self.list_path
+      "v1/devices"
+    end
+
+    def self.claim_path
+      "v1/devices"
+    end
+
+    def path
+      "/v1/devices/#{id_or_name}"
+    end
+
+    def function_path(name)
+      path + "/#{name}"
+    end
+
+    def variable_path(name)
+      path + "/#{name}"
+    end
+  end
+end
+