msr 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: db0608761faf290f7fb9eceac6be19f584a8b050
-  data.tar.gz: 91a207db5a02beba3ebfa044e5bc10a2e22f34f8
+  metadata.gz: 81af545812e6fab9ed1c61e8b69d1e82b961b068
+  data.tar.gz: fcd4c2cd3216794423db08a215db459739f2a7a0
 SHA512:
-  metadata.gz: f834b5ee6d3c3771b7d3214676b1d3e27caf3b2d66cd40a3a927d8485092eac8c5743dbc58dca2a2e5619555a8930f5aba97ae4f7917878ca907e3becda38b0a
-  data.tar.gz: 3be025af516e630802c1916e2a40504bc4d95702e6cb6f8fbb9899edf7afa545d19603e820267ac54196732dc45a598b4ef07807606a7857fb89241f4fb994a0
+  metadata.gz: 4179c29875a10c5d015a27ffffc80e1297a67e829385a8de3166aa903287d2640635c26242120e9982a05447bc6a3d8adb83a5af16bc698eb1851d894265aa73
+  data.tar.gz: a398a654f8304bdc7ad1dec138917d9bf29fb95fcfe34b7e4c5a86a4890f533e07ae7e06101e0e193b67f461945a302fb4e9b362dee3ce2e17e928defe616a16

data/.yardopts

@@ -0,0 +1 @@
+--no-private --markup-provider=redcarpet --markup=markdown - README.md LICENSE

data/ext/msr/msr206.c

@@ -4,25 +4,114 @@ VALUE cMSR_MSR206 = Qnil;
 
 static VALUE allocate(VALUE klass);
 static void deallocate_206_ctx(msr206_ctx_t *ctx);
+
+/*
+	Create a new {MSR::MSR206} instance for a serial device.
+	@param device [String] the serial device to connect to
+	@raise [RuntimeError] if the device can't be opened and/or initialized
+	@example
+		msr = MSR::MSR206.new("/dev/ttyUSB0")
+*/
 static VALUE initialize(VALUE self, VALUE rb_string);
+
+/*
+	Run a communications test between the system and the device.
+	@return [Symbol] `:pass` if the test succeeded, or `:fail` if it failed
+*/
 static VALUE comm_test(VALUE self);
+
+/*
+	Run a test of the device's magnetic sensor.
+	@return [Symbol] `:pass` if the test succeeded, or `:fail` if it failed
+	@note This method is interactive.
+*/
 static VALUE sensor_test(VALUE self);
+
+/*
+	Run a test of the device's internal RAM.
+	@return [Symbol] `:pass` if the test succeeded, or `:fail` if it failed
+*/
 static VALUE ram_test(VALUE self);
+
+
+/*
+	Reset the device to a ready state.
+	@note This method pauses for 100ms.
+*/
 static VALUE reset(VALUE self);
+
+/*
+	Get the device's current coercivity level.
+	@return [Symbol] `:hi` if the device is in Hi-Co mode, `:lo` if Lo-Co
+	@raise [RuntimeError] if the device returns a bad response
+*/
 static VALUE get_coercivity(VALUE self);
+
+/*
+	Set the device's coercivity level.
+	@param coercivity [Symbol] `:hi` for Hi-Co, and `:lo` for Lo-Co
+	@raise [ArgumentError] if the coercivity level is unrecognized
+	@raise [RuntimeError] if the device returns a bad response
+*/
 static VALUE set_coercivity(VALUE self, VALUE co_sym);
+
+/*
+	Set the bits-per-inch on the second track.
+	@param bpi [Fixnum] the BPI setting, either 75 or 210
+	@raise [RuntimeError] if the device returns a bad response
+	@note This only applies to the second track.
+*/
 static VALUE set_bpi(VALUE self, VALUE bpi);
-static VALUE set_bpc(VALUE self, VALUE bpc1, VALUE bpc2, VALUE bpc3);
+
+/*
+	Set the bits-per-character on each track.
+	@param bpc_ary [Array<Fixnum>] the array of BPC values
+	@raise [RuntimeError] if the device returns a bad response
+*/
+static VALUE set_bpc(VALUE self, VALUE bpc_ary);
+
+/*
+	Control the LEDs on the device.
+	@param led [Symbol] the LED command (`:green`, `:yellow`, `:red`, `:all`,
+		`:none`)
+	@raise [ArgumentError] if the LED command is unrecognized
+*/
 static VALUE set_led(VALUE self, VALUE led_sym);
+
+/*
+	Read raw data from a card.
+	@return [MSR::Tracks] a new tracks object containing the raw card data
+	@note This method is interactive.
+*/
 static VALUE raw_read(VALUE self);
+
+/*
+	Read ISO-formatted data from a card.
+	@return [MSR::Tracks] a new tracks object containing the ISO card data
+	@note This method is interactive.
+*/
 static VALUE iso_read(VALUE self);
+
+/*
+	Write raw data to a card.
+	@param tracks [MSR::Tracks] the raw tracks to write to the card
+	@note This method is interactive.
+*/
 static VALUE raw_write(VALUE self, VALUE tks_obj);
