ant-wireless 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b16333eed832c3068cd6e95d167bffe8132aaba7543ccabd773d809fac840199
-  data.tar.gz: 92d089d1bcf5121dd46477befeabc33e43abbac10de105d3d94d176b54c9af8a
+  metadata.gz: 1cbf09bffd2b5ac2d18ea9fb271bb1e358707b45a49bd45651129d5030598e95
+  data.tar.gz: f2d892f9c17f352e81b1b6236ac567a62f24b61495860b0f071975bd80446ea8
 SHA512:
-  metadata.gz: 51dbc06b6c199f16404fb0d79fd78e10cf53c4ca68e221462d225e1dff171a51f5f1807da2ebe2719e45109e981ece26781090ebd583d4c8c01d6e1539c5e43a
-  data.tar.gz: da1492d614d52e83402c85bbeed0d45d03f7f101bd6b5036ae9bc7a488dfbd5df41ee5aa2a0a3b0a7b4e7019c4d95bc55d0167a3a6e77c1825565ca299ba492e
+  metadata.gz: 8ecd19b9d5c711fe0e71be58e5fa3c1386fa340bc9cafa0279e08ba52b48ebe8f7169386faf93fe5b7a900a8ee70d84d049f31db3405dc2c7e957fa5126fce2c
+  data.tar.gz: 83aa2b97810514c2279182d1853efeed48087e270cb6db2533b151cae046370a6071c7fa2ed164cf6558c79b1f970a3d18526c2188ea281dc4493ec8313ebec5

data/History.md

@@ -1,6 +1,13 @@
 # Release History for ruby-ant
 
 ---
+## v0.4.0 [2021-11-05] Michael Granger <ged@FaerieMUD.org>
+
+Enhancements:
+
+- Add advanced burst support (with a customized ANT-SDK).
+
+
 ## v0.3.0 [2021-10-11] Michael Granger <ged@FaerieMUD.org>
 
 Enhancements:

data/README.md

@@ -24,7 +24,10 @@ manner.
 * [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:
+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, and with implementations for advanced burst and checking
+initialization status. That is available under the same licensing terms at:
 
 https://github.com/RavnGroup/Garmin-ANT-SDK
 

data/ext/ant_ext/ant_ext.c

@@ -225,6 +225,15 @@ rant_s_init( int argc, VALUE *argv, VALUE _module )
 }
 
 
+/*
+ * call-seq:
+ *    Ant.initialized?   -> true or false
+ *
+ * Returns +true+ if the ANT library has been initialized.
+ *
+ * Note: this requires a modified version of the Garmin ANT-SDK.
+ *
+ */
 static VALUE
 rant_s_initialized_p( VALUE _module )
 {
@@ -418,6 +427,56 @@ rant_s_use_extended_messages_eq( VALUE _module, VALUE true_false )
 }
 
 
+/*
+ * call-seq:
+ *    Ant.configure_advanced_burst( enabled, max_packet_length, required_fields, optional_fields,
+ *        stall_count=3210, retry_count=4 )
+ *
+ * Enable/disable and configure advanced burst. This is the lower-level method; the
+ * higher-level methods are: #enable_advanced_burst and #disable_advanced_burst.
+ *
+ */
+static VALUE
+rant_s_configure_advanced_burst( int argc, VALUE *argv, VALUE _module )
+{
+	VALUE enabled,
+		max_packet_length,
+		required_fields,
+		optional_fields,
+		stall_count = Qnil,
+		retry_count = Qnil;
+	bool bEnable;
+	unsigned char ucMaxPacketLength,
+		ucRetryCount = 0;
+	unsigned long ulRequiredFields,
+		ulOptionalFields;
+	unsigned short usStallCount = 0;
+	bool rval;
+
+	rb_scan_args( argc, argv, "42", &enabled, &max_packet_length, &required_fields,
+		&optional_fields, &stall_count, &retry_count );
+
+	bEnable = RTEST( enabled );
+	ucMaxPacketLength = NUM2CHR( max_packet_length );
+	ulRequiredFields = NUM2ULONG( required_fields );
+	ulOptionalFields = NUM2ULONG( optional_fields );
+
+	if ( RTEST(stall_count) ) {
+		usStallCount = NUM2USHORT( stall_count );
+	}
+	if ( RTEST(retry_count) ) {
+		ucRetryCount = NUM2CHR( retry_count );
+	}
+
+	rant_log( "warn", "Configuring advanced burst: enable = %d, maxpacketlength = %d",
+		bEnable, ucMaxPacketLength );
+	rval = ANT_ConfigureAdvancedBurst_ext( bEnable, ucMaxPacketLength, ulRequiredFields,
+		ulOptionalFields, usStallCount, ucRetryCount );
+
+	return rval ? Qtrue : Qfalse;
+}
+
+
 // Buffer for response data.
 // static UCHAR pucResponseBuffer[ MESG_RESPONSE_EVENT_SIZE ];
 static UCHAR pucResponseBuffer[ MESG_MAX_SIZE_VALUE ];
