Class: Smartcar::Vehicle

Inherits:
Base
  • Object
show all
Defined in:
lib/smartcar/vehicle.rb

Overview

Vehicle class to connect to vehicle basic info,disconnect, lock unlock and get all vehicles API For ease of use, this also has methods define to be able to call other resources on a vehicle object For Ex. Vehicle object will be treate as an entity and doing vehicle_object. Battery should return Battery object.

Constant Summary

Constants inherited from Base

Base::BASIC

Instance Attribute Summary collapse

Attributes inherited from Base

#auth_type, #error, #url

Instance Method Summary collapse

Methods included from Utils

#build_aliases, #build_error, #build_meta, #build_response, #build_v3_response, #convert_path_to_attribute, #convert_to_ostruct_recursively, #deep_transform_keys_to_snake_case, #determine_mode, #get_config, #handle_error, #json_to_ostruct, #parse_date_safely, #process_batch_response, #stringify_params, #to_snake_case

Constructor Details

#initialize(token:, id:, options: {}) ⇒ Vehicle

Returns a new instance of Vehicle.

Raises:



111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/smartcar/vehicle.rb', line 111

def initialize(token:, id:, options: {})
  super
  @token = token
  @id = id
  @unit_system = options[:unit_system] || METRIC
  @version = options[:version] || Smartcar.get_api_version
  @service = options[:service]
  @query_params = { flags: stringify_params(options[:flags]) }

  raise InvalidParameterValue.new, "Invalid Units provided : #{@unit_system}" unless UNITS.include?(@unit_system)
  raise InvalidParameterValue.new, 'Vehicle ID (id) is a required field' if id.nil?
  raise InvalidParameterValue.new, 'Access Token(token) is a required field' if token.nil?
end

Instance Attribute Details

#flags ⇒ Hash

Object of flags where key is the name of the flag and value is string or boolean value.

Returns:

  • the current value of flags



16
17
18
 
# File 'lib/smartcar/vehicle.rb', line 16

def flags
  @flags
end

#id ⇒ String

Smartcar vehicle ID.

Returns:

  • the current value of id



16
17
18
 
# File 'lib/smartcar/vehicle.rb', line 16

def id
  @id
end

#options ⇒ Hash

Returns the current value of options.

Returns:

  • the current value of options



16
17
18
 
# File 'lib/smartcar/vehicle.rb', line 16

def options
  @options
end

#service ⇒ Faraday::Connection

An optional connection object to be used for requests.

Returns:

  • the current value of service



16
17
18
 
# File 'lib/smartcar/vehicle.rb', line 16

def service
  @service
end

#token ⇒ String

Access token used to connect to Smartcar API.

Returns:

  • the current value of token



16
17
18
 
# File 'lib/smartcar/vehicle.rb', line 16

def token
  @token
end

#unit_system ⇒ String

Unit system to represent the data in, defaults to Imperial

Returns:

  • the current value of unit_system



16
17
18
 
# File 'lib/smartcar/vehicle.rb', line 16

def unit_system
  @unit_system
end

#version ⇒ String

API version to be used.

Returns:

  • the current value of version



16
17
18
 
# File 'lib/smartcar/vehicle.rb', line 16

def version
  @version
end

Instance Method Details

#attributes ⇒ OpenStruct

Returns make model year and id of the vehicle

API Documentation - https://smartcar.com/api#get-vehicle-attributes

Returns:




# File 'lib/smartcar/vehicle.rb', line 125

#batch(paths) ⇒ OpenStruct

Method to get batch requests. API - https://smartcar.com/docs/api#post-batch-request

Parameters:

  • Array of paths as strings. Ex ['/battery', '/odometer']

Returns:

  • Object with one attribute per requested path that returns an OpenStruct object of the requested attribute or taises if it is an error.



368
369
370
371
372
 
# File 'lib/smartcar/vehicle.rb', line 368

def batch(paths)
  request_body = { requests: paths.map { |path| { path: path } } }
  response, headers = post("/vehicles/#{id}/batch", @query_params, request_body)
  process_batch_response(response, headers)
end

#battery ⇒ OpenStruct

Returns the state of charge (SOC) and remaining range of an electric or plug-in hybrid vehicle's battery.

API Documentation https://smartcar.com/docs/api#get-ev-battery

Returns:




# File 'lib/smartcar/vehicle.rb', line 133

#battery_capacity ⇒ OpenStruct

Returns the capacity of an electric or plug-in hybrid vehicle's battery.

API Documentation https://smartcar.com/docs/api#get-ev-battery-capacity

Returns:




# File 'lib/smartcar/vehicle.rb', line 141

#charge ⇒ OpenStruct

Returns the current charge status of the vehicle.

API Documentation https://smartcar.com/docs/api#get-ev-battery

Returns:




# File 'lib/smartcar/vehicle.rb', line 157

#default_date_range ⇒ Object

Utility method to provide default dates



302
303
304
305
306
 
# File 'lib/smartcar/vehicle.rb', line 302

def default_date_range
  end_date = DateTime.now.new_offset(0).to_date
  start_date = end_date - 365
  [start_date.to_s, end_date.to_s]
end

#diagnostic_system_status ⇒ OpenStruct

Returns the status of the vehicle's diagnostic systems.

API Documentation: https://smartcar.com/docs/api#get-diagnostic-system-status

Returns:

  • An object representing the diagnostic system status and metadata.




# File 'lib/smartcar/vehicle.rb', line 165

#diagnostic_trouble_codes ⇒ OpenStruct

Retrieves diagnostic trouble codes (DTCs) from the vehicle.

API Documentation: https://smartcar.com/docs/api#get-diagnostic-trouble-codes

Returns:

  • An object containing the DTCs and metadata.




# File 'lib/smartcar/vehicle.rb', line 172

#engine_oil ⇒ OpenStruct

Returns the remaining life span of a vehicle's engine oil

API Documentation https://smartcar.com/docs/api#get-engine-oil-life

Returns:




# File 'lib/smartcar/vehicle.rb', line 179

#fuel ⇒ OpenStruct

Returns the status of the fuel remaining in the vehicle's gas tank.

API Documentation https://smartcar.com/docs/api#get-fuel-tank

Returns:




# File 'lib/smartcar/vehicle.rb', line 187

#get_signal(signal_code) ⇒ OpenStruct

Retrieve a specific signal by signal code from the vehicle. Uses the Vehicle API (v3) endpoint.

API Documentation - https://smartcar.com/docs/api-reference/get-signal

Parameters:

  • The code of the signal to retrieve.

Returns:

  • An object with a "body" attribute containing the signal data and a "headers" attribute containing the response headers.

Raises:



383
384
385
386
387
388
 
# File 'lib/smartcar/vehicle.rb', line 383

def get_signal(signal_code)
  raise InvalidParameterValue.new, 'signal_code is a required field' if signal_code.nil? || signal_code.empty?

  path = "/vehicles/#{id}/signals/#{signal_code}"
  request_v3(path)
end

#get_signals ⇒ OpenStruct

Retrieve all available signals from the vehicle. Uses the Vehicle API (v3) endpoint.

API Documentation - https://smartcar.com/docs/api-reference/get-signals

Returns:

  • An object with a "body" attribute containing all signals data and a "headers" attribute containing the response headers.



397
398
399
400
 
# File 'lib/smartcar/vehicle.rb', line 397

def get_signals
  path = "/vehicles/#{id}/signals"
  request_v3(path)
end

#location ⇒ OpenStruct

Returns the last known location of the vehicle in geographic coordinates.

API Documentation https://smartcar.com/docs/api#get-location

Returns:




# File 'lib/smartcar/vehicle.rb', line 195

#lock_status ⇒ OpenStruct

Returns the lock status for a vehicle and the open status of its doors, windows, storage units, sunroof and charging port where available. The open status array(s) will be empty if a vehicle has partial support. The request will error if lock status can not be retrieved from the vehicle or the brand is not supported.

API Documentation https://smartcar.com/docs/api#get-security

Returns:




# File 'lib/smartcar/vehicle.rb', line 227

#nominal_capacity ⇒ OpenStruct

Returns a list of nominal rated battery capacities for a vehicle.

API Documentation https://smartcar.com/docs/api-reference/get-nominal-capacity

Returns:




# File 'lib/smartcar/vehicle.rb', line 149

#odometer ⇒ OpenStruct

Returns the vehicle's last known odometer reading.

API Documentation https://smartcar.com/docs/api#get-odometer

Returns:




# File 'lib/smartcar/vehicle.rb', line 203

#permissions(paging = {}) ⇒ OpenStruct

Method to fetch the list of permissions that this application has been granted for this vehicle. API - https://smartcar.com/docs/api#get-application-permissions

Parameters:

  • (defaults to: {})

    Optional filter parameters (check documentation)

Returns:



269
270
271
272
 
# File 'lib/smartcar/vehicle.rb', line 269

def permissions(paging = {})
  response, headers = get(METHODS.dig(:permissions, :path).call(id), @query_params.merge(paging))
  build_response(response, headers)
end

#request(method, path, body = {}, headers = {}) ⇒ OpenStruct

General purpose method to make requests to the Smartcar API - can be used to make requests to brand specific endpoints.

Parameters:

  • The HTTP request method to use.

  • The path to make the request to.

  • (defaults to: {})

    The request body.

  • (defaults to: {})

    The headers to inlcude in the request.