+
+/*
+	Write ISO-formatted data to a card.
+	@param tracks [MSR::Tracks] the ISO tracks to write to the card
+	@note This method is interactive.
+*/
 static VALUE iso_write(VALUE self, VALUE tks_obj);
 
+
 void Init_msr_msr206()
 {
 	cMSR_MSR206 = rb_define_class_under(mMSR, "MSR206", rb_cObject);
 	rb_define_alloc_func(cMSR_MSR206, allocate);
+
 	rb_define_method(cMSR_MSR206, "initialize", initialize, 1);
 	rb_define_method(cMSR_MSR206, "comm_test!", comm_test, 0);
 	rb_define_method(cMSR_MSR206, "sensor_test!", sensor_test, 0);
@@ -31,7 +120,7 @@ void Init_msr_msr206()
 	rb_define_method(cMSR_MSR206, "coercivity", get_coercivity, 0);
 	rb_define_method(cMSR_MSR206, "coercivity=", set_coercivity, 1);
 	rb_define_method(cMSR_MSR206, "bpi=", set_bpi, 1);
-	rb_define_method(cMSR_MSR206, "bpc=", set_bpc, 3);
+	rb_define_method(cMSR_MSR206, "bpc=", set_bpc, 1);
 	rb_define_method(cMSR_MSR206, "led=", set_led, 1);
 	rb_define_method(cMSR_MSR206, "raw_read", raw_read, 0);
 	rb_define_method(cMSR_MSR206, "iso_read", iso_read, 0);
@@ -217,22 +306,26 @@ static VALUE set_bpi(VALUE self, VALUE bpi)
 	return self;
 }
 
-static VALUE set_bpc(VALUE self, VALUE bpc1, VALUE bpc2, VALUE bpc3)
+static VALUE set_bpc(VALUE self, VALUE bpc_ary)
 {
-	uint8_t bpc_tk1, bpc_tk2, bpc_tk3;
+	uint8_t bpcs[3] = {0};
 	msr206_ctx_t *ctx;
 	int ret;
 
-	Check_Type(bpc1, T_FIXNUM);
-	Check_Type(bpc2, T_FIXNUM);
-	Check_Type(bpc3, T_FIXNUM);
+	Check_Type(bpc_ary, T_ARRAY);
 	Data_Get_Struct(self, msr206_ctx_t, ctx);
 
-	bpc_tk1 = NUM2CHR(bpc1);
-	bpc_tk2 = NUM2CHR(bpc2);
-	bpc_tk3 = NUM2CHR(bpc3);
+	if (RARRAY_LEN(bpc_ary) != MSR_MAX_TRACKS) {
+		rb_raise(rb_eArgError, "Expected %d BPC values, got %ld",
+			MSR_MAX_TRACKS, RARRAY_LEN(bpc_ary));
+	}
+
+	for (int i = 0; i < MSR_MAX_TRACKS; i++) {
+		Check_Type(rb_ary_entry(bpc_ary, i), T_FIXNUM);
+		bpcs[i] = (uint8_t) NUM2CHR(rb_ary_entry(bpc_ary, i));
+	}
 
-	ret = msr_set_bpc(ctx->fd, bpc_tk1, bpc_tk2, bpc_tk3);
+	ret = msr_set_bpc(ctx->fd, bpcs[0], bpcs[1], bpcs[2]);
 
 	if (ret != LIBMSR_ERR_OK) {
 		rb_raise(rb_eRuntimeError, "Couldn't change bpc (%d)", ret);

data/ext/msr/track.c

@@ -1,8 +1,23 @@
 #include "msr.h"
 
+/*
+	The data associated with the track.
+	@return [Array<Fixnum>] the track data
+*/
 static VALUE msr_track_data(VALUE self);
+
+/*
+	The length of the track's data.
+	@return [Fixnum] the track length
+*/
 static VALUE msr_track_length(VALUE self);
 
+/*
+	Reverse the direction of the track, returning a new object.
+	@return [MSR::Track] the reversed track
+*/
+static VALUE msr_track_reverse(VALUE self);
+
 VALUE c_MSR_Track = Qnil;
 
 void Init_msr_track()
@@ -14,6 +29,7 @@ void Init_msr_track()
 	rb_define_method(c_MSR_Track, "initialize", msr_track_initialize, 1);
 	rb_define_method(c_MSR_Track, "data", msr_track_data, 0);
 	rb_define_method(c_MSR_Track, "length", msr_track_length, 0);
+	rb_define_method(c_MSR_Track, "reverse", msr_track_reverse, 0);
 }
 
 VALUE msr_track_initialize(VALUE self, VALUE tk_data_ary)
@@ -48,3 +64,14 @@ static VALUE msr_track_length(VALUE self)
 
 	return INT2NUM(RARRAY_LEN(tk_data_ary));
 }
+
+static VALUE msr_track_reverse(VALUE self)
+{
+	msr_track_t tk;
+
+	msr_unwrap_track(self, &tk);
+
+	msr_reverse_track(&tk);
+
+	return msr_track_new(tk);
+}

