ant-wireless 0.1.0.pre.20210715102740 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60051597c316ed311fb5c3203f5903e62f46e107c2094ae379db5dbf07c8232e
-  data.tar.gz: 41a4cc508416234557867b3fd0ac8c27c5d856cea90c7531fb99f29106028ec8
+  metadata.gz: abd16b62c0eb3b3e7e683fd46cca0382fa6b0400f23d8ae8a12de4455e66599a
+  data.tar.gz: c0e7b0571d2cb8285f072b23027b226ac4c472e0b2147faa34c1bd13d4c78aef
 SHA512:
-  metadata.gz: 22d0cf3c237e478f41ed217a67ce07a13e1dea8584142bee797fa7085cbf5e24445758cba5b2d29f7ca2ea50f973e20bb231e6579c50647bf286bb94e935f144
-  data.tar.gz: 3ce7d04e91583044385715746750f9bfd83dcbd06831a0e38f8c123f57e05fd778c6eaf13e5f9a6d770e85156c8406f7c195eab637a620dc6b5fa99f66ff829f
+  metadata.gz: 994058a2faa922f5d5469b9ab04aa5eecefaa6fdac4921a035a9bfe4f0ca58bea90a32f225c54d695f93b5cc27bcaf87ce2442b80160984944e7a04234eb0036
+  data.tar.gz: 11f91861b51651d3cfba2309334ac4e9253a4ea9bc313bd0434f42eaa4a86e05d3659b11cfed13a85b162761b1913afb2da13d99faf58f1b14cf53b52fb03da3

data/History.md

@@ -1,5 +1,24 @@
 # Release History for ruby-ant
 
 ---
+## v0.2.1 [2021-09-30] Michael Granger <ged@FaerieMUD.org>
 
+Bugfixes:
+
+- Add missing files to the manifest
+
+
+
+## v0.2.0 [2021-09-22] Michael Granger <ged@FaerieMUD.org>
+
+Enhancements:
+
+- Add channel period, search timeout, and introspection methods
+- Add Ant.initialized? predicate
+- Make the default response and event callback modules more useful.
+
+
+## v0.1.0 [2021-08-26] Michael Granger <ged@FaerieMUD.org>
+
+First release.
 

data/README.md

@@ -20,8 +20,13 @@ manner.
 
 ## Prerequisites
 
-* Ruby
-* Garmin USB ANT Stick (https://buy.garmin.com/en-US/US/p/10997/pn/010-01058-00)
+* Ruby 2.7.x or later
+* [Garmin USB ANT Stick][antstick]
+* [ANT SDK][antsdk]
+
+Note that we had trouble compiling the latest ANT SDK on some platforms, so we are currently using a modified version of it with a reworked build system for MacOS and FreeBSD. That is available under the same licensing terms at:
+
+https://github.com/RavnGroup/Garmin-ANT-SDK
 
 
 ## Installation
@@ -52,6 +57,12 @@ This task will install dependencies, and do any other necessary setup for develo
 
 ## License
 
+Portions of this code are from StaticCling, and are used under the
+terms of the 3-Clause BSD License. Specifics can be found in the
+appropriate files.
+
+This software is:
+
 Copyright (c) 2021, Ravn Group
 
 Permission is hereby granted, free of charge, to any person obtaining
@@ -76,4 +87,5 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 [ant]: https://www.thisisant.com/
 [antstick]: https://buy.garmin.com/en-US/US/p/10997/pn/010-01058-00
+[antsdk]: https://www.thisisant.com/developer/resources/downloads/#software_tab
 

data/ext/ant_ext/ant_ext.c

@@ -225,6 +225,17 @@ rant_s_init( int argc, VALUE *argv, VALUE _module )
 }
 
 
