Module: Particle::Client::Devices

Included in:
Particle::Client
Defined in:
lib/particle/client/devices.rb

Overview

Client methods for the Particle device API

See Also:

Instance Method Summary collapse

Instance Method Details

#call_function(target, name, argument = "") ⇒ Integer

Call a function in the firmware of a Particle device

Parameters:

  • target (String, Device) —

    A device id, name or Device object

  • name (String) —

    Function to run on firmware

  • argument (String) (defaults to: "") —

    Argument string to pass to the firmware function

Returns:

  • (Integer) —

    Return value from the firmware function



85
86
87
88
 
# File 'lib/particle/client/devices.rb', line 85

def call_function(target, name, argument = "")
  result = post(device(target).function_path(name), arg: argument)
  result[:return_value]
end

#change_device_product(target, product_id, should_update = false) ⇒ boolean

Change the product_id on the device. Use this carefully, it will impact what updates you receive, and can only be used for products that have given their permission

Parameters:

  • target (String, Device) —

    A device id, name or Device object

  • product_id (String) —

    New product id

  • should_update (String) (defaults to: false) —

    if the device should be immediately updated after changing the product_id

Returns:

  • (boolean) —

    true on success



120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/particle/client/devices.rb', line 120

def change_device_product(target, product_id, should_update = false)
  params = {
    product_id: product_id,
    update_after_claim: should_update
  }
  result = put(device(target).path, params)
  if result[:error] == "Nothing to do?"
    result[:ok] = false
  end
  result[:ok]
end

#claim_device(target) ⇒ Device

Add a Particle device to your account

Parameters:

  • target (String, Device) —

    A device id or Device object. You can’t claim a device by name

Returns:

  • (Device) —

    A device object to interact with



45
46
47
48
 
# File 'lib/particle/client/devices.rb', line 45

def claim_device(target)
  result = post(Device.claim_path, id: device(target).id_or_name)
  device(result[:id])
end

#device(target) ⇒ Device

Create a domain model for a Particle device

Parameters:

  • target (String, Hash, Device) —

    A device id, name, hash of attributes or Device object

Returns:

  • (Device) —

    A device object to interact with



15
16
17
18
19
20
21
 
# File 'lib/particle/client/devices.rb', line 15

def device(target)
  if target.is_a? Device
    target
  else
    Device.new(self, target)
  end
end

#device_attributes(target) ⇒ Hash

Get information about a Particle device

Parameters:

  • target (String, Device) —

    A device id, name or Device object

Returns:

  • (Hash) —

    The device attributes



36
37
38
 
# File 'lib/particle/client/devices.rb', line 36

def device_attributes(target)
  get(device(target).path)
end

#devices ⇒ Array<Device>

List all Particle devices on the account

Returns:

  • (Array<Device>) —

    List of Particle devices to interact with



26
27
28
29
30
 
# File 'lib/particle/client/devices.rb', line 26

def devices
  get(Device.list_path).map do |attributes|
    device(attributes)
  end
end

#get_variable(target, name) ⇒ String, Number

Get the value of a variable in the firmware of a Particle device

Parameters:

  • target (String, Device) —

    A device id, name or Device object

  • name (String) —

    Variable on firmware

Returns:

  • (String, Number) —

    Value from the firmware variable



95
96
97
98
 
# File 'lib/particle/client/devices.rb', line 95

def get_variable(target, name)
  result = get(device(target).variable_path(name))
  result[:result]
end

#provision_device(params) ⇒ Device

Create a new Particle device

Parameters:

  • product (String) —

    A product id

Returns:

  • (Device) —

    A device object to interact with



54
55
56
57
58
 
# File 'lib/particle/client/devices.rb', line 54

def provision_device(params)
  product_id = params[:product_id] or raise ArgumentError.new("product_id parameter is required")
  result = post(Device.provision_path, product_id: product_id)
  device(result[:device_id])
end

#remove_device(target) ⇒ boolean

Remove a Particle device from your account

Parameters:

  • target (String, Device) —

    A device id, name or Device object

Returns:

  • (boolean) —

    true for success



64
65
66
67
 
# File 'lib/particle/client/devices.rb', line 64

def remove_device(target)
  result = delete(device(target).path)
  result[:ok]
end

#rename_device(target, name) ⇒ boolean

Rename a Particle device in your account

Parameters:

  • target (String, Device) —

    A device id, name or Device object

  • name (String) —

    New name for the device

Returns:

  • (boolean) —

    true for success



74
75
76
77
 
# File 'lib/particle/client/devices.rb', line 74

def rename_device(target, name)
  result = put(device(target).path, name: name)
  result[:name] == name
end

#signal_device(target, enabled = true) ⇒ boolean

Signal the device to start blinking the RGB LED in a rainbow pattern. Useful to identify a particular device.

Parameters:

  • target (String, Device) —

    A device id, name or Device object

  • enabled (String) (defaults to: true) —

    Whether to enable or disable the rainbow signal

Returns:

  • (boolean) —

    true when signaling, false when stopped



106
107
108
109
 
# File 'lib/particle/client/devices.rb', line 106

def signal_device(target, enabled = true)
  result = put(device(target).path, signal: enabled ? '1' : '0')
  result[:signaling]
end

#update_device_public_key(target, public_key, algorithm = 'rsa') ⇒ boolean

Update the public key for a device you own

Parameters:

  • target (String, Device) —

    A device id, name or Device object

  • public_key (String) —

    The public key in PEM format (default format generated by openssl)

  • algorithm (String) (defaults to: 'rsa') —

    The encryption algorithm for the key (default rsa)

Returns:

  • (boolean) —

    true when successful



140
141
142
143
144
145
146
 
# File 'lib/particle/client/devices.rb', line 140

def update_device_public_key(target, public_key, algorithm = 'rsa')
  result = post(device(target).update_keys_path,
                deviceID: device(target).id,
                publicKey: public_key,
                algorithm: algorithm)
  !result.empty?
end