fit4ruby 0.0.4 → 0.0.5

data/lib/fit4ruby/FitMessageIdMapper.rb

@@ -12,16 +12,25 @@
 
 module Fit4Ruby
 
+  # The FIT file maps GlobalFitMessage numbers to local numbers. Due to
+  # restrictions in the format, only 16 local messages can be active at any
+  # point in the file. If a GlobalFitMessage is needed that is currently not
+  # mapped, a new entry is generated and the least recently used message is
+  # evicted. The FitMessageIdMapper is the objects that stores those 16 active
+  # entries and can map global to local message numbers.
   class FitMessageIdMapper
 
-    class Entry < Struct.new(:global_id, :last_use)
+    # The entry in the mapper.
+    class Entry < Struct.new(:global_message, :last_use)
     end
 
     def initialize
       @entries = Array.new(16, nil)
     end
 
-    def add_global(id)
+    # Add a new GlobalFitMessage to the mapper and return the local message
+    # number.
+    def add_global(message)
       unless (slot = @entries.index { |e| e.nil? })
         # No more free slots. We have to find the least recently used one.
         slot = 0
@@ -31,14 +40,16 @@ module Fit4Ruby
           end
         end
       end
-      @entries[slot] = Entry.new(id, Time.now)
+      @entries[slot] = Entry.new(message, Time.now)
 
       slot
     end
 
-    def get_local(id)
+    # Get the local message number for a given GlobalFitMessage. If there is
+    # no message number, nil is returned.
+    def get_local(message)
       0.upto(15) do |i|
-        if (entry = @entries[i]) && entry.global_id == id
+        if (entry = @entries[i]) && entry.global_message == message
           entry.last_use = Time.now
           return i
         end

data/lib/fit4ruby/FitMessageRecord.rb

@@ -3,7 +3,7 @@
 #
 # = FitMessageRecord.rb -- Fit4Ruby - FIT file processing library for Ruby
 #
-# Copyright (c) 2014 by Chris Schlaeger <cs@taskjuggler.org>
+# Copyright (c) 2014, 2015 by Chris Schlaeger <cs@taskjuggler.org>
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of version 2 of the GNU General Public License as
@@ -13,9 +13,16 @@
 require 'bindata'
 require 'fit4ruby/Log'
 require 'fit4ruby/GlobalFitMessage'
+require 'fit4ruby/FitFileEntity'
 
 module Fit4Ruby
 
+  # The FitMessageRecord models a part of the FIT file that contains the
+  # FIT message records. Each message record has a number, a local type and a
+  # set of data fields. The content of a FitMessageRecord is defined by the
+  # FitDefinition. This class is only used for reading data from a FIT file.
+  # For writing FIT message records, the class FitDataRecord and its
+  # decendents are used.
   class FitMessageRecord
 
     attr_reader :global_message_number, :name, :message_record
@@ -33,35 +40,108 @@ module Fit4Ruby
       @message_record = produce(definition)
     end
 
-    def read(io, activity, filter = nil, fields_dump = nil)
+    def read(io, entity, filter = nil, fields_dump = nil)
       @message_record.read(io)
 
-      obj = @name == 'activity' ? activity : activity.new_fit_data_record(@name)
+      if @name == 'file_id'
+        unless (entity_type = @message_record['type'].snapshot)
+          Log.fatal "Corrupted FIT file: file_id record has no type definition"
+        end
+        entity.set_type(entity_type)
+      end
+      obj = entity.new_fit_data_record(@name)
+
+      # It's important to ensure that alternative fields processed after the
+      # regular fields so that the decision field is already set.
+      sorted_fields = @definition.fields.sort do |f1, f2|
+        f1alt = is_alt_field?(f1)
+        f2alt = is_alt_field?(f2)
+        f1alt == f2alt ?
+          f1.field_definition_number.snapshot <=>
+          f2.field_definition_number.snapshot :
+          f1alt ? 1 : -1
+      end
 
-      @definition.fields.each do |field|
+      sorted_fields.each do |field|
         value = @message_record[field.name].snapshot
-        obj.set(field.name, field.to_machine(value)) if obj
+        # Strings are null byte terminated. There may be more bytes in the
+        # file, but we have to discard all bytes from the first null byte
+        # onwards.
+        if value.is_a?(String) && (null_byte = value.index("\0"))
+          value = value[0..(null_byte - 1)]
+        end
+
+        field_name, field_def = get_field_name_and_global_def(field, obj)
+        obj.set(field_name, field.to_machine(value)) if obj
+
         if filter && fields_dump &&
            (filter.field_names.nil? ||
-            filter.field_names.include?(field.name)) &&
+            filter.field_names.include?(field_name)) &&
            (value != field.undefined_value || !filter.ignore_undef)
-          fields_dump[field] = value
+          fields_dump << [ field.type(true), field_name,
+                           (field_def ? field_def : field).to_s(value) ]
         end
       end
     end
 
     private
 
+    def is_alt_field?(field)
+      return false unless @gfm
+
+      field_def_number = field.field_definition_number.snapshot
+      field_def = @gfm.fields_by_number[field_def_number]
+      field_def.is_a?(GlobalFitMessage::AltField)
+    end
+
+    def get_field_name_and_global_def(field, obj)
+      # If we don't have a corresponding GlobalFitMessage definition, we can't
+      # tell if the field is an alternative or not. We don't treat it as such.
+      return [ field.name, nil ] unless @gfm
+
+      field_def_number = field.field_definition_number.snapshot
+      # Get the corresponding GlobalFitMessage field definition.
+      field_def = @gfm.fields_by_number[field_def_number]
+      # If it's not an AltField, we just use the already given name.
+      unless field_def.is_a?(GlobalFitMessage::AltField)
+        return [ field.name, nil ]
+      end
+
+      # We have an AltField. Now we need to find the selection field and its
+      # value.
+      ref_field = field_def.ref_field
+      ref_value = obj ? obj.get(ref_field) : :default
+
+      # Based on that value, we select the Field of the AltField.
+      selected_field = field_def.fields[ref_value] ||
+                       field_def.fields[:default]
+      Log.fatal "The value #{ref_value} of field #{ref_field} does not match " +
+                "any selection of alternative field #{field_def_number} in " +
+                "GlobalFitMessage #{@gfm.name}" unless selected_field
+
+      [ selected_field.name, selected_field ]
+    end
+
     def produce(definition)
       fields = []
       definition.fields.each do |field|
-        fields << [ field.type, field.name ]
+        field_def = [ field.type, field.name ]
+        if field.type == 'string'
+          # Strings need special handling. We need to also include the length
+          # of the String.
+          field_def << { :read_length => field.total_bytes }
+        elsif field.is_array?
+          field_def = [ :array, field.name,
+                        { :type => field.type.intern,
+                          :initial_length => field.total_bytes /
+                                             field.base_type_bytes } ]
+        end
+        fields << field_def
       end
 
       BinData::Struct.new(:endian => definition.endian, :fields => fields)
     end
 
-
   end
 
 end

data/lib/fit4ruby/FitRecord.rb

@@ -3,7 +3,7 @@
 #
 # = FitRecord.rb -- Fit4Ruby - FIT file processing library for Ruby
 #
-# Copyright (c) 2014 by Chris Schlaeger <cs@taskjuggler.org>
+# Copyright (c) 2014, 2015 by Chris Schlaeger <cs@taskjuggler.org>
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of version 2 of the GNU General Public License as
@@ -15,10 +15,14 @@ require 'fit4ruby/FitRecordHeader'
 require 'fit4ruby/FitDefinition'
 require 'fit4ruby/FitMessageRecord'
 require 'fit4ruby/FitFilter'
-require 'fit4ruby/Activity'
+require 'fit4ruby/FitFileEntity'
 
 module Fit4Ruby
 
+  # The FitRecord is a basic building block of a FIT file. It can either
+  # contain a definition of a message record or an actual message record with
+  # FIT data. A FIT record always starts with a header that describes what
+  # kind of record this is.
   class FitRecord
 
     def initialize(definitions)
@@ -26,13 +30,13 @@ module Fit4Ruby
       @name = @number = @fields = nil
     end
 
-    def read(io, activity, filter, record_counters)
+    def read(io, entity, filter, record_counters)
       header = FitRecordHeader.read(io)
 
-      if header.normal?
+      if !header.compressed?
         # process normal headers
         local_message_type = header.local_message_type.snapshot
-        if header.message_type == 1
+        if header.message_type.snapshot == 1
           # process definition message
           definition = FitDefinition.read(io)
           @definitions[local_message_type] = FitMessageRecord.new(definition)
@@ -45,15 +49,19 @@ module Fit4Ruby
           if filter
             @number = @definitions[local_message_type].global_message_number
             index = (record_counters[@number] += 1)
+
+            # Check if we have a filter defined to collect raw dumps of the
+            # data in the message records. The dump is collected in @fields
+            # for later output.
             if (filter.record_numbers.nil? ||
                 filter.record_numbers.include?(@number)) &&
                (filter.record_indexes.nil? ||
                 filter.record_indexes.include?(index))
               @name = definition.name
-              @fields = {}
+              @fields = []
             end
           end
-          definition.read(io, activity, filter, @fields)
+          definition.read(io, entity, filter, @fields)
         end
       else
         # process compressed timestamp header
@@ -67,10 +75,13 @@ module Fit4Ruby
     def dump
       return unless @fields
 
-      puts "Message #{@number}: #{@name}" unless @fields.empty?
-      @fields.each do |field, value|
-        puts " [#{"%-7s" % field.type(true)}] #{field.name}: " +
-             "#{field.to_s(value)}"
+      begin
+        puts "Message #{@number}: #{@name}" unless @fields.empty?
+        @fields.each do |type, name, value|
+          puts " [#{"%-7s" % type}] #{name}: " + "#{value}"
+        end
+      rescue Errno::EPIPE
+        # Avoid ugly error message when aborting a less/more pipe.
       end
     end
 

data/lib/fit4ruby/FitRecordHeader.rb

@@ -27,11 +27,11 @@ module Fit4Ruby
     bit5 :time_offset, :onlyif => :compressed?
 
     def normal?
-      normal == 0
+      normal.snapshot == 0
     end
 
     def compressed?
-      normal == 1
+      normal.snapshot == 1
     end
 
   end

data/lib/fit4ruby/GlobalFitDictionaries.rb

@@ -26,6 +26,12 @@ module Fit4Ruby
     entry 6, 'walking'
     entry 254, 'all'
 
+    dict 'ant_network'
+    entry 0, 'public'
+    entry 1, 'antplus'
+    entry 2, 'antfs'
+    entry 3, 'private'
+
     dict 'battery_status'
     entry 1, 'new'
     entry 2, 'good'
@@ -53,6 +59,10 @@ module Fit4Ruby
     entry 123, 'bike_speed'
     entry 124, 'stride_speed_distance'
 
+    dict 'display_measure'
+    entry 0, 'metric'
+    entry 1, 'statute'
+
     dict 'event'
     entry 0, 'timer'
     entry 3, 'workout'
@@ -86,6 +96,7 @@ module Fit4Ruby
     entry 36, 'calibration'
     entry 37, 'vo2max' # guess
     entry 38, 'recovery_time' # guess (in minutes)
+    entry 39, 'recovery_info' # guess (in minutes, < 24 good, > 24h poor)
     entry 42, 'front_gear_change'
     entry 43, 'rear_gear_change'
 
@@ -118,6 +129,23 @@ module Fit4Ruby
     entry 28, 'monitoring_daily'
     entry 32, 'monitoring_b'
 
+    dict 'garmin_product'
+    entry 8, 'hrm_run_single_byte_product_id'
+    entry 1551, 'fenix'
+    entry 1623, 'fr620'
+    entry 1632, 'fr220'
+    entry 1752, 'hrm_run'
+    entry 1765, 'fr920xt'
+    entry 1928, 'fr620_japan'
+    entry 1929, 'fr620_china'
+    entry 1930, 'fr220_japan'
+    entry 1931, 'fr220_china'
+    entry 1967, 'fenix2'
+    entry 10007, 'sdm4'
+    entry 20119, 'training_center'
+    entry 65532, 'android_antplus_plugin'
+    entry 65534, 'connect'
+
     dict 'gender'
     entry 0, 'female'
     entry 1, 'male'
@@ -139,8 +167,12 @@ module Fit4Ruby
     entry 7, 'session_end'
     entry 8, 'fitness_equipment'
 
+    dict 'left_right_balance_100'
+    entry 0x3FFF, 'mask'
+    entry 0x8000, 'right'
+
     dict 'manufacturer'
-    entry 1, 'Garmin'
+    entry 1, 'garmin'
     entry 2, 'garmin_fr405_antfs'
     entry 3, 'zephyr'
     entry 4, 'dayton'
@@ -232,6 +264,14 @@ module Fit4Ruby
     entry 2, 'auto_multi_sport'
     entry 3, 'fitness_equipment'
 
+    dict 'source_type'
+    entry 0, 'ant'
+    entry 1, 'antplus'
+    entry 2, 'bluetooth'
+    entry 3, 'bluetooth_low_enegery'
+    entry 4, 'wifi'
+    entry 5, 'local'
+
     dict 'sport'
     entry 0, 'generic'
     entry 1, 'running'
@@ -255,6 +295,15 @@ module Fit4Ruby
     entry 19, 'paddling'
     entry 254, 'all'
 
+    dict 'swim_stroke'
+    entry 0, 'freestyle'
+    entry 1, 'backstroke'
+    entry 2, 'breaststrike'
+    entry 3, 'butterfly'
+    entry 4, 'drill'
+    entry 5, 'mixed'
+    entry 6, 'im'
+
     dict 'sub_sport'
     entry 0, 'generic'
     entry 1, 'treadmill'
@@ -285,17 +334,6 @@ module Fit4Ruby
     entry 26, 'cardio_training'
     entry 254, 'all'
 
-    dict 'product'
-    entry 8, 'hrm_run_single_byte_product_id'
-    entry 1623, 'fr620'
-    entry 1632, 'fr220'
-    entry 1752, 'hrm_run'
-    entry 1928, 'fr620_japan'
-    entry 1929, 'fr620_china'
-    entry 1930, 'fr220_japan'
-    entry 1931 , 'fr220_china'
-    entry 10007, 'sdm4'
-
   end
 
 end

data/lib/fit4ruby/GlobalFitMessage.rb

@@ -16,10 +16,16 @@ require 'fit4ruby/FitDefinitionField'
 
 module Fit4Ruby
 
+  # The GlobalFitMessage stores an abstract description of a particular
+  # FitMessage. It holds information like the name, the global ID number and
+  # the data fields of the message.
   class GlobalFitMessage
 
-    attr_reader :name, :number, :fields
+    attr_reader :name, :number, :fields_by_name, :fields_by_number
 
+    # The Field objects describe the name, type and optional attributes of a
+    # FitMessage definition field. It also provides methods to convert field
+    # values into various formats.
     class Field
 
       include Converters
@@ -131,24 +137,128 @@ module Fit4Ruby
 
     end
 
+    # A GlobalFitMessage may have Field entries that are dependent on the
+    # value of another Field. These alternative fields all depend on the value
+    # of a specific other Field of the GlobalFitMessage and their presense is
+    # mutually exclusive. An AltField object models such a group of Field
+    # objects.
+    class AltField
+
+      attr_reader :fields, :ref_field
+
+      # Create a new AltField object.
+      # @param message [GlobalFitMessage] reference to the GlobalFitMessage
+      #        this field belongs to.
+      # @param ref_field [String] The name of the field that is used to select
+      #        the alternative.
+      def initialize(message, ref_field, &block)
+        @message = message
+        @ref_field = ref_field
+        @fields = {}
+
+        instance_eval(&block) if block_given?
+      end
+
+      def field(ref_value, type, name, opts = {})
+        field = Field.new(type, name, opts)
+        if ref_value.respond_to?('each')
+          ref_value.each do |rv|
+            @fields[rv] = field
+          end
+        else
+          @fields[ref_value] = field
+        end
+        @message.register_field_by_name(field, name)
+      end
+
+      # Select the alternative field based on the actual field values of the
+      # FitMessageRecord.
+      def select(field_values_by_name)
+        unless (value = field_values_by_name[@ref_field])
+          Log.fatal "The selection field #{@ref_field} for the alternative " +
+                    "field is undefined in global message #{@message.name}: " +
+                    field_values_by_name.inspect
+        end
+        @fields.each do |ref_value, field|
+          return field if ref_value == value
+        end
+        return @fields[:default] if @fields[:default]
+
+        Log.fatal "The selector value #{value} for the alternative field " +
+                  "is not supported in global message #{@message.name}."
+      end
+
+    end
+
+    # Create a new GlobalFitMessage definition.
+    # @param name [String] name of the FIT message
+    # @param number [Fixnum] global message number
     def initialize(name, number)
       @name = name
       @number = number
-      @fields = {}
+      # Field names must be unique. A name always matches a single Field.
+      @fields_by_name = {}
+      # Field numbers are not unique. A group of alternative fields shares the
+      # same number and is stored as an AltField. Otherwise as Field.
+      @fields_by_number = {}
     end
 
+    # Two GlobalFitMessage objects are considered equal if they have the same
+    # number, name and list of named fields.
+    def ==(m)
+      @number == m.number && @name == m.name &&
+        @fields_by_name.keys.sort == m.fields_by_name.keys.sort
+    end
+
+    # Define a new Field for this message definition.
     def field(number, type, name, opts = {})
-      if @fields.include?(number)
+      field = Field.new(type, name, opts)
+      register_field_by_name(field, name)
+      register_field_by_number(field, number)
+    end
+
+    # Define a new set of Field alternatives for this message definition.
+    def alt_field(number, ref_field, &block)
+      unless @fields_by_name.include?(ref_field)
+        raise "Unknown ref_field: #{ref_field}"
+      end
+
+      field = AltField.new(self, ref_field, &block)
+      register_field_by_number(field, number)
+    end
+
+    def register_field_by_name(field, name)
+      if @fields_by_name.include?(name)
+        raise "Field '#{name}' has already been defined"
+      end
+
+      @fields_by_name[name] = field
+    end
+
+    def register_field_by_number(field, number)
+      if @fields_by_name.include?(number)
         raise "Field #{number} has already been defined"
       end
-      @fields[number] = Field.new(type, name, opts)
+
+      @fields_by_number[number] = field
     end
 
-    def find_by_name(field_name)
-      @fields.values.find { |f| f.name == field_name }
+    def construct(field_values_by_name)
+      gfm = GlobalFitMessage.new(@name, @number)
+
+      @fields_by_number.each do |number, field|
+        if field.is_a?(AltField)
+          # For alternative fields, we need to look at the value of the
+          # selector field and pick the corresponding Field.
+          field = field.select(field_values_by_name)
+        end
+        gfm.field(number, field.type, field.name, field.opts)
+      end
+
+      gfm
     end
 
-    def write(io, local_message_type)
+    def write(io, local_message_type, global_fit_message = self)
       header = FitRecordHeader.new
       header.normal = 0
       header.message_type = 1
@@ -157,7 +267,7 @@ module Fit4Ruby
 
       definition = FitDefinition.new
       definition.global_message_number = @number
-      definition.setup(self)
+      definition.setup(global_fit_message)
       definition.write(io)
     end
 
@@ -212,6 +322,13 @@ module Fit4Ruby
       @current_message.field(number, type, name, opts)
     end
 
+    def alt_field(number, ref_field, &block)
+      unless @current_message
+        raise "You must define a message first"
+      end
+      @current_message.alt_field(number, ref_field, &block)
+    end
+
     def [](number)
       @messages[number]
     end