live_f1-core 0.0.1

data/lib/live_f1/packet/sys/notice.rb

@@ -0,0 +1,10 @@
+module LiveF1
+  class Packet
+    class Sys
+      class Notice < Sys
+        include Packet::Type::Long
+        include Packet::Decryptable
+      end
+    end
+  end
+end

data/lib/live_f1/packet/sys/reset.rb

@@ -0,0 +1,9 @@
+module LiveF1
+  class Packet
+    class Sys
+      class Reset < Sys
+        include Packet::Type::Special
+      end
+    end
+  end
+end

data/lib/live_f1/packet/sys/session_start.rb

@@ -0,0 +1,25 @@
+module LiveF1
+  class Packet
+    class Sys
+      # A SessionStart packet is the first packet emitted for a session.
+      class SessionStart < Sys
+        include Packet::Type::Short
+
+        # The formula1.com unique identifier for this session
+        def session_number
+          data[1..-1].to_i
+        end
+
+        # The type of event this is (practise, qualifying or race) as defined
+        # by the constants in Event::Type
+        def event_type
+          header.data & 0b0111
+        end
+
+        def inspect
+          "Event #{session_number} Start (#{Event::Type.name_for event_type})"
+        end
+      end
+    end
+  end
+end

data/lib/live_f1/packet/sys/speed.rb

@@ -0,0 +1,29 @@
+module LiveF1
+  class Packet
+    class Sys
+      class Speed < Sys
+        include Packet::Type::Long
+        include Packet::Decryptable
+
+        def trap
+          data.bytes.first
+        end
+
+        def speeds
+          data[1..-1].split(/\s+/).each_slice(2).map { |d,s| "%s: %d" % [d,s] }.join(", ")
+        end
+
+        def to_s
+          out = case trap
+          when 1..4
+            speeds
+          else
+            data[1..-1]
+          end
+
+          "[%d] %s" % [trap, out]
+        end
+      end
+    end
+  end
+end

data/lib/live_f1/packet/sys/timestamp.rb

@@ -0,0 +1,23 @@
+module LiveF1
+  class Packet
+    class Sys
+      # Individual packets don't include any timestamp data to indicate when
+      # they happened. However, at selected (but irregular) intervals Timestamp
+      # packets are emitted containing the number of seconds since the start of
+      # the session.
+      class Timestamp < Sys
+        include Packet::Type::Timestamp
+        include Packet::Decryptable
+
+        # The number of seconds since the start of the session.
+        def number
+					data.unpack("v").first
+        end
+
+        def to_s
+          number
+        end
+      end
+    end
+  end
+end

data/lib/live_f1/packet/sys/track_status.rb

@@ -0,0 +1,18 @@
+module LiveF1
+  class Packet
+    class Sys
+      class TrackStatus < Sys
+        include Packet::Type::Short
+        include Packet::Decryptable
+        
+        def status
+          data.to_i
+        end
+        
+        def to_s
+          Event::TrackStatus.name_for(status)
+        end
+      end
+    end
+  end
+end

data/lib/live_f1/packet/sys/weather.rb

@@ -0,0 +1,33 @@
+require 'live_f1/enum'
+
+module LiveF1
+  class Packet
+    class Sys
+      class Weather < Sys
+        module Metric
+          extend LiveF1::Enum
+        	SESSION_CLOCK     = 0
+        	TRACK_TEMPERATURE = 1
+        	AIR_TEMPERATURE   = 2
+        	WET_TRACK         = 3
+        	WIND_SPEED        = 4
+        	HUMIDITY          = 5
+        	AIR_PRESSURE      = 6
+        	WIND_DIRECTION    = 7
+        end
+        include Metric
+
+        include Packet::Type::Short
+        include Packet::Decryptable
+
+        def to_s
+          "%-18s - %s" % [Metric.name_for(metric), data]
+        end
+
+        def metric
+          header.data & 0b0111
+        end
+      end
+    end
+  end
+end

data/lib/live_f1/packet/sys.rb

@@ -0,0 +1,10 @@
+module LiveF1
+  class Packet
+    class Sys < Packet
+    end
+  end
+end
+
+Dir[File.join(File.dirname(__FILE__),'sys','*')].each do |file|
+  require file
+end

data/lib/live_f1/packet.rb

@@ -0,0 +1,129 @@
+require 'live_f1/debug'
+
+module LiveF1
+  # A Packet represents a raw instruction sent from the live timing server to
+  # the live timing applet.
+  #
+  # It is represented in the data stream by a variable-length series of bytes,
+  # always starting with a 2-byte "header" and then a number of other bytes
+  # depending on the specific data being represented.
+  class Packet
+    # There are 4 broad categories of packet, where the only difference is how
+    # we work out how many bytes of data are expected from the stream.
+    #
+    # As described in the Header documentation, the 2 header bytes are split
+    # into information about the packet type and corresponding car, along with
+    # up to 7 bits of payload data.
+    module Type
+      module Short
+        # Short packets use 4 bits of the header data to represent the packet
+        # length. Normally this would mean a maximum length of 15, except if a
+        # short packet says it has a length of 15 it actually has a length of 0
+        def length
+          l = (header.data >> 3)
+          l == 0x0f ? 0 : l
+        end
+
+        def spare_bits
+          3
+        end
+      end
+
+      module Long
+        # Long packets use all 7 bits of the header data to represent the packet
+        # length. This allows for a maximum packet length of 127 bytes.
+        def length
+          header.data
+        end
+
+        def spare_bits
+          0
+        end
+      end
+
+      module Special
+        # Special packets never have any additional data.
+        def length
+          0
+        end
+
+        def spare_bits
+          7
+        end
+      end
+
+      module Timestamp
+        # Timestamp packets always contain 2 bytes of data.
+        def length
+          2
+        end
+
+        def spare_bits
+          0
+        end
+      end
+    end
+
+    attr_reader :source
+    attr_reader :header
+    attr_accessor :data
+
+    alias bytes data
+
+    # First extracts a Header from the given source and then extracts the
+    # packet it represents, based on the given event type.
+    def self.from_source source, event_type
+      header = Header.from_source(source, event_type)
+      packet = header.packet_klass.new source, header
+      data = source.read_bytes(packet.length)
+      packet.data = data
+      packet
+    end
+
+    def initialize source, header
+      @source = source
+      @header = header
+    end
+
+    def to_s
+      data.inspect
+    end
+
+    def spare_bits
+      0
+    end
+
+    # Returns the bits of the header data which aren't used to determine the
+    # packet length
+    def spare_data
+      "%0#{spare_bits}b" % (header.data & (2 ** spare_bits - 1))
+    end
+
+    def inspect
+      if LiveF1.debug
+        "[%7s] %-23s %s" % [spare_data, leader, to_s]
+      else
+        "%-23s %s" % [leader, to_s]
+      end
+    end
+
+    def leader
+      self.class.name.sub(/LiveF1::Packet::/, '')
+    end
+
+    private
+    # Since some classes override +data=+ to deal with encrypted data, here's a
+    # method that can be used in rare cases (e.g. testing) where we need to
+    # bypass that process
+    def set_data new_data
+      @data = new_data
+    end
+  end
+end
+
+
+require_relative 'packet/header'
+require_relative 'packet/decryptable'
+require_relative 'packet/sector_time'
+require_relative 'packet/sys'
+require_relative 'packet/car'

data/lib/live_f1/source/keyframe.rb

@@ -0,0 +1,30 @@
+require 'open-uri'
+
+module LiveF1
+  class Source
+    class Keyframe < Source
+      attr_reader :io, :parent
+
+      def initialize io, parent
+        @io = io
+        @parent = parent
+      end
+
+      def read_bytes num
+        io.read(num) or raise EOFError
+      end
+
+      def session
+        parent.session
+      end
+
+      def session= new_session
+        parent.session = new_session
+      end
+
+      def decryption_key session_number
+        parent.decryption_key(session_number)
+      end
+    end
+  end
+end

data/lib/live_f1/source/live.rb

@@ -0,0 +1,163 @@
+require 'net/http'
+require 'cgi'
+require 'timeout'
+require 'fileutils'
+require 'yaml'
+require_relative 'keyframe'
+
+module LiveF1
+  class Source
+    class Live < Source
+
+      HOST = "80.231.178.249"
+      PORT = 4321
+
+      attr_reader :username, :password
+
+      def initialize username, password
+        @username = username
+        @password = password
+      end
+
+      def read_bytes num
+        begin
+          Timeout.timeout(0.5) do
+            socket.read(num) or raise EOFError
+          end
+        rescue Timeout::Error, Errno::ETIMEDOUT => e
+          log.flush
+          socket.write("\n")
+          socket.flush
+          retry
+        end
+      end
+
+      def keyframe number = nil
+        io = open("http://#{HOST}/#{keyframe_filename(number)}")
+        log.keyframe(number, io.read) if number
+        io.rewind
+        Source::Keyframe.new io, self
+      rescue SocketError
+        raise ConnectionError, "Unable to connect to live timing server #{HOST}"
+      end
+
+      def decryption_key session_number
+        key = open("http://#{HOST}/reg/getkey/#{session_number}.asp?auth=#{auth}").read.to_i(16)
+        raise ConnectionError, "Unable to access session key for session #{session_number}. This could indicate incorrect credentials or an issue with the formula1.com key server" if key.zero?
+        key
+      end
+
+      # Sets the base directory for live data log files to be stored
+      def log_dir= log_directory
+        Log.dir = log_directory
+      end
+
+      def run
+        super do |packet|
+          case packet
+          when LiveF1::Packet::Sys::SessionStart
+            log.start packet.session_number
+            log.key session.decryption_key
+          when LiveF1::Packet::Sys::KeyFrame
+            keyframe(packet.number)
+          end
+
+          log.packet packet
+
+          yield packet
+        end
+      rescue Errno::ECONNRESET
+        log.flush
+        retry
+      rescue Exception
+        log.flush
+        raise
+      end
+
+      def session= new_session
+        super
+      end
+
+      def log
+        LogProxy
+      end
+
+      private
+      def socket
+        @socket ||= TCPSocket.open(HOST, PORT)
+      end
+
+      def auth
+        response = Net::HTTP.post_form URI.parse("http://#{HOST}/reg/login"), {"email" => username, "password" => password}
+        CGI::Cookie.parse(response["Set-Cookie"])["USER"].first
+      end
+
+      def keyframe_filename number
+        "keyframe#{ "_%05d" % number if number}.bin"
+      end
+
+      class LogProxy
+        class << self
+          def start session_number
+            flush
+            @log = Log.new session_number
+          end
+
+          [:key, :packet, :keyframe].each do |m|
+            define_method m do |*args|
+              @log.send(m, *args) if @log
+            end
+          end
+
+          def flush
+            @log.flush if @log
+            @log = nil
+          end
+        end
+      end
+
+      class Log
+        class << self
+          attr_reader :dir
+
+          def dir= log_directory
+            @dir = Pathname.new(log_directory).join(Date.today.strftime("%Y%m%d"))
+            FileUtils.mkdir_p(@dir)
+          end
+
+          def active?
+            !!@dir
+          end
+        end
+
+        def initialize session_number
+          @filename = Log.dir.join("%s.%s.f1" % [session_number, Time.now.strftime("%H%M%S")]) if Log.active?
+          @data = {
+            key: nil,
+            bytes: "",
+            keyframes: {},
+          }
+        end
+
+        def key k
+          @data[:key] = k
+        end
+
+        def packet p
+          @data[:bytes] << p.header.bytes << p.bytes
+        end
+
+        def keyframe n, k
+          @data[:keyframes][n] = k
+        end
+
+        def flush
+          File.open(@filename, "w") { |f| f.write YAML.dump(@data) } if @filename
+        end
+      end
+
+      class ConnectionError < RuntimeError
+      end
+    end
+  end
+end

data/lib/live_f1/source/log.rb

@@ -0,0 +1,29 @@
+require_relative 'keyframe'
+
+module LiveF1
+  class Source
+    class Log < Source
+
+      attr_reader :file, :data
+
+      def initialize file
+        @file = file
+        @data = YAML.load(@file.read)
+        @bytes = StringIO.new(@data[:bytes])
+      end
+
+      def read_bytes num
+        @bytes.read(num)
+      end
+
+      def keyframe number = nil
+        keyframe_data = data[:keyframes][number.to_s] || ""
+        Source::Keyframe.new StringIO.new(keyframe_data), self
+      end
+
+      def decryption_key session_number
+        data[:key].to_i
+      end
+    end
+  end
+end

data/lib/live_f1/source/session.rb

@@ -0,0 +1,41 @@
+module LiveF1
+  class Source
+    # A source's Session object holds information about the current state of
+    # the data stream, and can use that to decrypt the encrypted packets which
+    # are retrieved this way.
+    #
+    # = Decryption
+    #
+    # Decrypting a string of bytes from the timing stream relies on knowing two
+    # pieces of information, a decryption key which is specific to the session
+    # in progress, and a decryption salt which starts at a known value but is
+    # mutated with every byte that is decrypted.
+    #
+    # The decryption key can only be obtained from the live timing servers with
+    # a valid formula1.com Live Timing account, as described in
+    # LiveF1::Source::Live
+    class Session < Struct.new(:number, :event_type, :decryption_key)
+      INITIAL_DECRYPTION_SALT = 0x55555555
+
+      attr_accessor :decryption_salt
+
+      def initialize number, event_type, decryption_key
+        super
+        reset_decryption_salt!
+      end
+
+      # Decrypts the given string using this session's decryption_key and the
+      # current state of the decryption_salt.
+      def decrypt input
+        input.bytes.map do |b|
+          self.decryption_salt = (decryption_salt >> 1) ^ ((decryption_salt & 0x01).zero? ? 0 : decryption_key)
+          b ^ (decryption_salt & 0xff)
+        end.pack("c*")
+      end
+
+      def reset_decryption_salt!
+        self.decryption_salt = INITIAL_DECRYPTION_SALT
+      end
+    end
+  end
+end