+static VALUE
+rant_s_initialized_p( VALUE _module )
+{
+#ifdef HAVE_ANT_ISINITIALIZED
+	const bool initialized = ANT_IsInitialized();
+	return initialized ? Qtrue : Qfalse;
+#else
+	rb_notimplement();
+#endif
+}
+
 
 /*
  * call-seq:
@@ -291,7 +302,7 @@ rant_s_set_network_key( VALUE _module, VALUE network_number, VALUE key )
 	}
 
 	if ( !ANT_SetNetworkKey(ucNetNumber, (unsigned char *)pucKey) ) {
-		rb_raise( rb_eRuntimeError, "could not set the network key." );
+		rant_log( "error", "could not set the network key." );
 	}
 
 	return Qtrue;
@@ -463,6 +474,56 @@ rant_s_on_response( int argc, VALUE *argv, VALUE module )
 }
 
 
+/*
+ * call-seq:
+ *    Ant.request_capabilities
+ *
+ * Request the current ANT device's capabilities. These will be delivered
+ * via a callback to the #on_capabilities response callback, which by default
+ * extracts them into a Hash which is stored at Ant.capabilities.
+ *
+ */
+static VALUE
+rant_s_request_capabilities( VALUE module )
+{
+	bool rval = ANT_RequestMessage( 0, MESG_CAPABILITIES_ID );
+	return rval ? Qtrue : Qfalse;
+}
+
+
+/*
+ * call-seq:
+ *    Ant.request_serial_num
+ *
+ * Request the current ANT device's serial number. The result will be delivered
+ * via a callback to the #on_get_serial_num response callback, which by default
+ * extracts it and stores it at Ant.serial_number.
+ *
+ */
+static VALUE
+rant_s_request_serial_num( VALUE module )
+{
+	bool rval = ANT_RequestMessage( 0, MESG_GET_SERIAL_NUM_ID );
+	return rval ? Qtrue : Qfalse;
+}
+
+
+/*
+ * call-seq:
+ *    Ant.request_version
+ *
+ * Request the current device's ANT version. The result will be delivered
+ * via a callback to the #on_version response callback, which by default
+ * extracts it and stores it at Ant.hardware_version.
+ *
+ */
+static VALUE
+rant_s_request_version( VALUE module )
+{
+	bool rval = ANT_RequestMessage( 0, MESG_VERSION_ID );
+	return rval ? Qtrue : Qfalse;
+}
+
 
 /*
  * call-seq:
@@ -490,7 +551,7 @@ Init_ant_ext()
 	/*
 	 * Document-module: Ant
 	 *
-	 * This is an extension for using the ANT ultra-low power wireless protocol via 
+	 * This is an extension for using the ANT ultra-low power wireless protocol via
 	 * the Garmin USB ANT Stick. ANT can be used to send information
 	 * wirelessly from one device to another device, in a robust and flexible
 	 * manner.
@@ -508,6 +569,7 @@ Init_ant_ext()
 	rb_define_singleton_method( rant_mAnt, "device_serial_number", rant_s_device_serial_number, 0 );
 
 	rb_define_singleton_method( rant_mAnt, "init", rant_s_init, -1 );
+	rb_define_singleton_method( rant_mAnt, "initialized?", rant_s_initialized_p, 0 );
 	// rb_define_singleton_method( rant_mAnt, "init_ext", rant_s_init_ext, 4 );
 	rb_define_singleton_method( rant_mAnt, "close", rant_s_close, 0 );
 	rb_define_singleton_method( rant_mAnt, "reset", rant_s_reset, 0 );
@@ -521,6 +583,9 @@ Init_ant_ext()
 	rb_define_singleton_method( rant_mAnt, "on_response", rant_s_on_response, -1 );
 	// EXPORT void ANT_UnassignAllResponseFunctions(); //Unassigns all response functions
 
+	rb_define_singleton_method( rant_mAnt, "request_capabilities", rant_s_request_capabilities, 0 );
+	rb_define_singleton_method( rant_mAnt, "request_serial_num", rant_s_request_serial_num, 0 );
+	rb_define_singleton_method( rant_mAnt, "request_version", rant_s_request_version, 0 );
 
 	rb_define_singleton_method( rant_mAnt, "log_directory=", rant_s_log_directory_eq, 1 );
 
@@ -537,6 +602,7 @@ Init_ant_ext()
 	EXPOSE_CONST( ANT_EXT_STRING_SIZE );
 	EXPOSE_CONST( ANT_EXT_MESG_BITFIELD_DEVICE_ID );
 	EXPOSE_CONST( ANT_EXT_MESG_BIFIELD_EXTENSION );
+	rb_define_const( rant_mAnt, "ANT_EXT_MESG_BITFIELD_EXTENSION", INT2FIX(ANT_EXT_MESG_BIFIELD_EXTENSION) );
 	EXPOSE_CONST( ANT_EXT_MESG_BITFIELD_OVERWRITE_SHARED_ADR );
 	EXPOSE_CONST( ANT_EXT_MESG_BITFIELD_TRANSMISSION_TYPE );
 
@@ -618,6 +684,9 @@ Init_ant_ext()
 	EXPOSE_CONST( CAPABILITIES_SELECTIVE_DATA_UPDATE_ENABLED );
 	EXPOSE_CONST( CAPABILITIES_ENCRYPTED_CHANNEL_ENABLED );
 
+	// Not in the header; this is taken from 9.5.7.4, ANT Message Protocol and Usage v5.1
+	rb_define_const( rant_mAnt, "CAPABILITIES_RFACTIVE_NOTIFICATION_ENABLED", INT2FIX(0) );
+
 	EXPOSE_CONST( CHANNEL_NUMBER_MASK );
 	EXPOSE_CONST( SEQUENCE_NUMBER_MASK );
 	EXPOSE_CONST( SEQUENCE_NUMBER_ROLLOVER );

data/ext/ant_ext/channel.c

@@ -128,6 +128,11 @@ rant_channel_init( VALUE self, VALUE channel_number, VALUE channel_type, VALUE n
 	rb_iv_set( self, "@network_number", network_number );
 	rb_iv_set( self, "@extended_options", extended_options );
 
+	rb_iv_set( self, "@device_type", Qnil );
+	rb_iv_set( self, "@device_number", Qnil );
+	rb_iv_set( self, "@transmission_type", Qnil );
+	rb_iv_set( self, "@rf_frequency", Qnil );
+
 	rb_hash_aset( registry, channel_number, self );
 
 	return self;
@@ -173,8 +178,8 @@ rant_channel_set_channel_id( int argc, VALUE *argv, VALUE self )
 	rb_scan_args( argc, argv, "31", &device_number, &device_type, &transmission_type, &timeout );
 
 	usDeviceNumber = NUM2USHORT( device_number );
-	ucDeviceType = NUM2USHORT( device_type );
-	ucTransmissionType = NUM2USHORT( transmission_type );
+	ucDeviceType = NUM2CHR( device_type );
+	ucTransmissionType = NUM2CHR( transmission_type );
 
 	if ( RTEST(timeout) )
 		ulResponseTime = NUM2UINT( timeout );
@@ -186,13 +191,114 @@ rant_channel_set_channel_id( int argc, VALUE *argv, VALUE self )
 		rb_raise( rb_eRuntimeError, "Failed to set the channel id." );
 	}
 
+	rb_iv_set( self, "@device_type", device_type );
+	rb_iv_set( self, "@device_number", device_number );
+	rb_iv_set( self, "@transmission_type", transmission_type );
+
+	return Qtrue;
+}
+
+
+/*
+ * call-seq:
+ *    channel.set_channel_period( period, timeout=0 )
+ *
+ * This message configures the messaging +period+ of a specific channel where:
+ * Messaging period = channel period time +period+ * 32768.
+ *
+ * E.g.: To send or receive a message at 4Hz, set the channel period to 8192 (32768/4).
+ *
+ * Note: The minimum acceptable channel period is difficult to specify as it is
+ * system dependent and depends on the number of configured channels and their use.
+ * Caution should be used to appropriately test the system when high data rates are
+ * used, especially in combination with multiple channels.
+ *
+ */
+static VALUE
+rant_channel_set_channel_period( int argc, VALUE *argv, VALUE self )
+{
+	rant_channel_t *ptr = rant_get_channel( self );
+	VALUE period, timeout;
+	unsigned int ulResponseTime = 0;
+	unsigned short usMesgPeriod;
+	bool result;
+
+	rb_scan_args( argc, argv, "11", &period, &timeout );
+
+	usMesgPeriod = NUM2USHORT( period );
+	if ( RTEST(timeout) )
+		ulResponseTime = NUM2UINT( timeout );
+
+	result = ANT_SetChannelPeriod_RTO( ptr->channel_num, usMesgPeriod, ulResponseTime );
+
+	if ( !result )
+		rb_raise( rb_eRuntimeError, "Failed to set the channel period." );
+
+	return Qtrue;
+}
+
+
+/*
+ * call-seq:
+ *    channel.set_channel_search_timeout( search_timeout, timeout=0 )
+ *
+ * Configure the length of time that the receiver will search for a channel
+ * before timing out. Note that a value of zero will disable high priority
+ * search mode, and a value of 255 sets an infinite search time-out. The
+ * exception to this is the AP1 module, which has only a high priority search
+ * mode. For AP1 only, a value of 0 is an immediate search timeout, and a value
+ * of 255 corresponds to approximately 10.5 minutes.
+ *
+ */
+static VALUE
+rant_channel_set_channel_search_timeout( int argc, VALUE *argv, VALUE self )
+{
+	rant_channel_t *ptr = rant_get_channel( self );
+	VALUE search_timeout, timeout;
+	unsigned int ulResponseTime = 0;
+	unsigned char ucSearchTimeout;
+	bool result;
+
+	rb_scan_args( argc, argv, "11", &search_timeout, &timeout );
+
+	ucSearchTimeout = NUM2CHR( search_timeout );
+	if ( RTEST(timeout) )
+		ulResponseTime = NUM2UINT( timeout );
+
+	result = ANT_SetChannelSearchTimeout_RTO( ptr->channel_num, ucSearchTimeout, ulResponseTime );
+
+	if ( !result )
+		rb_raise( rb_eRuntimeError, "Failed to set the channel search timeout." );
+
+	return Qtrue;
+}
+
+
+/*
+ * call-seq:
+ *    channel.set_channel_rf_freq( frequency )
+ *
+ * Set the ANT RF +frequency+.
+ *
+ */
+static VALUE
+rant_channel_set_channel_rf_freq( VALUE self, VALUE frequency )
+{
+	rant_channel_t *ptr = rant_get_channel( self );
+	unsigned short ucRFFreq = NUM2USHORT( frequency );
+
+	if ( ucRFFreq > 124 ) {
+		rb_raise( rb_eArgError, "frequency must be between 0 and 124." );
+	}
+
+	ANT_SetChannelRFFreq( ptr->channel_num, ucRFFreq );
+
+	rb_iv_set( self, "@rf_frequency", frequency );
+
 	return Qtrue;
 }
 
 