data/ext/msr/tracks.c

@@ -1,9 +1,29 @@
 #include "msr.h"
 
+/*
+	The first track on the card.
+	@return [MSR::Track] the track object
+*/
 static VALUE msr_tracks_track1(VALUE self);
+
+/*
+	The second track on the card.
+	@return [MSR::Track] the track object
+*/
 static VALUE msr_tracks_track2(VALUE self);
+
+/*
+	The third track on the card.
+	@return [MSR::Track] the track object
+*/
 static VALUE msr_tracks_track3(VALUE self);
 
+/*
+	Reverse the direction of the tracks, returning a new object.
+	@return [MSR::Tracks] the reversed tracks
+*/
+static VALUE msr_tracks_reverse(VALUE self);
+
 VALUE c_MSR_Tracks = Qnil;
 
 void Init_msr_tracks()
@@ -14,6 +34,7 @@ void Init_msr_tracks()
 	rb_define_method(c_MSR_Tracks, "track1", msr_tracks_track1, 0);
 	rb_define_method(c_MSR_Tracks, "track2", msr_tracks_track2, 0);
 	rb_define_method(c_MSR_Tracks, "track3", msr_tracks_track3, 0);
+	rb_define_method(c_MSR_Tracks, "reverse", msr_tracks_reverse, 0);
 }
 
 VALUE msr_tracks_initialize(VALUE self, VALUE tk1, VALUE tk2, VALUE tk3)
@@ -51,3 +72,14 @@ static VALUE msr_tracks_track3(VALUE self)
 {
 	return rb_iv_get(self, "@track3");
 }
+
+static VALUE msr_tracks_reverse(VALUE self)
+{
+	msr_tracks_t tks;
+
+	msr_unwrap_tracks(self, &tks);
+
+	msr_reverse_tracks(&tks);
+
+	return msr_tracks_new(tks);
+}

data/lib/msr.rb

@@ -2,7 +2,8 @@ require_relative "../ext/msr/msr"
 require_relative "msr/track"
 require_relative "msr/tracks"
 require_relative "msr/msr206"
+require_relative "msr/msr505c"
 
 module MSR
-  VERSION = "0.0.2".freeze
+  VERSION = "0.0.3".freeze
 end

data/lib/msr/msr206.rb

@@ -1,5 +1,9 @@
 module MSR
+  # Represents a connection to an MSR206 (or MSR206-compatible device).
   class MSR206
+    # Whether or not the device is currently linked.
+    # Corresponds to {#comm_test!} being passed.
+    # @return [Boolean] `true` if linked, `false` otherwise
     def linked?
       comm_test! == :pass
     end

data/lib/msr/msr505c.rb

@@ -0,0 +1,5 @@
+module MSR
+  # Alias MSR505C to MSR206, since the two are firmware compatible.
+  # @see MSR206
+  MSR505C = MSR206
+end

data/lib/msr/track.rb

@@ -1,5 +1,19 @@
 module MSR
+  # Represents a single track from a magnetic stripe card.
   class Track
+    # Reverse the direction of the track, in place.
+    # @return [MSR::Tracks] the current instance
+    def reverse!
+      reversed = self.reverse
+
+      @data = reversed.data
+
+      self # return ourself, just for convenience
+    end
+
+    # Compare two tracks for equality. Two tracks are said to be equal if they
+    # contain the same data, in the same order.
+    # @return [Boolean] `true` if the two are equal, `false` otherwise
     def ==(o)
       return unless o.is_a?(self.class)
       data == o.data

data/lib/msr/tracks.rb

@@ -1,5 +1,21 @@
 module MSR
+  # Represents (up to) three tracks from a magnetic stripe card.
   class Tracks
+    # Reverse the direction of the tracks, in place.
+    # @return [MSR::Tracks] the current instance
+    def reverse!
+      reversed = self.reverse
+
+      @track1 = reversed.track1
+      @track2 = reversed.track2
+      @track3 = reversed.track3
+
+      self # return ourself, just for convenience
+    end
+
+    # Compare two sets of tracks for equality. Two sets are said to be equal
+    # if all of their corresponding pairs are equal.
+    # @return [Boolean] `true` if the two are equal, `false` otherwise
     def ==(o)
       return unless o.is_a?(self.class)
       track1 == o.track1 && track2 == o.track2 && track3 == o.track3

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: msr
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - William Woodruff
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-10-21 00:00:00.000000000 Z
+date: 2016-11-03 00:00:00.000000000 Z
 dependencies: []
 description: A library for controlling magnetic stripe reader/writers.
 email: william@tuffbizz.com
@@ -17,6 +17,7 @@ extensions:
 - ext/msr/extconf.rb
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - LICENSE
 - README.md
 - ext/msr/extconf.rb
@@ -27,6 +28,7 @@ files:
 - ext/msr/tracks.c
 - lib/msr.rb
 - lib/msr/msr206.rb
+- lib/msr/msr505c.rb
 - lib/msr/track.rb
 - lib/msr/tracks.rb
 homepage: https://github.com/woodruffw/ruby-msr