Skip to content

agentfisk/handy-api

BranchesTags

Repository files navigation

handy_api

HandyAPI - the Ruby gem for the Handy API v2.0.0

API to interact with the 'TheHandy'.

IMPORTANT: This API is compatible with devices running firmware version 3 (v3) only. See note below on how to deal with firmware version 2 (v2) devices with this API.

Join the community

Send us a mail or add us on discord for a more technical chat - Handy#8756
Follow us on Reddit for updates and announcements: https://www.reddit.com/r/theHandy/

Server selection

When using the API make sure you connect to the server environment that the device you are trying to interact with is connected to.
For most users this will be the production environment API server: https://www.handyfeeling.com/api/handy/v2
If you have been given special access to firmware that connects to the staging environment, you should use the staging environment API server: https://staging.handyfeeling.com/api/handy/v2

Handling firmware v2 devices

Users with firmware v2 devices are required to update their device to firmware v3 before the device can be fully used with this API.
To ease this process, two of the endpoints in this API can be used with firmware v2 devices:
  • /connected - Check online status of a device.
  • /info - Get general information about the device.
All other endpoints will always return a 'Machine not connected' error if you try to use them with a firmware v2 device.

For v2 devices it's important to handle the fwStatus returned from the /info endpoint properly.
v2 devices will always have fwStatus = UPDATE_REQUIRED(2). See /info documentation for more details.

When using the API with a device, you should always start by verifying that the device have a firmware that is compatible with the API you are using in your service.
An example flow could look like this:
  1. Check if device is conncted with /connected
  2. Check device firmware status with /info
  3. If a firmware update is required, forward the user to <a href="https://www.handfyfeeling.com\">https://www.handfyfeeling.com so they can easily update the device firmware.
  4. Continue your service when the firmware status returned in /info is UP_TO_DATE(0).

Mode specific operations

Operations in BASE, SLIDE, TIMESYNC and HSTP are mode independent and available at any time.
Other operations are only available in a specific mode (eg. HAMP, HDSP, HSSP).
To access these operations, the device have to first be put in the specific mode (see /mode).
If you execute an operation not available in the current mode of the device, you will receive a 'No such method' error response.

This SDK is automatically generated by the OpenAPI Generator project:

  • API version: 2.0.0-beta-3
  • Package version: 1.0.0
  • Build package: org.openapitools.codegen.languages.RubyClientCodegen

Installation

Build a gem

To build the Ruby code into a gem:

gem build handy_api.gemspec

Then either install the gem locally:

gem install ./handy_api-1.0.0.gem

(for development, run gem install --dev ./handy_api-1.0.0.gem to install the development dependencies)

or publish the gem to a gem hosting service, e.g. RubyGems.

Finally add this to the Gemfile:

gem 'handy_api', '~> 1.0.0'

Install from Git

If the Ruby gem is hosted at a git repository: https://github.com/GIT_USER_ID/GIT_REPO_ID, then add the following in the Gemfile:

gem 'handy_api', :git => 'https://github.com/GIT_USER_ID/GIT_REPO_ID.git'

Include the Ruby code directly

Include the Ruby code directly using -I as follows:

ruby -Ilib script.rb

Getting Started

Please follow the installation procedure and then run the following code:

# Load the gem
require 'handy_api'

api_instance = HandyAPI::BASEApi.new
x_connection_key = 'x_connection_key_example' # String | Device connection key.

begin
  #Get extended device information.
  result = api_instance.get_info(x_connection_key)
  p result
rescue HandyAPI::ApiError => e
  puts "Exception when calling BASEApi->get_info: #{e}"
end

Documentation for API Endpoints

All URIs are relative to https://www.handyfeeling.com/api/handy/v2

Class Method HTTP request Description
HandyAPI::BASEApi get_info GET /info Get extended device information.
HandyAPI::BASEApi get_mode GET /mode Get the current mode of the device.
HandyAPI::BASEApi get_settings GET /settings Extended device settings.
HandyAPI::BASEApi get_status GET /status Get the device status.
HandyAPI::BASEApi is_connected GET /connected Check device connectivity.
HandyAPI::BASEApi set_mode PUT /mode Set the current mode of the device.
HandyAPI::HAMPApi get_hamp_state GET /hamp/state Get the HAMP state of the device.
HandyAPI::HAMPApi get_hamp_velocity_percent GET /hamp/velocity Get the HAMP velocity setting of the device in percent.
HandyAPI::HAMPApi hamp_stop PUT /hamp/stop Stop alternating motion.
HandyAPI::HAMPApi set_hamp_velocity_percent PUT /hamp/velocity Set the HAMP velocity setting of the device in percent.
HandyAPI::HAMPApi start PUT /hamp/start Start alternating motion.
HandyAPI::HDSPApi next_position_abs_in_time PUT /hdsp/xat Sets the next absolute position (xa) of the device, and the time (t) the device should use to reach the position.
HandyAPI::HDSPApi next_position_percent_in_time PUT /hdsp/xpt Sets the next percent position (xp) of the device, and the time (t) the device should use to reach the position.
HandyAPI::HDSPApi next_position_percent_velocity_absolute PUT /hdsp/xpva Sets the next percent position (xp) of the device, and the absolute velocity (va) the device should use to reach the position.
HandyAPI::HDSPApi next_position_percent_velocity_percent PUT /hdsp/xpvp Sets the next percent position (xp) of the device, and the percent velocity (vp) the device should use to reach the position.
HandyAPI::HDSPApi next_postion_abs_velocity_abs PUT /hdsp/xava Sets the next absolute position (xa) of the device, and the absolute velocity (va) the device should use to reach the position.
HandyAPI::HSSPApi get_hssp_state GET /hssp/state Get the HSSP state of the device.
HandyAPI::HSSPApi get_loop_setting GET /hssp/loop Get the HSSP loop setting of the device. Only available in firmware >= 3.2.x
HandyAPI::HSSPApi hssp_stop PUT /hssp/stop Stop script playing.
HandyAPI::HSSPApi play PUT /hssp/play Start script playing.
HandyAPI::HSSPApi set_loop_setting PUT /hssp/loop Set the HSSP loop setting of the device. Only available in firmware >= 3.2.x
HandyAPI::HSSPApi setup PUT /hssp/setup Setup script synchronization.
HandyAPI::HSTPApi get_device_time GET /hstp/time Get the current time of the device.
HandyAPI::HSTPApi get_offset GET /hstp/offset Get the HSTP offset of the device.
HandyAPI::HSTPApi get_round_trip_delay GET /hstp/rtd Get the round-trip-delay-time (rtd) between the device and the server.
HandyAPI::HSTPApi set_offset PUT /hstp/offset Set the HSTP offset of the device.
HandyAPI::HSTPApi sync GET /hstp/sync Syncronize the connected device with the server clock.
HandyAPI::MAINTENANCEApi get_update_status GET /maintenance/update/status Get the device update status.
HandyAPI::MAINTENANCEApi restart PUT /maintenance/restart Restart the device.
HandyAPI::MAINTENANCEApi update_perform_fw PUT /maintenance/update/perform Perform firmware update.
HandyAPI::OTAApi latest GET /ota/latest Get the latest available firmware available for the provided model and branch.
HandyAPI::SLIDEApi get_position_abs GET /slide/position/absolute Get the current slide position
HandyAPI::SLIDEApi get_slide GET /slide Get the slide settings.
HandyAPI::SLIDEApi set_slide PUT /slide Set slide settings.
HandyAPI::TIMESYNCApi get_server_time GET /servertime Get current server time.

Documentation for Models

Documentation for Authorization

Authentication schemes defined for the API:

BearerAuth

  • Type: Bearer authentication (unique)

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •  

Languages