@@ -510,7 +569,7 @@ rant_s_on_response( int argc, VALUE *argv, VALUE module )
  *
  */
 static VALUE
-rant_s_request_capabilities( VALUE module )
+rant_s_request_capabilities( VALUE _module )
 {
 	bool rval = ANT_RequestMessage( 0, MESG_CAPABILITIES_ID );
 	return rval ? Qtrue : Qfalse;
@@ -527,7 +586,7 @@ rant_s_request_capabilities( VALUE module )
  *
  */
 static VALUE
-rant_s_request_serial_num( VALUE module )
+rant_s_request_serial_num( VALUE _module )
 {
 	bool rval = ANT_RequestMessage( 0, MESG_GET_SERIAL_NUM_ID );
 	return rval ? Qtrue : Qfalse;
@@ -544,13 +603,30 @@ rant_s_request_serial_num( VALUE module )
  *
  */
 static VALUE
-rant_s_request_version( VALUE module )
+rant_s_request_version( VALUE _module )
 {
 	bool rval = ANT_RequestMessage( 0, MESG_VERSION_ID );
 	return rval ? Qtrue : Qfalse;
 }
 
 
+/*
+ * call-seq:
+ *    Ant.request_advanced_burst_capabilities
+ *
+ * Request the current device's advanced burst capabilities. The result will
+ * be delivered via a callback to the #on_version response callback, which by
+ * default extracts it and stores it at Ant.advanced_burst_capabilities.
+ *
+ */
+static VALUE
+rant_s_request_advanced_burst_capabilities( VALUE _module )
+{
+	bool rval = ANT_RequestMessage( 0, MESG_CONFIG_ADV_BURST_ID );
+	return rval ? Qtrue : Qfalse;
+}
+
+
 /*
  * call-seq:
  *    Ant.log_directory = "path/to/log/dir"
@@ -606,6 +682,8 @@ Init_ant_ext()
 
 	rb_define_singleton_method( rant_mAnt, "use_extended_messages=",
 		rant_s_use_extended_messages_eq, 1 );
+	rb_define_singleton_method( rant_mAnt, "configure_advanced_burst",
+		rant_s_configure_advanced_burst, -1 );
 
 	rb_define_singleton_method( rant_mAnt, "on_response", rant_s_on_response, -1 );
 	// EXPORT void ANT_UnassignAllResponseFunctions(); //Unassigns all response functions
@@ -613,6 +691,8 @@ Init_ant_ext()
 	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, "request_advanced_burst_capabilities",
+		rant_s_request_advanced_burst_capabilities, 0 );
 
 	rb_define_singleton_method( rant_mAnt, "log_directory=", rant_s_log_directory_eq, 1 );
 

data/ext/ant_ext/channel.c

@@ -9,6 +9,9 @@
 
 #include "ant_ext.h"
 
+#define DEFAULT_ADV_PACKETS 3
+#define ADVANCED_BURST_TIMEOUT 5
+
 VALUE rant_cAntChannel;
 
 VALUE rant_mAntDataUtilities;
@@ -300,8 +303,16 @@ rant_channel_set_channel_rf_freq( VALUE self, VALUE frequency )
 }
 
 
+/*
+ * call-seq:
+ *    channel.set_frequency_agility( freq1, freq2, freq3 )
+ *
+ * Set the frequencies to use in frequency agility (integers between 0 and 124). These values
+ * use the same convention as the +rf_frequency+ setting; i.e., they're offsets from 2400 MHz.
+ *
+ */
 static VALUE
-rant_channet_set_frequency_agility( VALUE self, VALUE freq1, VALUE freq2, VALUE freq3 )
+rant_channel_set_frequency_agility( VALUE self, VALUE freq1, VALUE freq2, VALUE freq3 )
 {
 	rant_channel_t *ptr = rant_get_channel( self );
 	unsigned char ucFreq1 = NUM2CHR( freq1 ),
@@ -582,6 +593,61 @@ rant_channel_send_broadcast_data( VALUE self, VALUE data )
 }
 
 
+/*
+ * call-seq:
+ *    channel.send_advanced_transfer( data, packets_per_message=3 )
+ *
+ * Send the given +data+ as one or more advanced burst packets. The +packets_per_message+
+ * may be set to a value between 1 and 3 to control how many 8-byte packets are send with
+ * each message.
+ *
+ */
+static VALUE
+rant_channel_send_advanced_transfer( int argc, VALUE *argv, VALUE self )
+{
+#ifdef HAVE_ANT_SENDADVANCEDBURST
+	rant_channel_t *ptr = rant_get_channel( self );
+	VALUE data = Qnil, packets = Qnil;
+	unsigned char *data_s;
+	long data_len;
+	unsigned short usNumDataPackets, remainingBytes;
+	unsigned char ucStdPcktsPerSerialMsg = DEFAULT_ADV_PACKETS;
+
+	rb_scan_args( argc, argv, "11", &data, &packets );
+	data_len = RSTRING_LEN( data );
+	usNumDataPackets = data_len / 8;
+	remainingBytes = data_len % 8;
+	if ( RTEST(packets) ) {
+		ucStdPcktsPerSerialMsg = NUM2CHR(packets);
+	}
+
+	data_s = ALLOC_N( unsigned char, data_len );
+	strncpy( (char *)data_s, StringValuePtr(data), data_len );
+
+	// Pad it to 8-byte alignment
+	if ( remainingBytes ) {
+		int pad_bytes = (8 - remainingBytes);
+		REALLOC_N( data_s, unsigned char, data_len + pad_bytes );
+		memset( data_s + data_len, 0, pad_bytes );
+
+		usNumDataPackets += 1;
+	}
+
+	rant_log_obj( self, "warn", "Sending advanced burst packets (%d-byte messages): %s",
+		ucStdPcktsPerSerialMsg * 8, data_s );
+	if ( !ANT_SendAdvancedBurst_RTO(ptr->channel_num, data_s, usNumDataPackets,
+		ucStdPcktsPerSerialMsg, ADVANCED_BURST_TIMEOUT) )
+	{
+		rant_log_obj( self, "error", "failed to send advanced burst transfer." );
+	}
+
+	return Qtrue;
+#else
+	rb_notimplement();
+#endif
+}
+
+
 void
 init_ant_channel()
 {
@@ -621,7 +687,7 @@ init_ant_channel()
 	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, "set_frequency_agility", rant_channet_set_frequency_agility, 3 );
+	rb_define_method( rant_cAntChannel, "set_frequency_agility", rant_channel_set_frequency_agility, 3 );
 
 	rb_define_method( rant_cAntChannel, "open", rant_channel_open, -1 );
 	rb_define_method( rant_cAntChannel, "close", rant_channel_close, -1 );
@@ -630,6 +696,7 @@ init_ant_channel()
 	rb_define_method( rant_cAntChannel, "send_burst_transfer", rant_channel_send_burst_transfer, 1 );
 	rb_define_method( rant_cAntChannel, "send_acknowledged_data", rant_channel_send_acknowledged_data, 1 );
 	rb_define_method( rant_cAntChannel, "send_broadcast_data", rant_channel_send_broadcast_data, 1 );
+	rb_define_method( rant_cAntChannel, "send_advanced_transfer", rant_channel_send_advanced_transfer, -1 );
 
 	rb_define_method( rant_cAntChannel, "on_event", rant_channel_on_event, -1 );
 

data/ext/ant_ext/extconf.rb

@@ -18,6 +18,15 @@ have_func( 'ANT_IsInitialized', 'libant.h' )
 have_func( 'ANT_LibVersion', 'libant.h' )
 have_func( 'ANT_GetDeviceSerialNumber', 'libant.h' )
 
+# Look for a custom advanced burst function, as the official SDK has it in the
+# header but doesn't actually implement it.
+have_func( 'ANT_SendAdvancedBurst', 'libant.h' )
+
+# Ref: https://bugs.ruby-lang.org/issues/17865
+$CPPFLAGS << " -Wno-compound-token-split-by-macro "
+
+$CFLAGS << " -g "
+
 create_header()
 create_makefile( 'ant_ext' )
 

data/lib/ant/response_callbacks.rb

@@ -9,7 +9,8 @@ require 'ant/bitvector'
 
 # A module that handles response callbacks by logging them.
 module Ant::ResponseCallbacks
-	extend Loggability
+	extend Loggability,
+		Ant::DataUtilities
 
 	# Loggability API -- send logs to the Ant logger
 	log_to :ant
@@ -49,9 +50,10 @@ module Ant::ResponseCallbacks
 		Ant::Message::MESG_RADIO_TX_POWER_ID            => :on_radio_tx_power,
 
 		Ant::Message::MESG_AUTO_FREQ_CONFIG_ID          => :on_auto_freq_config,
+		Ant::Message::MESG_CONFIG_ADV_BURST_ID          => :on_config_adv_burst_id,
 
 		# :TODO: There are many other MESG_ constants, but I think most or all of
-		# them are for the serial protocol.
+		# them are only used for the serial protocol.
 	}
 
 
@@ -236,6 +238,54 @@ module Ant::ResponseCallbacks
 	end
 
 
+	### Handle callback when requesting advanced burst configuration.
+	def on_config_adv_burst_id( type, data )
+		self.log.debug "Advanced burst config/capabilities: 0x%02x: %p" % [ type, data ]
+
+		# Advanced burst capabilities
+		if type == 0
+			max_packet_length, features = data.unpack( 'CV' )
+			features = Ant::BitVector.new( features )
+
+			caps = {
+				max_packet_length: max_packet_length,
+				frequency_hopping: features.on?( Ant::ADV_BURST_CONFIG_FREQ_HOP )
+			}
+
+			self.log.info "Advanced burst capabilities: %p" % [ caps ]
+			Ant.instance_variable_set( :@advanced_burst_capabilities, caps );
+
+		# Advanced burst current configuration
+		elsif type == 1
+			enabled, max_packet_length, required, optional, stall_count, retry_count =
+				data.unpack( 'CCVVvC' )
+			required = Ant::BitVector.new( required )
+			optional = Ant::BitVector.new( optional )
+
+			required_features = []
+			required_features << :frequency_hopping if required.on?( Ant::ADV_BURST_CONFIG_FREQ_HOP )
+
+			optional_features = []
+			optional_features << :frequency_hopping if optional.on?( Ant::ADV_BURST_CONFIG_FREQ_HOP )
+
+			config = {
+				enabled: enabled == 1,
+				max_packet_length: max_packet_length,
+				required_features: required_features,
+				optional_features: optional_features,
+				stall_count: stall_count,
+				retry_count_extension: retry_count
+			}
+
+			self.log.info "Advanced burst configuration: %p" % [ config ]
+			Ant.instance_variable_set( :@advanced_burst_config, config );
+
+		else
+			self.log.warn "Unknown advanced burst response type %p." % [ type ]
+		end
+	end
+
+
 	### Handle capabilities response event.
 	def on_capabilities( channel_num, data )
 		std_opts  = Ant::BitVector.new( data.bytes[2] )

data/lib/ant.rb

@@ -12,7 +12,7 @@ module Ant
 	extend Loggability
 
 	# Package version
-	VERSION = '0.3.0'
+	VERSION = '0.4.0'
 
 	# A Range for matching valid ANT device numbers
 	VALID_DEVICE_NUMBERS = ( 0...65535 ).freeze
@@ -26,6 +26,14 @@ module Ant
 	# The valid offsets for the "RF Frequency" setting; this is an offset from 2400Hz.
 	VALID_RF_FREQUENCIES = ( 0...124 ).freeze
 
+	# Default options for advanced burst when it's enabled.
+	DEFAULT_ADVANCED_OPTIONS = {
+		max_packet_length: 24,
+		frequency_hopping: :optional,
+		stall_count: 0,
+		retry_count: 0
+	}
+
 
 	# Loggability API -- set up a logger for the library
 	log_as :ant
@@ -143,5 +151,55 @@ module Ant
 		return offset
 	end
 
+
+	### Enable advanced burst mode with the given +options+.
+	def self::enable_advanced_burst( **options )
+		options = DEFAULT_ADVANCED_OPTIONS.merge( options )
+
+		max_packet_length = self.convert_max_packet_length( options[:max_packet_length] )
+
+		required_fields = self.make_required_fields_config( options )
+		optional_fields = self.make_optional_fields_config( options )
+
+		stall_count = options[:stall_count]
+		retry_count = options[:retry_count]
+
+		self.configure_advanced_burst( true, max_packet_length, required_fields, optional_fields,
+			stall_count, retry_count )
+	end
+
+
+	### Validate that the specified +length+ (in bytes) is a valid setting as an
+	### advanced burst max packet length configuration value. Returns the equivalent
+	### configuration value.
+	def self::convert_max_packet_length( length )
+		case length
+		when 8 then return 0x01
+		when 16 then return 0x02
+		when 24 then return 0x03
+		else
+			raise ArgumentError,
+				"invalid max packet length; expected 8, 16, or 24, got %p" % [ length ]
+		end
+	end
+
+
+	### Given an options hash, return a configuration value for required fields.
+	def self::make_required_fields_config( **options )
+		value = 0
+		value |= 0x01 if options[:frequency_hopping] == :required
+
+		return value
+	end
+
+
+	### Given an options hash, return a configuration value for optional fields.
+	def self::make_optional_fields_config( **options )
+		value = 0
+		value |= 0x01 if options[:frequency_hopping] == :optional
+
+		return value
+	end
+
 end # module Ant
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ant-wireless
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Michael Granger
@@ -34,7 +34,7 @@ cert_chain:
   MCh97sQ/Z/MOusb5+QddBmB+k8EicXyGNl4b5L4XpL7fIQu+Y96TB3JEJlShxFD9
   k9FjI4d9EP54gS/4
   -----END CERTIFICATE-----
-date: 2021-10-11 00:00:00.000000000 Z
+date: 2021-11-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler