aio 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 70668dcd4f13f77e238662175257cf8b64a621df
+  data.tar.gz: 8915cb0cf9a45718b3e72922e085b8d26ea6b842
+SHA512:
+  metadata.gz: c906dee14bc8a69610d9d73e18d135130082d5eadd7774284279e3a07cb893a9ab8794e85277f7c22c22a08167ab555302630f614f1f62c832f79b7ec6706bbf
+  data.tar.gz: 7805e2d5b780de1c61ae5f84b132a121c8bdcccd1fc6dace35167d7247219f3b67460bf87113126cfdc62236b77a79bf1ee6f43da6497397f00bf990a0228e8e

data/bin/aiosketch

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "aio"
+
+Aio.print_sketch

data/lib/aio.rb

@@ -0,0 +1,107 @@
+require "aio/constants"
+require "aio/errors"
+require "aio/board"
+require "aio/sketch"
+require "aio/helpers"
+
+# {https://github.com/jvalencia80/aio Aio} (Arduino Input/Output) is a robust 
+# library with built-in redundancy check for data integrity and command 
+# confirmation for remotely controlling {http://arduino.cc Arduino}
+# boards using Ruby code and the serial port.
+# 
+# It implements lots of functions found in the
+# {http://arduino.cc/en/Reference/HomePage Arduino Reference} and they even 
+# share the same names and parameters for an easier experience.
+#
+# * Currently, these boards are fully supported (and many others should work):
+# 
+#   * UNO, Duemilanove, Diecimila, Pro
+#   * Leonardo, Yun, Micro
+#   * Mega, Mega 2560, Mega ADK
+#   * Nano, Mini, Fio, Pro Mini
+# 
+# * Supported functions implemented in the {Aio::Board Aio::Board} class:
+# 
+#   * pinMode
+#   * digitalRead, digitalWrite
+#   * analogRead, analogWrite, analogReference
+#   * millis
+#
+# * Supported constants:
+# 
+#   * LOW, HIGH
+#   * INPUT, INPUT_PULLUP, OUTPUT
+#   * DEFAULT, INTERNAL, EXTERNAL, INTERNAL1V1, INTERNAL2V56
+# 
+# * Other supported functions (see {Aio::Helpers Aio::Helpers} module):
+# 
+#   * lowByte, highByte, bit, bitClear, bitSet, bitRead, bitWrite
+#   * min, max, abs, pow, sqrt, map, constrain
+#   * sin, cos, tan
+#   * random, randomSeed
+# 
+# = Example
+# 
+# Blinking a LED:
+# 
+#   require "aio"
+#   
+#   Aio::Board.new("/dev/ttyUSB0") do |board|
+#     sleep 0.1 until board.ready?
+#
+#     board.pinMode(13, Aio::OUTPUT)
+#     
+#     5.times do
+#       board.digitalWrite(13, Aio::HIGH)
+#       sleep 0.5
+#       board.digitalWrite(13, Aio::LOW)
+#       sleep 0.5
+#     end
+#   end
+# 
+# Check more examples at the {https://github.com/jvalencia80/aio/tree/master/examples Github}
+# page.
+# 
+# = Installation
+# 
+# 1. Install the {https://rubygems.org/gems/aio Aio} gem:
+# 
+#      $ gem install aio
+# 
+# 2. Print the sketch required by the library:
+# 
+#      $ aiosketch > sketch.ino
+#
+#    or
+#
+#      $ ruby -raio -e "Aio.print_sketch" > sketch.ino
+# 
+# 3. Compile and burn the sketch using the {http://arduino.cc/en/Main/Software Arduino IDE}.
+# 
+# = Limitations
+# 
+# - As this library uses the Arduino serial port, digital pins *0* and *1* must not be used.
+#
+# - This library code isn't executed in realtime as Arduino does, and the communication
+#   protocol is relatively slow, so trying to make code that requires exact timing is tricky.
+#
+# - Also take into account that this library does not check if *PIN* *X* is available in
+#   *BOARD* *Z*, or if the value supplied is valid or not for a specific command,
+#   so check your board's documentation first.
+#
+# - This library is *NOT* thread safe.
+#
+# = Issues
+#
+# Post any issues at the {https://github.com/jvalencia80/aio/issues Github issue tracker}.
+
+module Aio
+	# Prints the Arduino sketch to STDOUT.
+	#
+	# @return [nil]
+	
+	def self.print_sketch
+		STDOUT.puts SKETCH.gsub(/\t/,'')
+		nil
+	end
+end