Returns:

  • An object with a "body" attribute that contains the response body and a "meta" attribute with the relevant items from response headers.



412
413
414
415
416
417
 
# File 'lib/smartcar/vehicle.rb', line 412

def request(method, path, body = {}, headers = {})
  path = "/vehicles/#{id}/#{path}"
  raw_response, headers = send(method.downcase, path, @query_params, body, headers)
  meta = build_meta(headers)
  json_to_ostruct({ body: raw_response, meta: meta })
end

#send_destination!(latitude, longitude) ⇒ OpenStruct

Returns Meta attribute with the relevant items from response headers.

Returns:

  • Meta attribute with the relevant items from response headers



354
355
356
357
358
359
360
 
# File 'lib/smartcar/vehicle.rb', line 354

def send_destination!(latitude, longitude)
  method_config = METHODS[:send_destination!]

  response, headers = post(method_config[:path].call(id), @query_params,
                           method_config[:body].call(latitude, longitude))
  build_response(response, headers)
end

#service_history(start_date = nil, end_date = nil) ⇒ OpenStruct

Retrieves a list of service records for the vehicle, optionally filtered by a specified date range. If no dates are specified, the method defaults to returning records from the last year.

This method calls the Smartcar API to fetch the vehicle's service history and processes the response to return structured data.

Example usage: vehicle.service_history('2021-01-01', '2021-12-31')

Note: This method assumes that the necessary error handling is embedded within the get method or handled externally when exceptions arise due to network issues, API limitations, or data encoding problems.

Parameters:

  • (defaults to: nil)

    the start date of the period from which records are retrieved (inclusive). Expected in 'YYYY-MM-DD' format. If nil, defaults to one year ago from today.

  • (defaults to: nil)

    the end date of the period until which records are retrieved (inclusive). Expected in 'YYYY-MM-DD' format. If nil, defaults to today's date.

Returns:

  • An object representing the parsed JSON response from the API, with service history data and metadata extracted from the response headers.



293
294
295
296
297
298
299
 
# File 'lib/smartcar/vehicle.rb', line 293

def service_history(start_date = nil, end_date = nil)
  start_date, end_date = default_date_range if start_date.nil? || end_date.nil?

  path = METHODS[:service_history][:path].call(id, start_date, end_date)
  body, headers = get(path, @query_params)
  build_response(body, headers)
end

#set_charge_limit!(limit) ⇒ OpenStruct

Set the charge limit for a given vehicle

Parameters:

  • A value between 0 and 1 denoting the charge limit to be set.

Returns:

  • Meta attribute with the relevant items from response headers.



340
341
342
343
344
345
346
 
# File 'lib/smartcar/vehicle.rb', line 340

def set_charge_limit!(limit)
  path = METHODS.dig(:set_charge_limit!, :path).call(id)
  body = METHODS.dig(:set_charge_limit!, :body).call(limit)

  response, headers = post(path, {}, body)
  build_response(response, headers)
end

#subscribe!(webhook_id) ⇒ OpenStruct

Subscribe the vehicle to given webhook Id.

Parameters:

  • Webhook id to subscribe to

Returns:

  • An object representing the JSON response and a meta attribute with the relevant items from response headers.



314
315
316
317
 
# File 'lib/smartcar/vehicle.rb', line 314

def subscribe!(webhook_id)
  response, headers = post(METHODS.dig(:subscribe!, :path).call(id, webhook_id), @query_params)
  build_aliases(build_response(response, headers), METHODS.dig(:subscribe!, :aliases))
end

#tire_pressure ⇒ OpenStruct

Returns the air pressure of each of the vehicle's tires.

API Documentation https://smartcar.com/docs/api#get-tire-pressure

Returns:




# File 'lib/smartcar/vehicle.rb', line 211

#unsubscribe!(amt, webhook_id) ⇒ OpenStruct

Unubscribe the vehicle from given webhook Id.

Parameters:

  • Application management token

  • Webhook id to subscribe to

Returns:

  • Meta attribute with the relevant items from response headers.



325
326
327
328
329
330
331
332
333
 
# File 'lib/smartcar/vehicle.rb', line 325

def unsubscribe!(amt, webhook_id)
  # swapping off the token with amt for unsubscribe.
  access_token = token
  self.token = amt
  response, headers = delete(METHODS.dig(:unsubscribe!, :path).call(id, webhook_id),
                             @query_params)
  self.token = access_token
  build_response(response, headers)
end

#vin ⇒ OpenStruct

Returns the vehicle's manufacturer identifier (VIN).

API Documentation https://smartcar.com/docs/api#get-vin

Returns:




# File 'lib/smartcar/vehicle.rb', line 219