axis-netcam 0.1.0

data/CHANGELOG.txt

@@ -0,0 +1,3 @@
+=== 0.1.0 :: 2007-07-26
+
+* First public release.

data/LICENSE.txt

@@ -0,0 +1,165 @@
+		   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions. 
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version. 
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

data/Manifest.txt

@@ -0,0 +1,11 @@
+CHANGELOG.txt
+LICENSE.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/axis-netcam.rb
+lib/axis-netcam/camera.rb
+lib/axis-netcam/version.rb
+setup.rb
+test/axis-netcam_test.rb
+test/test_helper.rb

data/README.txt

@@ -0,0 +1,50 @@
+= AxisNetcam
+
+<i>Copyright 2007 Urbacon Ltd.</i>
+
+For info and downloads please see:
+
+  http://rubyforge.org/projects/axis-netcam/
+
+You can contact the author at:
+
+  matt at roughest dot net
+  
+
+<b>AxisNetcam provides a Ruby interface for interacting with network cameras
+from  Axis Communications.</b>
+
+Note that only a subset of the full Axis API is currently implemented, but the most
+useful functionality is in place.
+
+Example usage:
+
+  require 'rubygems' # (if installed as a gem)
+  require 'axis-netcam'
+  
+  c = AxisNetcam::Camera.new(:hostname => '192.168.2.25', 
+        :username => 'root', :password => 'pass')
+  c.tilt(90)
+  c.zoom(500)
+  f = File.open('/tmp/test.jpg', 'wb')
+  f.bin
+  f.write(c.snapshot_jpeg)
+  f.close
+  
+For more information about using a Camera object, see the AxisNetcam::Camera RDocs.
+
+
+------
+
+axis-netcam is free software; you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation; either version 3 of the License, or
+(at your option) any later version.
+
+axis-netcam is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.

data/Rakefile