data/lib/live_f1/source.rb

@@ -0,0 +1,83 @@
+require_relative 'source/live'
+require_relative 'source/log'
+require_relative 'source/session'
+require_relative 'packet'
+
+module LiveF1
+  # A Source reads raw live timing data packets from the live timing stream and
+  # processes them into semantic packets representing discrete instructions
+  # sent from the live timing server.
+  #
+  # These instructions relate to a low-level manipulation of the screen which
+  # would be displayed by the live timing Java applet. For example, when a
+  # car's sector 1 time is received, the applet needs to clear the other two
+  # sector times from the previous lap:
+  #
+  #   Driver        Lap       S1    S2    S3
+  #   L. HAMILTON   1:35.324  38.4  22.7  34.2
+  #
+  # becomes
+  #
+  #   Driver        Lap       S1    S2    S3
+  #   L. HAMILTON   1:35.324  39.1
+  #
+  # However, the live timing stream achieves this by sending three "packets" of
+  # data: a sector 1 packet containing "39.1", and sector 2 and 3 packets both
+  # containing the empty string "".
+  #
+  # The methods on a Source instance output all of these packets, even the ones
+  # which are useless from a data point of view.
+  class Source
+    attr_accessor :session
+
+    # Starts processing data from the relevant location, and yields all packets
+    # which are generated from the data stream.
+    def run
+      # We load packets from a couple of places below, but however we get them
+      # we treat them the same, hence this proc.
+      packet_processor = proc do |packet|
+        case packet
+        when LiveF1::Packet::Sys::SessionStart
+          self.session = Source::Session.new(packet.session_number, packet.event_type, decryption_key(packet.session_number))
+        when LiveF1::Packet::Sys::KeyFrame
+          session.reset_decryption_salt!
+        end
+        yield packet
+      end
+
+      # The live timing stream starts by loading the most recent Keyframe and
+      # reading its data. The keyframe contains "setup" information like driver
+      # names and numbers to get the app ready to receive live packets.
+      #
+      # Importantly we check to see whether the source *knows* about other
+      # keyframes. This is because the keyframe is itself another source (the
+      # +.run+ we call here is actually this very method on a different
+      # subclass)
+      if self.respond_to? :keyframe
+        keyframe.run(&packet_processor)
+      end
+
+      # Now that any keyframe has been parsed, we start streaming raw data
+      while packet = read_packet
+        packet_processor.call(packet)
+      end
+    end
+
+    def decrypt bytes
+      session.decrypt bytes
+    end
+
+    def read_packet
+      Packet.from_source(self, (session.event_type if session))
+    rescue EOFError
+    end
+
+    def read_bytes num
+      raise NotImplementedError, "#read_bytes should be implemented by #{self.class}"
+    end
+
+    def decryption_key session_number
+      raise NotImplementedError, "#decryption_key should be implemented by #{self.class}"
+    end
+  end
+end

data/lib/live_f1/version.rb

@@ -0,0 +1,3 @@
+module LiveF1
+  VERSION = '0.0.1'
+end

data/lib/live_f1.rb

@@ -0,0 +1,32 @@
+require_relative 'live_f1/source'
+require_relative 'live_f1/debug'
+
+# =Formula 1 live timing
+#
+# The LiveF1 library allows realtime parsing of data from the F1 live
+# timing stream. It connects to the binary stream and turns it into a series of
+# objects describing the stream
+#
+# ==Basics
+#
+# The live timing service is primarily used to control the live timing Java
+# applet at http://www.formula1.com/live_timing. However, the richness
+# of the data it provides means that the stream could be used to provide a much
+# deeper view of a session than the applet itself provides. This library
+# provides the very basic toolkit allowing such an application to be built using
+# Ruby, but when using it it's important to remember the service was built
+# around this one visual use.
+#
+# The stream generates packets from the start of every practice, qualifying and
+# race session. However anyone connecting to the stream after the start of a
+# session doesn't get sent the entire packet history. Instead, keyframes
+# containing the current live timing state are regularly generated throughout a
+# session, and new connections are given the latest keyframe followed by the
+# packets generated since that keyframe.
+#
+# ==Usage
+#
+# See bin/live-f1 for usage examples
+#
+module LiveF1
+end