ksr10 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '04493410ad7bdb38f5601a106ba1d48b1524354e5c13aa9726fac3be8d9d1a88'
+  data.tar.gz: a3c7b22e7042b92b8939d84aa681f7a6ac18b7a1798406648a7174993f488946
+SHA512:
+  metadata.gz: 811dd98d2afd2e73b679cf0449fab4da55c98bd642bc0a8618cae38a835b45dc9f1a6c6989cb29f3802a2a48a5d876c807d5233f8cfd37425591810df173f549
+  data.tar.gz: 131e8a334f4d96f52ddd627195cbd4ff503da6ef140d1b67eaba35df0a10c31fc93d59220a873f554eb7d61988ba7e06a9ee1fc7b28b8759872e5b4ed054b534

data/LICENSE

@@ -0,0 +1,26 @@
+Copyright (c) 2020 Martin Carpenter <martin.carpenter@gmail.com>. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,71 @@
+# ksr10
+
+https://github.com/mcarpenter/ksr10
+
+This Ruby Gem provides a simple programming interface to the Velleman KSR10
+robotic arm with USB control board. It's simple enough that it can be used from
+the REPL. The `krs10` script uses `pry` so that you can just call the instance
+methods from the prompt. See the examples below.
+
+For product details see:
+
+ * https://www.velleman.eu/products/view/?id=375310
+ * https://www.velleman.eu/products/view/?id=436330
+
+
+## Examples
+
+### API
+
+```ruby
+require 'ksr10'
+
+arm = Ksr10.new
+arm.led(:on)
+arm.elbow(:down, 500)
+arm.gripper(:close, 1000)
+arm.stop
+```
+
+### REPL
+
+```ruby
+$ ksr10
+[1] pry(#<Ksr10>)> led(:on)
+=> #<Ksr10:0x000055da9db684b0
+ @device=#<LIBUSB::Device 3/2 1267:0001 ? ? ? (Vendor specific (00,00))>,
+ @state=1,
+ @usb=#<LIBUSB::Context:0x000055da9db68488 @ctx=#<FFI::Pointer address=0x000055da9da582d0>, @hotplug_callbacks={}, @on_pollfd_added=nil, @on_pollfd_removed=nil>>
+[2] pry(#<Ksr10>)> shoulder(:up, 400)
+=> #<Ksr10:0x000055da9db684b0
+ @device=#<LIBUSB::Device 3/2 1267:0001 ? ? ? (Vendor specific (00,00))>,
+ @state=1,
+ @usb=#<LIBUSB::Context:0x000055da9db68488 @ctx=#<FFI::Pointer address=0x000055da9da582d0>, @hotplug_callbacks={}, @on_pollfd_added=nil, @on_pollfd_removed=nil>>
+[3] pry(#<Ksr10>)>
+```
+
+## Install
+
+```sh
+sudo apt install libusb-1.0-0
+sudo gem install ksr10
+```
+
+Add the following lines to `/etc/udev/rules.d/95-ksr10.rules` so that
+unprivileged users can connect to the KSR10:
+
+```
+ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="1267", ATTR{idProduct}=="0000", MODE="0666"
+ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="1267", ATTR{idProduct}=="0001", MODE="0666"
+```
+
+If you find that the action is reversed (eg "up" is actually "down") then you
+can simply reverse the appropriate Dupont connector on the battery box to
+change the polarity.
+
+
+## Alternatives
+
+ * https://github.com/lvajxi03/roboarm (Python)
+ * https://github.com/TristanvanLeeuwen/KSR10 (Python)
+ * https://github.com/paly2/ksr10-linux-driver (C++)

data/Rakefile

@@ -0,0 +1,22 @@
+
+require 'rake'
+require 'rake/clean'
+require 'rdoc/task'
+require 'rubygems/package_task'
+
+SPEC = eval(File.read('ksr10.gemspec'))
+
+desc 'Default task (gem)'
+task :default => [:gem]
+
+Gem::PackageTask.new(SPEC) do |pkg|
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = SPEC.name
+  rdoc.options << '--line-numbers'
+  rdoc.options << '--charset' << 'utf-8'
+  rdoc.options << '--main' << 'README.md'
+  rdoc.options << '--all'
+end

data/bin/ksr10

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'pry'
+require 'ksr10'
+
+begin
+  arm = Ksr10.new
+rescue Ksr10::Error => err
+  execname = File.basename(__FILE__)
+  STDERR.puts "#{execname}: #{err.class::MESSAGE}"
+  exit 2
+end
+arm.pry
+arm.stop

data/lib/ksr10.rb

@@ -0,0 +1,125 @@
+
+require 'libusb'
+
+# An object representing a Velleman KSR10 USB robotic arm.
+class Ksr10
+
+  # Gem version.
+  VERSION = '1.0.0'
+
+  # USB product IDs of 0x0 and 0x1 have been seen in the wild so we look for
+  # either and take the first found when initializing a Ksr10 object.
+  PRODUCT_IDS = [0x0, 0x1]
+
+  # USB vendor ID.
+  VENDOR_ID = 0x1267
+
+  # Exceptions that might be thrown by the Ksr10 constructor.
+  class Error < StandardError
+
+    class DeviceNotFound < Error
+      MESSAGE = 'USB device not found'
+    end # DeviceNotFound
+
+    class PermissionDenied < Error
+      MESSAGE = 'Permission denied to open interface to USB device'
+    end # PermissionDenied
+
+  end # Error
+
+  def initialize
+    @usb = LIBUSB::Context.new
+    PRODUCT_IDS.each do |product_id|
+      @device = @usb.devices(idVendor: VENDOR_ID, idProduct: product_id).first
+      break if @device
+    end
+    raise Error::DeviceNotFound unless @device
+    # Check we can access the device. Libusb requires that #open_interface take
+    # a block, so we cannot keep and reuse the returned handle.
+    begin
+      @device.open_interface(0) { |_| }
+    rescue LIBUSB::ERROR_ACCESS
+      raise Error::PermissionDenied
+    end
+    stop # initializes @state
+  end
+
+  # Rotate the base.
+  def base(left_right_stop, duration_ms=0)
+    set_state(left_right_stop, duration_ms, {left: {on: 9, off: 8}, right: {on: 8, off: 9}})
+  end
+
+  # Action the shoulder motor.
+  def shoulder(up_down_stop, duration_ms=0)
+    set_state(up_down_stop, duration_ms, {up: {on: 22, off: 23}, down: {on: 23, off: 22}})
+  end
+
+  # Action the elbow motor.
+  def elbow(up_down_stop, duration_ms=0)
+    set_state(up_down_stop, duration_ms, {up: {on: 20, off: 21}, down: {on: 21, off: 20}})
+  end
+
+  # Action the wrist motor.
+  def wrist(up_down_stop, duration_ms=0)
+    set_state(up_down_stop, duration_ms, {up: {on: 18, off: 19}, down: {on: 19, off: 18}})
+  end
+
+  # Action the gripper.
+  def gripper(open_close_stop, duration_ms=0)
+    set_state(open_close_stop, duration_ms, {open: {on: 17, off: 16}, close: {on: 16, off: 17}})
+  end
+
+  # Turn on or off the LED.
+  def led(on_off, duration_ms=0)
+    set_state(on_off, duration_ms, {on: {on: 0}, off: {off: 0}})
+  end
+
+  # Stop all actions and turn off the LED.
+  def stop(duration_ms=0)
+    @state = 0
+    write_state!(duration_ms)
+    self
+  end
+
+  private
+
+  # The Hash spec defines the bits to flip in the USB control write for each
+  # permitted state. Bits are numbered from LSB and are 0-indexed.  Returns
+  # "self" so that calls may be chained in the style of Fowler's "fluent
+  # interface".
+  def set_state(state, duration_ms, spec)
+    if state == :stop
+      spec.each do |_, bit_flips|
+        @state &= ~(1<<bit_flips[:off]) if bit_flips.has_key?(:off)
+      end
+    else
+      bit_flips = spec[state]
+      raise ArgumentError, "Invalid argument #{state.inspect} for #{caller_locations[0].label}" unless bit_flips
+      # Flip off bits first to avoid an invalid state "go up AND down
+      # simultaneously".
+      @state &= ~(1<<bit_flips[:off]) if bit_flips.has_key?(:off)
+      @state |= 1<<bit_flips[:on] if bit_flips.has_key?(:on)
+    end
+    write_state!(duration_ms)
+    # If we received a duration then flip off the bits we just flipped on.
+    if !duration_ms.zero? && bit_flips && bit_flips.has_key?(:on)
+      @state &= ~(1<<bit_flips[:on])
+      write_state! # return immediately, no duration_ms
+    end
+    self
+  end
+
+  # Write the state stored in the instance variable to the device.
+  def write_state!(duration_ms=0)
+    data = [@state.to_s(16).rjust(6, '0')].pack('H*')
+    @device.open_interface(0) do |handle|
+      handle.control_transfer(bmRequestType: 0x40,
+                              bRequest: 0x06,
+                              wValue: 0x0100,
+                              wIndex: 0x00,
+                              dataOut: data)
+    end
+    sleep(duration_ms / 1000.0)
+  end
+
+end # Ksr10

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: ksr10
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Martin Carpenter
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-01-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: libusb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.4
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.12.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.12.2
+description: Interface and control script for the Velleman KSR-10 robotic arm.
+email: martin.carpenter@gmail.com
+executables:
+- ksr10
+extensions: []
+extra_rdoc_files:
+- LICENSE
+- Rakefile
+- README.md
+files:
+- LICENSE
+- README.md
+- Rakefile
+- bin/ksr10
+- lib/ksr10.rb
+homepage: http://github.com/mcarpenter/ksr10
+licenses:
+- BSD-3-Clause
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.1
+signing_key: 
+specification_version: 4
+summary: KSR-10 robotic arm API and CLI
+test_files: []