data/lib/aio/board.rb

@@ -0,0 +1,220 @@
+require "serialport"
+
+module Aio
+	# This is the main class that communicates with the Arduino board.
+	#
+	# It implements several mechanisms like ACK/NAK for confirming
+	# command execution and {http://en.wikipedia.org/wiki/Longitudinal_redundancy_check redundancy checks} 
+	# to ensure data integrity.
+	
+	class Board
+		# @example Modes of initialization
+		#   # explicit
+		#   board = Aio::Board.new("/dev/ttyUSB1")
+		#   
+		#   # block mode (closes the connection at the end)
+		#   Aio::Board.new("/dev/ttyUSB0") do |board|
+		#     # code...
+		#   end
+		#
+		# @param port [String] the device/address used for communication.
+		# @yield [self] an optional block of code to execute.
+		# @raise [DeviceError] when the serial port is unavailable.
+		
+		def initialize(port)
+			@serial = SerialPort.new(port, BAUDRATE, 8, 1, SerialPort::NONE)
+		rescue Errno::ENOENT
+			raise Aio::DeviceError, "Unavailable serial port at address => '#{port}'"
+		else
+			@serial.flow_control = SerialPort::NONE
+			@serial.read_timeout = TIMEOUT
+			@serial.sync = true
+			
+			if block_given?
+				yield(self)
+				close
+			end
+		end
+		
+		# Closes the connection with the board.
+		#
+		# @return [nil]
+		
+		def close
+			@serial.close
+			nil
+		end
+		
+		# Sets the mode of operation for a specific pin.
+		#
+		# @param pin [Integer] pin number (as stated in the board).
+		# @param mode [Integer] mode of operation: {INPUT}, {OUTPUT} or {INPUT_PULLUP}.
+		# @return [Boolean] if the command was successful.
+		# @raise [DeviceError] on unexpected device errors.
+		
+		def pinMode(pin, mode)
+			try(false) {
+				sendCMD [1, pin, mode]
+				onACK {true}
+			}
+		end
+		
+		# Reads the value from a specified digital pin.
+		#
+		# @param pin [Integer] pin number (as stated in the board).
+		# @return [Integer, nil] {HIGH} (1), {LOW} (0) or *nil* on error.
+		# @raise (see #pinMode)
+		
+		def digitalRead(pin)
+			try(nil) {
+				sendCMD [2, pin, empty]
+				onACK do
+					onData(4) do |bytes|
+						bytes[0]
+					end
+				end
+			}
+		end
+		
+		# Writes a {HIGH} (1) or a {LOW} (0) value to a digital pin. 
+		#
+		# @param pin [Integer] pin number (as stated in the board).
+		# @param state [Integer] {HIGH} (1) or {LOW} (0).
+		# @return (see #pinMode)
+		# @raise (see #pinMode)
+		
+		def digitalWrite(pin, state)
+			try(false) {
+				sendCMD [3, pin, state]
+				onACK {true}
+			}
+		end
+		
+		# Reads the value from a specified analog pin.
+		#
+		# @param pin [Integer] pin number (as stated in the board).
+		# @return [Integer, nil] an integer between *0* and *1023* or *nil* on error.
+		# @raise (see #pinMode)
+		
+		def analogRead(pin)
+			try(nil) {
+				sendCMD [4, pin, empty]
+				onACK do
+					onData(4) do |bytes|
+						bytes[0] + (bytes[1] << 8)
+					end
+				end
+			}
+		end
+		
+		# Writes an analog value (PWM wave) to a pin.
+		#
+		# @param pin [Integer] pin number (as stated in the board).
+		# @param value [Integer] an integer between *0* (always off) and *255* (always on).
+		# @return (see #pinMode)
+		# @raise (see #pinMode)
+		
+		def analogWrite(pin, value)
+			try(false) {
+				sendCMD [5, pin, value]
+				onACK {true}
+			}
+		end
+		
+		# Configures the reference voltage used for analog input.
+		#
+		# @param type [Integer] {DEFAULT}, {EXTERNAL}, {INTERNAL}, {INTERNAL1V1} or {INTERNAL2V56}.
+		# @return (see #pinMode)
+		# @raise (see #pinMode)
+		
+		def analogReference(type)
+			try(false) {
+				sendCMD [6, type, empty]
+				onACK {true}
+			}
+		end
+		
+		# Returns the number of milliseconds since the Arduino board began running the current program.
+		#
+		# @return [Integer, nil] a *32bit* *integer* or *nil* on error.
+		# @raise (see #pinMode)
+		
+		def millis
+			try(nil) {
+				sendCMD [7, empty, empty]
+				onACK do
+					onData(4) do |bytes|
+						bytes[0] + (bytes[1] << 8) + (bytes[2] << 16) + (bytes[3] << 24)
+					end
+				end
+			}
+		end
+		
+		# Tells if the board is ready.
+		#
+		# @return [Boolean]
+		# @raise (see #pinMode)
+		
+		def ready?
+			try(false) {
+				sendCMD [8, empty, empty]
+				onACK {true}
+			}
+		end
+		
+		private
+		
+		def try(ret, &block)
+			instance_eval(&block)
+		rescue => e
+			@serial.flush_input
+			case e
+				when EOFError, Aio::CommandError
+					return ret
+				when Errno::EIO
+					raise(Aio::DeviceError, e.message)
+				else
+					raise
+			end
+		end
+		
+		def onACK(&block)
+			if @serial.readbyte == ACK
+				instance_eval(&block)
+			else
+				raise Aio::CommandError
+			end
+		end
+		
+		def onData(n, &block)
+			bytes = readBytes(n)
+			lrc = @serial.readbyte
+			if lrc == getLRC(bytes)
+				instance_exec(bytes, &block)
+			else
+				raise Aio::CommandError
+			end
+		end
+		
+		def sendCMD(ary)
+			@serial.putc(SYNCBYTE)
+			ary.each {|byte| @serial.putc(byte.to_i)}
+			@serial.putc(getLRC(ary))
+		end
+		
+		def readBytes(n)
+			bytes = []
+			n.times {bytes << @serial.readbyte}
+			bytes
+		end
+		
+		def getLRC(ary)
+			lrc = ary.inject(0) {|acc,val| (acc + (val.to_i & 0xff)) & 0xff}
+			(lrc ^ 0xff) + 1
+		end
+		
+		def empty
+			rand(256)
+		end
+	end
+end

data/lib/aio/constants.rb

@@ -0,0 +1,28 @@
+module Aio
+	# Baud rate (shared with the sketch).
+	#
+	# Changing it requires printing and burning the sketch again.
+	
+	BAUDRATE = 57600
+	
+	# Read timeout in milliseconds (shared with the sketch).
+	#
+	# Changing it requires printing and burning the sketch again.
+	
+	TIMEOUT = 100
+	
+	ACK = 246
+	NAK = 144
+	SYNCBYTE = 255
+	
+	LOW = 0
+	HIGH = 1
+	INPUT = 0
+	OUTPUT = 1
+	INPUT_PULLUP = 2
+	EXTERNAL = 0
+	DEFAULT = 1
+	INTERNAL = 3
+	INTERNAL1V1 = 2
+	INTERNAL2V56 = 3
+end

data/lib/aio/errors.rb

@@ -0,0 +1,17 @@
+module Aio
+	# Generic error.
+	
+	class Error < StandardError
+	end
+	
+	# This exception handles serious errors, like an unexpected
+	# disconnection between the PC and the Arduino.
+	
+	class DeviceError < Aio::Error
+	end
+	
+	# @private
+	
+	class CommandError < Aio::Error
+	end
+end

data/lib/aio/helpers.rb

@@ -0,0 +1,86 @@
+module Aio
+	# This module adds most of the Arduino Reference functionality.
+	#
+	# Check the {http://www.arduino.cc/en/reference/homePage Arduino Reference}
+	# for more information about them.
+	
+	module Helpers
+		def lowByte(num)
+			num & 0xff
+		end
+		
+		def highByte(num)
+			num & 0xff00
+		end
+		
+		def bit(n)
+			2**n
+		end
+		
+		def bitClear(num, pos)
+			num & ~(0x01 << pos)
+		end
+		
+		def bitSet(num, pos)
+			num | (0x01 << pos)
+		end
+		
+		def bitRead(num, pos)
+			(num & (0x01 << pos)) >> pos
+		end
+		
+		def bitWrite(num, pos, value)
+			value == 0 ? bitClear(num, pos) : bitSet(num, pos)
+		end
+		
+		def min(x, y)
+			x < y ? x : y
+		end
+		
+		def max(x, y)
+			x < y ? y : x
+		end
+		
+		def abs(num)
+			num > 0 ? num : -num
+		end
+		
+		def pow(base, exponent)
+			base ** exponent
+		end
+		
+		def sqrt(num)
+			Math.sqrt(num)
+		end
+		
+		def sin(rad)
+			Math.sin(rad)
+		end
+		
+		def cos(rad)
+			Math.cos(rad)
+		end
+		
+		def tan(rad)
+			Math.tan(rad)
+		end
+		
+		def map(value, min0, max0, min1, max1)
+			((value - min0) * (max1 - min1) / (max0 - min0)) + min0
+		end
+		
+		def constrain(value, a, b)
+			return a if value < a
+			return b if value > b
+			value
+		end
+		
+		def random(a, b = nil)
+			(a and b) ? rand(a..b) : rand(a)
+		end
+		
+		def randomSeed(seed)
+			srand(seed)
+		end
+	end
+end