-// ANT_SetChannelPeriod_RTO(UCHAR ucANTChannel_, USHORT usMesgPeriod_, ULONG ulResponseTime_);
-// ANT_SetChannelSearchTimeout_RTO(UCHAR ucANTChannel_, UCHAR ucSearchTimeout_, ULONG ulResponseTime_);
-// ANT_SetChannelRFFreq_RTO(UCHAR ucANTChannel_, UCHAR ucRFFreq_, ULONG ulResponseTime_);
 
 
 /*
@@ -450,29 +556,6 @@ rant_channel_send_broadcast_data( VALUE self, VALUE data )
 }
 
 
-/*
- * call-seq:
- *    channel.set_channel_rf_freq( frequency )
- *
- * Set the ANT RF +frequency+.
- *
- */
-static VALUE
-rant_channel_set_channel_rf_freq( VALUE self, VALUE frequency )
-{
-	rant_channel_t *ptr = rant_get_channel( self );
-	unsigned short ucRFFreq = NUM2USHORT( frequency );
-
-	if ( ucRFFreq > 124 ) {
-		rb_raise( rb_eArgError, "frequency must be between 0 and 124." );
-	}
-
-	ANT_SetChannelRFFreq( ptr->channel_num, ucRFFreq );
-
-	return Qtrue;
-}
-
-
 void
 init_ant_channel()
 {
@@ -501,11 +584,15 @@ init_ant_channel()
 	rb_attr( rant_cAntChannel, rb_intern("network_number"), 1, 0, 0 );
 	rb_attr( rant_cAntChannel, rb_intern("extended_options"), 1, 0, 0 );
 
+	rb_attr( rant_cAntChannel, rb_intern("device_number"), 1, 0, 0 );
+	rb_attr( rant_cAntChannel, rb_intern("device_type"), 1, 0, 0 );
+	rb_attr( rant_cAntChannel, rb_intern("transmission_type"), 1, 0, 0 );
+	rb_attr( rant_cAntChannel, rb_intern("rf_frequency"), 1, 0, 0 );
+
 	rb_define_method( rant_cAntChannel, "set_channel_id", rant_channel_set_channel_id, -1 );
-	// rb_define_method( rant_cAntChannel, "set_channel_period",
-	// rant_channel_set_channel_period, -1 );
-	// rb_define_method( rant_cAntChannel, "set_channel_search_timeout",
-	// rant_channel_set_channel_search_timeout, -1 );
+	rb_define_method( rant_cAntChannel, "set_channel_period", rant_channel_set_channel_period, -1 );
+	rb_define_method( rant_cAntChannel, "set_channel_search_timeout",
+		rant_channel_set_channel_search_timeout, -1 );
 	rb_define_method( rant_cAntChannel, "set_channel_rf_freq", rant_channel_set_channel_rf_freq, 1 );
 
 	rb_define_method( rant_cAntChannel, "open", rant_channel_open, -1 );

data/ext/ant_ext/extconf.rb

@@ -14,6 +14,7 @@ have_header( 'ruby/thread.h' ) or
 	abort "Your Ruby is too old!"
 
 have_func( 'ANT_Init', 'libant.h' )
+have_func( 'ANT_IsInitialized', 'libant.h' )
 have_func( 'ANT_LibVersion', 'libant.h' )
 have_func( 'ANT_GetDeviceSerialNumber', 'libant.h' )
 

data/lib/ant/bitvector.rb

@@ -0,0 +1,197 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+# vim: set nosta noet ts=4 sw=4:
+
+require 'ant' unless defined?( Ant )
+
+# Ant::BitVector -- a convenience class for manipulating and
+# comparing bit vectors.
+#
+# This is a slightly-modified version of the same utility in StaticCling.
+#
+# == Synopsis
+#
+#   require 'ant/bitvector'
+#
+#   vector = Ant::BitVector.new
+#
+#   vector.on( 4 )     # => 16
+#   vector.on( 12 )    # => 4112
+#   vector.toggle( 4 ) # => 4096
+#   vector.on?( 4 )    # => false
+#   vector.size        # => 13
+#   vector.to_hex      # => 0x1000
+#
+#   vector2 = Ant::BitVector.new( 5 )
+#   vector > vector2   # => true
+#
+#   vector2.each_with_index do |bit, i|
+#		puts "Bit %d is %s" % [ i + 1, bit.zero? ? 'off' : 'on' ]
+#	end
+#
+#		Bit 1 is on
+#		Bit 2 is off
+#		Bit 3 is on
+#
+# == Version
+#
+#  $Id$
+#
+# == Author
+#
+# * Mahlon E. Smith <mahlon@martini.nu>
+#
+# == License
+#
+# Copyright (c) 2000-2013, Mahlon E. Smith <mahlon@martini.nu>
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#     * Redistributions of source code must retain the above copyright notice,
+#     this list of conditions and the following disclaimer.
+#
+#     * 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.
+#
+#     * Neither the name of the author, nor the names of 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 OWNER 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.
+#
+class Ant::BitVector
+	include Enumerable,
+		Comparable
+
+	### Create a new bit vector object, optionally from a pre-existing
+	### +init+ number (Any number that ruby supports natively should be
+	### fine -- 0b, 0x, or decimal.)
+	def initialize( init=0 )
+		unless init.respond_to?( :to_i )
+			raise ArgumentError, "I don't know what to do with a %s object." % [ init.class.name ]
+		end
+
+		@bv = init.to_i
+	end
+
+
+	######
+	public
+	######
+
+	# let any additional methods fall through to Fixnum/Bignum objs,
+	# and return new vector objects.  This allows for doing bitwise math
+	# or simple addition/subtraction on two BitVector objects.
+	%w{ % & * ** + - / << >> ^ | ~ }.each do |op|
+		define_method( op.to_sym ) do |arg|
+			res = @bv.send( op.to_sym, arg.bv )
+			return self.class.new( res )
+		end
+	end
+
+
+	##
+	# Allow external access to the underlying Fixnum/Bignum
+	attr_reader :bv
+
+
+	### Return the bit vector as a decimal.
+	def to_i
+		return @bv
+	end
+	alias_method :to_int, :to_i
+	alias_method :to_dec, :to_i
+
+
+	### Return the bit vector as a binary string.
+	def to_bin
+		return "0b%s" % @bv.to_s(2)
+	end
+
+
+	### Return the bit vector as a hexidecimal string.
+	def to_hex
+		return "0x%04x" % @bv
+	end
+
+
+	### Return the length of the vector in bytes.
+	def size
+		return @bv.to_s(2).length
+	end
+
+
+	### Switch a +bit+ on.
+	def on( bit )
+		@bv = @bv | ( 1 << bit )
+	end
+
+
+	### Return boolean true if given +bit+ is currently on.
+	def on?( bit )
+		return @bv[ bit ].zero? ? false : true
+	end
+	alias_method :[], :on?
+
+
+	### Switch a +bit+ off.
+	def off( bit )
+		@bv = @bv & ~( 1 << bit )
+	end
+
+
+	### Return boolean true if given +bit+ is currently +off+.
+	def off?( bit )
+		return ! self.on?( bit )
+	end
+
+
+	### Swap the current state of the given +bit+.
+	def toggle( bit )
+		@bv = @bv ^ ( 1 << bit )
+	end
+	alias_method :flip, :toggle
+
+
+	### Set a +bit+ to +bool+ -- either true (on) or false (off).
+	### Any value other than nil or false is treated as true.
+	### This form also accepts ranges of bits, a la: vector[ 1..4 ] = true
+	def []=( bit, bool )
+		if bit.respond_to?( :each )
+			bit.each { |b| bool ? self.on( b ) : self.off( b ) }
+		else
+			bool ? self.on( bit ) : self.off( bit )
+		end
+	end
+
+
+	### Yield each binary position, least significant +bit+ first.
+	def each
+		@bv.to_s(2).reverse.each_byte do |bit|
+			yield bit.chr.to_i
+		end
+	end
+
+
+	### Comparision operator for Comparable mixin, fallthrough to
+	### Fixnum/Bignum.  Compares current state against +cmp+.
+	def <=>( cmp )
+		@bv <=> cmp.bv
+	end
+
+end # class Ant::BitVector
+