@@ -0,0 +1,54 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/contrib/rubyforgepublisher'
+require 'fileutils'
+require 'hoe'
+include FileUtils
+require File.join(File.dirname(__FILE__), 'lib', 'axis-netcam', 'version')
+
+AUTHOR = "Matt Zukowski"  # can also be an array of Authors
+EMAIL = "matt@roughest.net"
+DESCRIPTION = "Provides a Ruby interface for interacting with network cameras from Axis Communications."
+GEM_NAME = "axis-netcam" # what ppl will type to install your gem
+RUBYFORGE_PROJECT = "axis-netcam" # The unix name for your project
+HOMEPATH = "http://axis-netcam.rubyforge.org"
+
+
+NAME = "axis-netcam"
+REV = nil # UNCOMMENT IF REQUIRED: File.read(".svn/entries")[/committed-rev="(d+)"/, 1] rescue nil
+VERS = ENV['VERSION'] || (AxisNetcam::VERSION::STRING + (REV ? ".#{REV}" : ""))
+                          CLEAN.include ['**/.*.sw?', '*.gem', '.config']
+RDOC_OPTS = ['--quiet', '--title', "axis-netcam documentation",
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README.txt",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject { |x| Array(x).first == 'hoe' } 
+  end 
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.author = AUTHOR 
+  p.description = DESCRIPTION
+  p.email = EMAIL
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/*_test.rb"]
+  p.clean_globs = CLEAN  #An array of file patterns to delete on clean.
+  
+  # == Optional
+  #p.changes        - A description of the release's latest changes.
+  #p.extra_deps     - An array of rubygem dependencies.
+  #p.spec_extras    - A hash of extra values to set in the gemspec.
+end

data/lib/axis-netcam/camera.rb

@@ -0,0 +1,391 @@
+require 'net/http'
+require 'cgi'
+require 'logger'
+
+module AxisNetcam
+  # The AxisNetcam::Camera class represents an Axis network camera.
+  #
+  # To control a camera, first create an instance of a Camera object and then call
+  # its methods. For example:
+  #
+  #   require 'axis-netcam/camera'
+  #
+  #   c = AxisNetcam::Camera.new(:hostname => '192.168.2.25', 
+  #         :username => 'root', :password => 'pass')
+  #
+  #   puts c.get_position[:tilt]
+  #   c.tilt(90)
+  #   puts c.camera_video_uri
+  #
+  # For a list of available methods, see the RDocs for included modules:
+  # AxisNetcam::Camera::PTZ :: for point-tilt-zoom control
+  # AxisNetcam::Camera::Users :: for user management
+  # AxisNetcam::Camera::Video :: for obtaining video/image data
+  # AxisNetcam::Camera::Info :: for diagnostic/status information
+  #
+  # Note that by default, AxisNetcam::Camera will log quite verbosely to stdout.
+  # See AxisNetcam::Camera#new for info on how to change this behaviour.
+  class Camera
+    
+    # The HTTP network connection to the camera.
+    @@http = nil
+    
+    attr_reader :hostname, :logger
+    
+    # Create a new Camera object.
+    # Options must include a :hostname, :username, and :password.
+    # A Logger object can also be specified to the :logger option, otherwise 
+    # logging will be done to STDOUT.
+    def initialize(options)
+      @hostname = options[:hostname] or raise(ArgumentError, "Must specify a hostname")
+      @username = options[:username] or raise(ArgumentError, "Must specify a username")
+      @password = options[:password] or raise(ArgumentError, "Must specify a password")
+      @log = options[:logger] || Logger.new(STDOUT)
+    end
+    
+    
+    # Functionality related to the camera's point, zoom, and tilt.
+    # Not all camera models support this.
+    module PTZ
+      
+      # Returns the camera's current absolute position as a hash with :pan, 
+      # :tilt, and :zoom elements.
+      #
+      # :tilt and :pan are specified in degrees from center (for example, -170 
+      # to 170 for :pan, depending on your camera's physical capabilities), and
+      # zoom is an integer factor, with 0 being no zoom (widest possible
+      # viewing angle) and 10000 approaching a camera's maximum zoom. Again,
+      # this depends on your camera's capabilities.
+      def get_position
+        str = axis_action("com/ptz.cgi", {'query' => 'position'}).split
+        pan = str[0].split("=").last
+        tilt = str[1].split("=").last
+        zoom = str[2].split("=").last
+        
+        {:pan => pan, :tilt => tilt, :zoom => zoom}
+      end
+      
+      # Simultanously pans, tilts, and zooms the camera.
+      # The argument is a hash that can have any of 'pan', 'tilt', and 'zoom' 
+      # elements, each specifying the desired value for the movement.
+      #
+      # Example:
+      #  
+      #   camera.ptz(:pan => 60, :zoom => 8000)
+      #
+      def ptz(ptz = {})
+        axis_action('com/ptz.cgi', ptz)
+      end
+      
+      # Tilts the camera (up/down) to the given absolute position in degrees.
+      def tilt(d)
+        axis_action("com/ptz.cgi", {'tilt'  => d})
+      end
+      
+      # Pans the camera (left/right) to the given absolute position in degrees.
+      def pan(d)
+        axis_action("com/ptz.cgi", {'pan'  => d})
+      end
+      
+      # Zooms the camera (in/out) to the given zoom factor.
+      def zoom(n)
+        axis_action("com/ptz.cgi", {'zoom'  => n})
+      end
+    
+      # Zooms the camera (in/out) to the given zoom factor.
+      def center_on(x,y)
+        axis_action("com/ptz.cgi", {'center'  => "#{x},#{y}"})
+      end
+      
+      # Returns and array with the names of the preset positions saved in the camera.
+      def get_preset_positions
+        str = axis_action("com/ptz.cgi", {'query' => 'presetposall'})
+        positions = []
+        str.each do |line|
+          line =~ /presetposno\d+=(.*)/
+          positions << $~[1].strip if $~ && $~[1]
+        end
+        positions
+      end
+      
+      def point_at_preset_name(preset_name)
+        axis_action("com/ptz.cgi", {'gotoserverpresetname' => preset_name})
+      end
+    end
+    include PTZ
+    
+    # Functionality related to managing the camera's user and group lists.
+    module Users
+    
+      # Adds a new user based on the given hash.
+      # The hash must have :username, :password, and :comment elements.
+      def add_user(user)
+        params = {
+          'action'  => 'add',
+          'user'    => user[:username],
+          'pwd'     => user[:password],
+          'comment' => user[:comment],
+          'grp'     => 'users',
+          'sgrp'    => 'axview'
+        }
+        axis_action("admin/pwdgrp.cgi", params)
+      end
+      
+      # Updates a user based on the given hash.
+      # username :: specifies the username of the user to update.
+      # attributes :: must be a hash with new values for :password and :comment.
+      def update_user(username, attributes)
+        params = {
+          'action'  => 'update',
+          'user'    => username,
+          'pwd'     => user[:password],
+          'comment' => user[:comment],
+          'grp'     => 'users',
+          'sgrp'    => 'axview'
+        }
+        axis_action("admin/pwdgrp.cgi", params)
+      end
+      
+      # Same as add_user, but updates the user account instead of creating it
+      # if it already exists.
+      def add_or_update_user(user)
+        if user_exists?(user[:username], user)
+          update_user(user[:username], user)
+        else
+          add_user(user)
+        end
+      end
+      
+      # Deletes the user with the given username.
+      def remove_user(username)
+        params = {
+          'action'  => 'remove',
+          'user'    => username,
+        }
+        axis_action("admin/pwdgrp.cgi", params)
+      end
+      
+      # Returns an array with the usernames of the users on the camera.
+      def users
+        str = axis_action("admin/pwdgrp.cgi", {'action' => 'get'})
+        return false unless str
+        usernames = []
+        str.split.collect do |u| 
+          u =~ /.*?="(.*)"/
+          if $~
+            usernames += $~[1].split(',')
+          else
+            usernames += []
+          end
+        end
+        usernames.uniq!
+      end
+      
+      # Checks if the user with the given username exists.
+      def user_exists?(username)
+        users.include? username
+      end
+    end
+    include Users
+    
+    
+    # Functionality related to the camera's video/image capabilities.
+    module Video
+      # Returns JPEG data with a snapshot of the current camera image.
+      # size :: optionally specifies the image size -- one of :full, :medium, 
+      #         or :thumbnail, or a string specifying the WxH dimensions like "640x480".
+      #
+      # To dump the JPEG data to a file, you can do something like this:
+      #
+      #   # Instantiate c as a AxisNetcam::Camera object, and then...
+      #   data = c.snapshot_jpeg
+      #   f = File.open('/tmp/test.jpg', 'wb')
+      #   f.binmode
+      #   f.write(data)
+      #   f.close
+      #
+      def snapshot_jpeg(size = :full)
+        case size
+        when :thumbnail
+          resolution = "160x120"
+        when :medium
+          resolution = "480x360"
+        when :full
+          resolution = "640x480"
+        else
+          resolution = size
+        end
+        
+        axis_action("jpg/image.cgi", 
+          {'resolution' => resolution, 'text' => '0'})
+      end
+      
+      # Returns the URI for accessing the camera's streaming Motion JPEG video.
+      # size :: optionally specifies the image size -- one of :full, :medium, 
+      #         or :thumbnail, or a string specifying the WxH dimensions like "640x480".
+      def camera_video_uri(size = :full)
+        case size
+        when :thumbnail
+          resolution = "160x120"
+        when :medium
+          resolution = "480x360"
+        when :full
+          resolution = "640x480"
+        end
+        "http://#{hostname}/axis-cgi/mjpg/video.cgi?resolution=#{resolution}&text=0"
+      end
+    end
+    include Video
+    
+    # Functionality related to obtaining information about the camera, such as its
+    # status, model number, etc.
+    module Info
+      # Returns the raw camera server report. 
+      #
+      # The report is a string with info about the camera's status and parameters,
+      # and differs considerably from model to model.
+      #
+      # If you have the Easycache Rails plugin installed, report data will be
+      # cached unless the force_refresh argument is true. This is done to help
+      # improve performance, as the server_report method is often called by other
+      # methods to retrieve various camera info.
+      def server_report(force_refresh = false)
+        if Object.const_defined? "Easycache"
+          if force_refresh
+            Easycache.write("#{hostname}_server_report",
+              @report = axis_action("admin/serverreport.cgi"))
+          else
+            @report ||= Easycache.cache("#{hostname}_server_report") do
+              axis_action("admin/serverreport.cgi")
+            end
+          end
+        else
+          axis_action("admin/serverreport.cgi")
+        end
+      end
+      
+      # Returns the camera's model name.
+      def model
+        begin
+          server_report =~ /prodshortname\s*=\s*"(.*?)"/i
+          $~[1]
+        rescue RemoteTimeout, RemoteError => e
+          @error = e
+          nil
+        end
+      end
+      
+      # Returns a code describing the camera's current status.
+      # The codes are as follows:
+      #
+      # :ok :: Camera is responding as expected.
+      # :down :: Camera is not responding at all (connection is timing out).
+      # :error :: Camera responded with an error.
+      # :no_server_report :: Camera responded but for some reason did not return a server report.
+      #
+      # Calling this method updates the @status_message attribute with some more
+      # detailed information about the camera's status (for example, the full error message in
+      # case of an error).
+      def status_code
+        begin
+          if self.server_report(true).empty?
+            @status_message = "Server did not send report"
+            :no_server_report
+          else
+            @status_message = "OK"
+            :ok
+          end
+        rescue InvalidLogin => e
+          @status_message = "Invalid login"
+          :invalid_login
+        rescue RemoteTimeout => e
+          @status_message = "Timeout"
+          :down
+        rescue RemoteError => e
+          @status_message = "Error: #{e}"
+          :error
+        end
+      end
+      
+      # Returns the result of the status message resulting from the last 
+      # status_code call. If no status message is available, status_code
+      # will be automatically called first.
+      def status_message
+        if @status_message
+          @status_message
+        else
+          status_code
+          @status_message
+        end
+      end
+    end
+    include Info
+    
+    private
+      # Executes an AXIS HTTP API call.
+      # script :: the remote cgi script to call
+      # params :: hash parameters to send to the script -- they will be URL-encoded for you
+      def axis_action(script, params = nil)
+        query = params.collect{|k,v| "#{k}=#{CGI.escape v.to_s}"}.join("&") if 
+          params
+        body = false
+        cmd_uri = "/axis-cgi/#{script}?#{query}"
+        begin
+          # read/open timeouts don't seem to be working, so we gotta do it ourselves
+          Timeout.timeout(15) do
+            req = Net::HTTP::Get.new(cmd_uri)
+            
+    #        if @@http && @@http.active?
+    #          @log.debug "AXIS REMOTE API reusing HTTP connection #{@@http}"
+    #          http = @@http
+    #        else
+              @log.debug "AXIS REMOTE API opening new HTTP connection to '#{hostname}'"
+              http = Net::HTTP.start(hostname)
+              http.read_timeout = 15 # wait 15 seconds for camera to respond, then give up
+              http.open_timeout = 15
+    #          @@http = http
+    #        end
+            
+            req.basic_auth @username, @password
+            
+            @log.info "AXIS REMOTE API CALL [#{hostname}]: #{cmd_uri}"
+            res = http.request(req)
+            @log.debug "AXIS REMOTE API CALL FINISHED"
+            
+    #        http.finish
+            
+            body = res.body
+            
+            if res.kind_of?(Net::HTTPClientError) || res.kind_of?(Net::HTTPServerError)
+              if res.kind_of?(Net::HTTPUnauthorized)
+                @log.error err = "AXIS CAMERA INVALID LOGIN [#{hostname}] for username '#{@username}'"
+                raise InvalidLogin, "Invalid login for username '#{@username}'"
+              else
+                @log.error err = "AXIS CAMERA ERROR [#{hostname}]: #{cmd_uri} -- #{body}"
+                raise RemoteError, body
+              end          
+            end
+          end
+          if body =~ /Error: (.*?)<\/body>/
+            @log.error err = "AXIS CAMERA ERROR [#{hostname}]: #{cmd_uri} -- #{$~[1]}"
+            raise RemoteError, err
+          else
+            body
+          end
+        rescue Timeout::Error
+          @log.error err = "AXIS CAMERA #{hostname} TIMED OUT!"
+          raise RemoteTimeout, err
+        end
+      end
+    
+      # Raised when a Camera is instantiated with incorrect username and/or password.
+      class InvalidLogin < Exception
+      end
+      # Raised when the camera responds with some error.
+      class RemoteError < Exception
+      end
+      # Raised when the remote camera does not respond within the timeout period.
+      class RemoteTimeout < Exception
+      end
+  end
+end