data/lib/aio/sketch.rb

@@ -0,0 +1,83 @@
+module Aio
+	private
+	
+	# Arduino sketch written in C.
+	
+	SKETCH = <<-SKETCH_END
+		#define ISIZE 3
+		#define OSIZE 4
+		
+		void setup() {
+		  Serial.begin(#{BAUDRATE}L);
+		  Serial.setTimeout(#{TIMEOUT}L);
+		}
+		
+		byte input[ISIZE];
+		byte output[OSIZE];
+		
+		void loop() {
+		  byte lrc;
+		  int param16;
+		  long param32;
+		  
+		  while(Serial.read() != #{SYNCBYTE}); /* wait for sync byte */
+		  
+		  if (readBytes(input, ISIZE) && readBytes(&lrc, 1) && (lrc == getLRC(input, ISIZE))) {
+		    Serial.write(#{ACK});
+		    switch(input[0]) {
+		      case 1: /* pinMode */
+		        pinMode(input[1], input[2]);
+		        break;
+		      case 2: /* digitalRead */
+		        output[0] = digitalRead(input[1]);
+		        fill(output, OSIZE, 1);
+		        Serial.write(output, OSIZE);
+		        Serial.write(getLRC(output, OSIZE));
+		        break;
+		      case 3: /* digitalWrite */
+		        digitalWrite(input[1], input[2]);
+		        break;
+		      case 4: /* analogRead */
+		        *((int *)output) = analogRead(input[1]);
+		        fill(output, OSIZE, 2);
+		        Serial.write(output, OSIZE);
+		        Serial.write(getLRC(output, OSIZE));
+		        break;
+		      case 5: /* analogWrite */
+		        analogWrite(input[1], input[2]);
+		        break;
+		      case 6: /* analogReference */
+		        analogReference(input[1]);
+		        break;
+		      case 7: /* millis */
+		        *((long *)output) = millis();
+		        Serial.write(output, OSIZE);
+		        Serial.write(getLRC(output, OSIZE));
+		        break;
+		      case 8: /* ready */
+		        /* nop */
+		        break;
+		    }
+		  } else {
+		    Serial.write(#{NAK});
+		  }
+		}
+		
+		byte getLRC(byte *buff, int length) {
+		  byte lrc = 0;
+		  
+		  for(int c = 0; c < length; c++)
+		    lrc += buff[c];
+		  return ((lrc ^ 0xff) + 1);
+		}
+		
+		int readBytes(byte *buff, int length) {
+		  return (Serial.readBytes(buff, length) == length);
+		}
+		
+		void fill(byte *buff, int length, int start) {
+		  for(int c = start; c < length; c++)
+		    buff[c] = random(256);
+		}
+	SKETCH_END
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: aio
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Javier Valencia
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: serialport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: "'Aio' is a robust library that implements redundancy checks and command
+  confirmation aimed at controlling Arduino boards remotely."
+email:
+- javiervalencia80@gmail.com
+executables:
+- aiosketch
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/aiosketch
+- lib/aio.rb
+- lib/aio/board.rb
+- lib/aio/constants.rb
+- lib/aio/errors.rb
+- lib/aio/helpers.rb
+- lib/aio/sketch.rb
+homepage: http://rubygems.org/gems/aio
+licenses:
+- GPL-2.0
+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: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Library for remotely controlling Arduino boards with Ruby code using the
+  serial port.
+test_files: []
+has_rdoc: