jeffrafter-rubygsm 0.3.1

data/README.rdoc

@@ -0,0 +1,47 @@
+RubyGSM is a Ruby library which uses ruby-serialport[http://github.com/toholio/ruby-serialport]
+to provide a nifty interface to send and receive SMS messages via a GSM modem.
+
+
+=== Sample Usage
+	
+  class ReverseApp
+      def initialize(gsm)
+          gsm.receive(method(:incoming))
+          @gsm = gsm
+      end
+      
+      def incoming(from, datetime, message)
+          @gsm.send(from, message.reverse)
+      end
+  end
+
+  gsm = GsmModem.new
+  ReverseApp.new(gsm)
+
+
+=== Installing
+RubyGSM is distributed via GitHub[http://github.com/adammck/rubygsm], which you must
+add as a gem source before installing:
+
+  $ sudo gem sources -a http://gems.github.com
+
+The library depends upon ruby-serialport, which is currently maintained on GitHub by
+Toholio[http://github.com/toholio/ruby-serialport]. This library is included as a Gem
+dependancy, so to install both:
+
+  $ sudo gem install adammck-rubygsm
+
+
+==== For Debian/Ubuntu users...
+The ruby-serialport library is available in the APT repository as a binary package, which
+is substatially less hassle to install than the Gem, for those who don't have a compiler
+installed (I prefer not to, on production servers). To install the package via apt, and
+ignore the Gem dependancy:
+
+  $ sudo apt-get install libserialport-ruby
+  $ sudo gem install --ignore-dependencies adammck-rubygsm
+
+
+=== Devices Tested
+* Multitech MTCBA
+* Wavecom M1306B

data/bin/gsm-modem-band

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+# vim: noet
+
+#require "rubygems"
+#require "rubygsm"
+dir = File.dirname(__FILE__)
+require "#{dir}/../lib/rubygsm.rb"
+
+
+begin
+	modem = Gsm::Modem.new
+	
+rescue Gsm::Modem::Error => err
+	puts "Initialization Error:"
+	puts "  " + err.desc
+	exit
+end
+
+
+puts "Found modem on port:"
+puts "  " + modem.port
+puts
+
+
+puts "GSM bands supported:"
+puts "  " + modem.bands_available.join(", ")
+puts
+
+
+puts "Currently selected:"
+puts "  " + modem.band
+puts
+
+
+if ARGV[0]
+	new_band = ARGV[0].downcase
+	
+	begin
+		modem.band = new_band
+		puts "Switched to: "
+		puts "  " + modem.band
+		
+	rescue StandardError => err
+		puts "Error switching band: "
+		puts "  " + err
+	end
+	
+	puts
+end

data/lib/rubygsm/core.rb

@@ -0,0 +1,851 @@
+#!/usr/bin/env ruby
+#:include:../../README.rdoc
+#:title:Ruby GSM
+#--
+# vim: noet
+#++
+
+# standard library
+require "timeout.rb"
+require "date.rb"
+
+# gems (we're using the ruby-serialport gem
+# now, so we can depend upon it in our spec)
+require "rubygems"
+require "serialport"
+
+module Gsm
+class Modem
+	include Timeout
+	
+	
+	attr_accessor :verbosity, :read_timeout
+	attr_reader :device, :port
+	
+	# call-seq:
+	#   Gsm::Modem.new(port, verbosity=:warn)
+	#
+	# Create a new instance, to initialize and communicate exclusively with a
+	# single modem device via the _port_ (which is usually either /dev/ttyS0
+	# or /dev/ttyUSB0), and start logging to *rubygsm.log* in the chdir.
+	def initialize(port=:auto, verbosity=:warn, baud=9600, cmd_delay=0.1)
+		
+		# if no port was specified, we'll attempt to iterate
+		# all of the serial ports that i've ever seen gsm
+		# modems mounted on. this is kind of shaky, and
+		# only works well with a single modem. for now,
+		# we'll try: ttyS0, ttyUSB0, ttyACM0, ttyS1...
+		if port == :auto
+			@device, @port = catch(:found) do
+				0.upto(8) do |n|
+					["ttyS", "ttyUSB", "ttyACM"].each do |prefix|
+						try_port = "/dev/#{prefix}#{n}"
+			
+						begin
+							# serialport args: port, baud, data bits, stop bits, parity
+							device = SerialPort.new(try_port, baud, 8, 1, SerialPort::NONE)
+							throw :found, [device, try_port]
+						
+						rescue ArgumentError, Errno::ENOENT
+							# do nothing, just continue to
+							# try the next port in order
+						end
+					end
+				end
+	
+				# tried all ports, nothing worked
+				raise AutoDetectError
+			end
+			
+		else
+			@device = SerialPort.new(port, baud, 8, 1, SerialPort::NONE)
+			@port = port
+		end
+		
+		@cmd_delay = cmd_delay
+		@verbosity = verbosity
+		@read_timeout = 10
+		@locked_to = false
+		
+		# keep track of the depth which each
+		# thread is indented in the log
+		@log_indents = {}
+		@log_indents.default = 0
+		
+		# to keep multi-part messages until
+		# the last part is delivered
+		@multipart = {}
+		
+		# (re-) open the full log file
+		@log = File.new "rubygsm.log", "w"
+		
+		# initialization message (yes, it's underlined)
+		msg = "RubyGSM Initialized at: #{Time.now}"
+		log msg + "\n" + ("=" * msg.length), :file
+		
+		# to store incoming messages
+		# until they're dealt with by
+		# someone else, like a commander
+		@incoming = []
+		
+		# initialize the modem
+		command "ATE0"      # echo off
+#COMPAT		command "AT+CMEE=1" # useful errors
+#COMPAT		command "AT+WIND=0" # no notifications
+		command "AT+CMGF=1" # switch to text mode
+	end
+	
+	
+	
+	
+	private
+	
+	
+	INCOMING_FMT = "%y/%m/%d,%H:%M:%S%Z" #:nodoc:
+	
+	def parse_incoming_timestamp(ts)
+		# extract the weirdo quarter-hour timezone,
+		# convert it into a regular hourly offset
+		ts.sub! /(\d+)$/ do |m|
+			sprintf("%02d", (m.to_i/4))
+		end
+		
+		# parse the timestamp, and attempt to re-align
+		# it according to the timezone we extracted
+		DateTime.strptime(ts, INCOMING_FMT)
+	end
+	
+	def parse_incoming_sms!(lines)
+		n = 0
+		
+		# iterate the lines like it's 1984
+		# (because we're patching the array,
+		# which is hard work for iterators)
+		while n < lines.length
+			
+			# not a CMT string? ignore it
+			unless lines && lines[n] && lines[n][0,5] == "+CMT:"
+				n += 1
+				next
+			end
+			
+			# since this line IS a CMT string (an incomming
+			# SMS), parse it and store it to deal with later
+			unless m = lines[n].match(/^\+CMT: "(.+?)",.*?,"(.+?)".*?$/)
+				err = "Couldn't parse CMT data: #{buf}"
+				raise RuntimeError.new(err)
+			end
+			
+			# extract the meta-info from the CMT line,
+			# and the message from the FOLLOWING line
+			from, timestamp = *m.captures
+			msg = lines[n+1].strip
+			
+			# notify the network that we accepted
+			# the incoming message (for read receipt)
+			# BEFORE pushing it to the incoming queue
+			# (to avoid really ugly race condition if
+			# the message is grabbed from the queue
+			# and responded to quickly, before we get
+			# a chance to issue at+cnma)
+			begin
+				command "AT+CNMA"
+				
+			# not terribly important if it
+			# fails, even though it shouldn't
+			rescue Gsm::Error
+				log "Receipt acknowledgement (CNMA) was rejected"
+			end
+			
+			# we might abort if this is
+			catch :skip_processing do
+			
+				# multi-part messages begin with ASCII char 130
+				if (msg[0] == 130) and (msg[1].chr == "@")
+					text = msg[7,999]
+					
+					# ensure we have a place for the incoming
+					# message part to live as they are delivered
+					@multipart[from] = []\
+						unless @multipart.has_key?(from)
+					
+					# append THIS PART
+					@multipart[from].push(text)
+					
+					# add useless message to log
+					part = @multipart[from].length
+					log "Received part #{part} of message from: #{from}"
+					
+					# abort if this is not the last part
+					throw :skip_processing\
+						unless (msg[5] == 173)
+					
+					# last part, so switch out the received
+					# part with the whole message, to be processed
+					# below (the sender and timestamp are the same
+					# for all parts, so no change needed there)
+					msg = @multipart[from].join("")
+					@multipart.delete(from)
+				end
+				
+				# just in case it wasn't already obvious...
+				log "Received message from #{from}: #{msg}"
+			
+				# store the incoming data to be picked up
+				# from the attr_accessor as a tuple (this
+				# is kind of ghetto, and WILL change later)
+				sent = parse_incoming_timestamp(timestamp)
+				@incoming.push Gsm::Incoming.new(self, from, sent, msg)
+			end
+			
+			# drop the two CMT lines (meta-info and message),
+			# and patch the index to hit the next unchecked
+			# line during the next iteration
+			lines.slice!(n,2)
+			n -= 1
+		end
+	end
+	
+	
+	# write a string to the modem immediately,
+	# without waiting for the lock
+	def write(str)
+		log "Write: #{str.inspect}", :traffic
+		
+		begin
+			str.each_byte do |b|
+				@device.putc(b.chr)
+			end
+		
+		# the device couldn't be written to,
+		# which probably means that it has
+		# crashed or been unplugged
+		rescue Errno::EIO
+			raise Gsm::WriteError
+		end
+	end
+	
+	
+	# read from the modem (blocking) until
+	# the term character is hit, and return
+	def read(term=nil)
+		term = "\r\n" if term==nil
+		term = [term] unless term.is_a? Array
+		buf = ""
+		
+		# include the terminator in the traffic dump,
+		# if it's anything other than the default
+		#suffix = (term != ["\r\n"]) ? " (term=#{term.inspect})" : ""
+		#log_incr "Read" + suffix, :traffic
+		
+		begin
+			timeout(@read_timeout) do
+				while true do
+					char = @device.getc
+					
+					# die if we couldn't read
+					# (nil signifies an error)
+					raise Gsm::ReadError\
+						if char.nil?
+					
+					# convert the character to ascii,
+					# and append it to the tmp buffer
+					buf << sprintf("%c", char)
+				
+					# if a terminator was just received,
+					# then return the current buffer
+					term.each do |t|
+						len = t.length
+						if buf[-len, len] == t
+							log "Read: #{buf.inspect}", :traffic
+							return buf.strip
+						end
+					end
+				end
+			end
+		
+		# reading took too long, so intercept
+		# and raise a more specific exception
+		rescue Timeout::Error
+			log = "Read: Timed out", :warn
+			raise TimeoutError
+		end
+	end
+	
+	
+	# issue a single command, and wait for the response
+	def command(cmd, resp_term=nil, write_term="\r")
+		begin
+			out = ""
+			log_incr "Command: #{cmd}"
+			
+			exclusive do
+				write(cmd + write_term)
+				out = wait(resp_term)
+			end
+		
+			# some hardware (my motorola phone) adds extra CRLFs
+			# to some responses. i see no reason that we need them
+			out.delete ""
+		
+			# for the time being, ignore any unsolicited
+			# status messages. i can't seem to figure out
+			# how to disable them (AT+WIND=0 doesn't work)
+			out.delete_if do |line|
+				(line[0,6] == "+WIND:") or
+				(line[0,6] == "+CREG:") or
+				(line[0,7] == "+CGREG:")
+			end
+		
+			# parse out any incoming sms that were bundled
+			# with this data (to be fetched later by an app)
+			parse_incoming_sms!(out)
+		
+			# log the modified output
+			log_decr "=#{out.inspect}"
+		
+			# rest up for a bit (modems are
+			# slow, and get confused easily)
+			sleep(@cmd_delay)
+			return out
+		
+		# if the 515 (please wait) error was thrown,
+		# then automatically re-try the command after
+		# a short delay. for others, propagate
+		rescue Error => err
+			log "Rescued: #{err.desc}"
+			
+			if (err.type == "CMS") and (err.code == 515)
+				sleep 2
+				retry
+			end
+			
+			log_decr
+			raise
+		end
+	end
+	
+	
+	def query(cmd)
+		log_incr "Query: #{cmd}"
+		out = command cmd
+	
+		# only very simple responses are supported
+		# (on purpose!) here - [response, crlf, ok]
+		if (out.length==2) and (out[1]=="OK")
+			log_decr "=#{out[0].inspect}"
+			return out[0]
+		
+		else
+			err = "Invalid response: #{out.inspect}"
+			raise RuntimeError.new(err)
+		end
+	end
+	
+	
+	# just wait for a response, by reading
+	# until an OK or ERROR terminator is hit
+	def wait(term=nil)
+		buffer = []
+		log_incr "Waiting for response"
+		
+		while true do
+			buf = read(term)
+			buffer.push(buf)
+		
+			# some errors contain useful error codes,
+			# so raise a proper error with a description
+			if m = buf.match(/^\+(CM[ES]) ERROR: (\d+)$/)
+				log_then_decr "!! Raising Gsm::Error #{$1} #{$2}"
+				raise Error.new(*m.captures)
+			end
+		
+			# some errors are not so useful :|
+			if buf == "ERROR"
+				log_then_decr "!! Raising Gsm::Error"
+				raise Error
+			end
+		
+			# most commands return OK upon success, except
+			# for those which prompt for more data (CMGS)
+			if (buf=="OK") or (buf==">")
+				log_decr "=#{buffer.inspect}"
+				return buffer
+			end
+		
+			# some commands DO NOT respond with OK,
+			# even when they're successful, so check
+			# for those exceptions manually
+			if m = buf.match(/^\+CPIN: (.+)$/)
+				log_decr "=#{buffer.inspect}"
+				return buffer
+			end
+		end
+	end
+	
+	
+	def exclusive &blk
+		old_lock = nil
+		
+		begin
+			
+			# prevent other threads from issuing
+			# commands TO THIS MODDEM while this
+			# block is working. this does not lock
+			# threads, just the gsm device
+			if @locked_to and (@locked_to != Thread.current)
+				log "Locked by #{@locked_to["name"]}, waiting..."
+			
+				# wait for the modem to become available,
+				# so we can issue commands from threads
+				while @locked_to
+					sleep 0.05
+				end
+			end
+			
+			# we got the lock!
+			old_lock = @locked_to
+			@locked_to = Thread.current
+			log_incr "Got lock"
+		
+			# perform the command while
+			# we have exclusive access
+			# to the modem device
+			yield
+			
+		
+		# something went bang, which happens, but
+		# just pass it on (after unlocking...)
+		rescue Gsm::Error
+			raise
+		
+		
+		# no message, but always un-
+		# indent subsequent log messages
+		# and RELEASE THE LOCK
+		ensure
+			@locked_to = old_lock
+			Thread.pass
+			log_decr
+		end
+	end
+	
+	
+	
+	
+	public
+	
+	
+	# call-seq:
+	#   hardware => hash
+	#
+	# Returns a hash of containing information about the physical
+	# modem. The contents of each value are entirely manufacturer
+	# dependant, and vary wildly between devices.
+	#
+	#   modem.hardware => { :manufacturer => "Multitech".
+	#                       :model        => "MTCBA-G-F4", 
+	#                       :revision     => "123456789",
+	#                       :serial       => "ABCD" }
+	def hardware
+		return {
+			:manufacturer => query("AT+CGMI"),
+			:model        => query("AT+CGMM"),
+			:revision     => query("AT+CGMR"),
+			:serial       => query("AT+CGSN") }
+	end
+	
+	
+	# The values accepted and returned by the AT+WMBS
+	# command, mapped to frequency bands, in MHz. Copied
+	# directly from the MultiTech AT command-set reference
+	Bands = {
+		0 => "850",
+		1 => "900",
+		2 => "1800",
+		3 => "1900",
+		4 => "850/1900",
+		5 => "900E/1800",
+		6 => "900E/1900"
+	}
+	
+	# call-seq:
+	#   bands_available => array
+	#
+	# Returns an array containing the bands supported by
+	# the modem.
+	def bands_available
+		data = query("AT+WMBS=?")
+		
+		# wmbs data is returned as something like:
+		#  +WMBS: (0,1,2,3,4,5,6),(0-1)
+		#  +WMBS: (0,3,4),(0-1)
+		# extract the numbers with a regex, and
+		# iterate each to resolve it to a more
+		# readable description
+		if m = data.match(/^\+WMBS: \(([\d,]+)\),/)
+			return m.captures[0].split(",").collect do |index|
+				Bands[index.to_i]
+			end
+		
+		else
+			# Todo: Recover from this exception
+			err = "Not WMBS data: #{data.inspect}"
+			raise RuntimeError.new(err)
+		end
+	end
+	
+	# call-seq:
+	#   band => string
+	#
+	# Returns a string containing the band
+	# currently selected for use by the modem.
+	def band
+		data = query("AT+WMBS?")
+		if m = data.match(/^\+WMBS: (\d+),/)
+			return Bands[m.captures[0].to_i]
+			
+		else
+			# Todo: Recover from this exception
+			err = "Not WMBS data: #{data.inspect}"
+			raise RuntimeError.new(err)
+		end
+	end
+	
+	BandAreas = {
+		:usa     => 4,
+		:africa  => 5,
+		:europe  => 5,
+		:asia    => 5,
+		:mideast => 5
+	}
+	
+	# call-seq:
+	#   band=(_numeric_band_) => string
+	#
+	# Sets the band currently selected for use
+	# by the modem, using either a literal band
+	# number (passed directly to the modem, see
+	# Gsm::Modem.Bands) or a named area from
+	# Gsm::Modem.BandAreas:
+	#
+	#   m = Gsm::Modem.new
+	#   m.band = :usa    => "850/1900"
+	#   m.band = :africa => "900E/1800"
+	#   m.band = :monkey => ArgumentError
+	#
+	# (Note that as usual, the United States of
+	# America is wearing its ass backwards.)
+	#
+	# Raises ArgumentError if an unrecognized band was
+	# given, or raises Gsm::Error if the modem does
+	# not support the given band.
+	def band=(new_band)
+		
+		# resolve named bands into numeric
+		# (mhz values first, then band areas)
+		unless new_band.is_a?(Numeric)
+			
+			if Bands.has_value?(new_band.to_s)
+				new_band = Bands.index(new_band.to_s)
+			
+			elsif BandAreas.has_key?(new_band.to_sym)
+				new_band = BandAreas[new_band.to_sym]
+				
+			else
+				err = "Invalid band: #{new_band}"
+				raise ArgumentError.new(err)
+			end
+		end
+		
+		# set the band right now (second wmbs
+		# argument is: 0=NEXT-BOOT, 1=NOW). if it
+		# fails, allow Gsm::Error to propagate
+		command("AT+WMBS=#{new_band},1")
+	end
+	
+	# call-seq:
+	#   pin_required? => true or false
+	#
+	# Returns true if the modem is waiting for a SIM PIN. Some SIM cards will refuse
+	# to work until the correct four-digit PIN is provided via the _use_pin_ method.
+	def pin_required?
+		not command("AT+CPIN?").include?("+CPIN: READY")
+	end
+	
+	
+	# call-seq:
+	#   use_pin(pin) => true or false
+	#
+	# Provide a SIM PIN to the modem, and return true if it was accepted.
+	def use_pin(pin)
+		
+		# if the sim is already ready,
+		# this method isn't necessary
+		if pin_required?
+			begin
+				command "AT+CPIN=#{pin}"
+		
+			# if the command failed, then
+			# the pin was not accepted
+			rescue Gsm::Error
+				return false
+			end
+		end
+		
+		# no error = SIM
+		# PIN accepted!
+		true
+	end
+	
+	
+	# call-seq:
+	#   signal => fixnum or nil
+	#
+	# Returns an fixnum between 1 and 99, representing the current
+	# signal strength of the GSM network, or nil if we don't know.
+	def signal_strength
+		data = query("AT+CSQ")
+		if m = data.match(/^\+CSQ: (\d+),/)
+			
+			# 99 represents "not known or not detectable",
+			# but we'll use nil for that, since it's a bit
+			# more ruby-ish to test for boolean equality
+			csq = m.captures[0].to_i
+			return (csq<99) ? csq : nil
+			
+		else
+			# Todo: Recover from this exception
+			err = "Not CSQ data: #{data.inspect}"
+			raise RuntimeError.new(err)
+		end
+	end
+	
+	
+	# call-seq:
+	#   wait_for_network
+	#
+	# Blocks until the signal strength indicates that the
+	# device is active on the GSM network. It's a good idea
+	# to call this before trying to send or receive anything.
+	def wait_for_network
+		
+		# keep retrying until the
+		# network comes up (if ever)
+		until csq = signal_strength
+			sleep 1
+		end
+		
+		# return the last
+		# signal strength
+		return csq
+	end
+	
+	
+	# call-seq:
+	#   send_sms(message) => true or false
+	#   send_sms(recipient, text) => true or false
+	#
+	# Sends an SMS message, and returns true if the network
+	# accepted it for delivery. We currently can't handle read
+	# receipts, so have no way of confirming delivery.
+	#
+	# Note: the recipient is passed directly to the modem, which
+	# in turn passes it straight to the SMSC (sms message center).
+	# for maximum compatibility, use phone numbers in international
+	# format, including the *plus* and *country code*.
+	def send_sms(*args)
+		
+		# extract values from Outgoing object.
+		# for now, this does not offer anything
+		# in addition to the recipient/text pair,
+		# but provides an upgrade path for future
+		# features (like FLASH and VALIDITY TIME)
+		if args.length == 1\
+		and args[0].is_a? Gsm::Outgoing
+			to = args[0].recipient
+			msg = args[0].text
+		
+		# the < v0.4 arguments. maybe
+		# deprecate this one day
+		elsif args.length == 2
+			to, msg = *args
+		
+		else
+			raise ArgumentError,\
+				"The Gsm::Modem#send_sms method accepts" +\
+				"a single Gsm::Outgoing instance, " +\
+				"or recipient and text strings"
+		end
+		
+		# the number must be in the international
+		# format for some SMSCs (notably, the one
+		# i'm on right now) so maybe add a PLUS
+		#to = "+#{to}" unless(to[0,1]=="+")
+		
+		# 1..9 is a special number which does notm
+		# result in a real sms being sent (see inject.rb)
+		if to == "+123456789"
+			log "Not sending test message: #{msg}"
+			return false
+		end
+		
+		# block the receiving thread while
+		# we're sending. it can take some time
+		exclusive do
+			log_incr "Sending SMS to #{to}: #{msg}"
+			
+			# initiate the sms, and wait for either
+			# the text prompt or an error message
+			command "AT+CMGS=\"#{to}\"", ["\r\n", "> "]
+			
+			begin
+				# send the sms, and wait until
+				# it is accepted or rejected
+				write "#{msg}#{26.chr}"
+				wait
+				
+			# if something went wrong, we are
+			# be stuck in entry mode (which will
+			# result in someone getting a bunch
+			# of AT commands via sms!) so send
+			# an escpae, to... escape
+			rescue Exception, Timeout::Error => err
+				log "Rescued #{err.desc}"
+				return false
+				#write 27.chr
+				#wait
+			end
+			
+			log_decr
+		end
+				
+		# if no error was raised,
+		# then the message was sent
+		return true
+	end
+	
+	
+	# call-seq:
+	#   receive(callback_method, interval=5, join_thread=false)
+	#
+	# Starts a new thread, which polls the device every _interval_
+	# seconds to capture incoming SMS and call _callback_method_
+	# for each.
+	#
+	#   class Receiver
+	#     def incoming(msg)
+	#       puts "From #{msg.from} at #{msg.sent}:", msg.text
+	#     end
+	#   end
+	#   
+	#   # create the instances,
+	#   # and start receiving
+	#   rcv = Receiver.new
+	#   m = Gsm::Modem.new "/dev/ttyS0"
+	#   m.receive rcv.method :incoming
+	#   
+	#   # block until ctrl+c
+	#   while(true) { sleep 2 }
+	#
+	# Note: New messages may arrive at any time, even if this method's
+	# receiver thread isn't waiting to process them. They are not lost,
+	# but cached in @incoming until this method is called.
+	def receive(callback, interval=5, join_thread=false)
+		@polled = 0
+		
+		@thr = Thread.new do
+			Thread.current["name"] = "receiver"
+			
+			# keep on receiving forever
+			while true
+				command "AT"
+        check_for_inbox_messages
+        
+				# enable new message notification mode
+				# every ten intevals, in case the
+				# modem "forgets" (power cycle, etc)
+				if (@polled % 10) == 0
+#COMPAT					command "AT+CNMI=2,2,0,0,0"
+				end
+				
+				# if there are any new incoming messages,
+				# iterate, and pass each to the receiver
+				# in the same format that they were built
+				# back in _parse_incoming_sms!_
+				unless @incoming.empty?
+					@incoming.each do |msg|
+						begin
+							callback.call(msg)
+							
+						rescue StandardError => err
+							log "Error in callback: #{err}"
+						end
+					end
+					
+					# we have dealt with all of the pending
+					# messages. todo: this is a ridiculous
+					# race condition, and i fail at ruby
+					@incoming.clear
+				end
+				
+				# re-poll every
+				# five seconds
+				sleep(interval)
+				@polled += 1
+			end
+		end
+		
+		# it's sometimes handy to run single-
+		# threaded (like debugging handsets)
+		@thr.join if join_thread
+	end
+  
+  def select_default_mailbox
+    # Eventually we will select the first mailbox as the default
+    result = command("AT+CPMS=?")
+    boxes = result.first.scan(/\"(\w+)\"/).flatten #"
+    mailbox = boxes.first        
+    command "AT+CPMS=\"#{mailbox}\""
+    mailbox
+  rescue
+    raise RuntimeError.new("Could not select the default mailbox")
+    nil
+  end
+  
+  # Could accomplish this with a CMGL=\"REC UNREAD\" too
+  def check_for_inbox_messages
+    return unless select_default_mailbox
+    
+    # Try to read the first message from the box (should this be 0?)
+    begin
+      out = command("AT+CMGR=1")
+    rescue
+      return     
+    end  
+    return if out.nil? || out.empty?
+
+    # Delete that message
+    command("AT+CMGD=1")
+
+    # Break that down
+    header = out.first
+    msg = out[1..out.size-2].join("\n")
+    validity = out.last
+       				
+    # Read the header
+    header = header.scan(/\"([^"]+)\"/).flatten #"
+    status = header[0]
+    from = header[1]
+    timestamp = header[2]
+    # Parsing this using the incoming format failed, it need %Y instead of %y
+    sent = DateTime.parse(timestamp)
+                        
+    # just in case it wasn't already obvious...
+    log "Received message from #{from}: #{msg}"
+  
+    @incoming.push Gsm::Incoming.new(self, from, sent, msg)
+  end
+  
+end # Modem
+end # Gsm

data/lib/rubygsm/errors.rb

@@ -0,0 +1,128 @@
+#!/usr/bin/env ruby
+#:title:Ruby GSM Errors
+#--
+# vim: noet
+#++
+
+module Gsm
+	class Error < StandardError
+		ERRORS = {
+			"CME" => {
+				3   => "Operation not allowed",
+				4   => "Operation not supported",
+				5   => "PH-SIM PIN required (SIM lock)",
+				10  => "SIM not inserted",
+				11  => "SIM PIN required",
+				12  => "SIM PUK required",
+				13  => "SIM failure",
+				16  => "Incorrect password",
+				17  => "SIM PIN2 required",
+				18  => "SIM PUK2 required",
+				20  => "Memory full",
+				21  => "Invalid index",
+				22  => "Not found",
+				24  => "Text string too long",
+				26  => "Dial string too long",
+				27  => "Invalid characters in dial string",
+				30  => "No network service",
+				32  => "Network not allowed – emergency calls only",
+				40  => "Network personal PIN required (Network lock)",
+				103 => "Illegal MS (#3)",
+				106 => "Illegal ME (#6)",
+				107 => "GPRS services not allowed",
+				111 => "PLMN not allowed",
+				112 => "Location area not allowed",
+				113 => "Roaming not allowed in this area",
+				132 => "Service option not supported",
+				133 => "Requested service option not subscribed",
+				134 => "Service option temporarily out of order",
+				148 => "unspecified GPRS error",
+				149 => "PDP authentication failure",
+				150 => "Invalid mobile class"
+			},
+			
+			# message service errors
+			"CMS" => {
+				301 => "SMS service of ME reserved",
+				302 => "Operation not allowed",
+				303 => "Operation not supported",
+				304 => "Invalid PDU mode parameter",
+				305 => "Invalid text mode parameter",
+				310 => "SIM not inserted",
+				311 => "SIM PIN required",
+				312 => "PH-SIM PIN required",
+				313 => "SIM failure",
+				316 => "SIM PUK required",
+				317 => "SIM PIN2 required",
+				318 => "SIM PUK2 required",
+				321 => "Invalid memory index",
+				322 => "SIM memory full",
+				330 => "SC address unknown",
+				340 => "No +CNMA acknowledgement expected",
+				
+				# specific error result codes (also from +CMS ERROR)
+				500 => "Unknown error",
+				512 => "MM establishment failure (for SMS)",
+				513 => "Lower layer failure (for SMS)",
+				514 => "CP error (for SMS)",
+				515 => "Please wait, init or command processing in progress",
+				517 => "SIM Toolkit facility not supported",
+				518 => "SIM Toolkit indication not received",
+				519 => "Reset product to activate or change new echo cancellation algo",
+				520 => "Automatic abort about get PLMN list for an incomming call",
+				526 => "PIN deactivation forbidden with this SIM card",
+				527 => "Please wait, RR or MM is busy. Retry your selection later",
+				528 => "Location update failure. Emergency calls only",
+				529 => "PLMN selection failure. Emergency calls only",
+				531 => "SMS not send: the <da> is not in FDN phonebook, and FDN lock is enabled (for SMS)"
+			}
+		}
+		
+		attr_reader :type, :code
+		def initialize(type=nil, code=nil)
+			@code = code.to_i
+			@type = type
+		end
+		
+		def desc
+			# attempt to return something useful
+			return(ERRORS[@type][@code])\
+				if(@type and ERRORS[@type] and @code and ERRORS[@type][@code])
+			
+			# fall back to something not-so useful
+			return "Unknown error (unrecognized command?) " +\
+			       "[type=#{@type}] [code=#{code}]"
+		end
+		
+		alias :to_s :desc
+	end
+	
+	# TODO: what the hell is going on with
+	# all these "desc" methods? refactor this
+	
+	class TimeoutError < Error #:nodoc:
+		def desc
+			"The command timed out"
+		end
+	end
+	
+	class WriteError < Error #:nodoc:
+		def desc
+			"The modem couldn't be written to. It " +\
+			"may have crashed or been unplugged"
+		end
+	end
+	
+	class ReadError < Error #:nodoc:
+		def desc
+			"The modem couldn't be read from. It " +\
+			"may have crashed or been unplugged"
+		end
+	end
+	
+	class AutoDetectError < Error #:nodoc:
+		def desc
+			"No modem could be auto-detected."
+		end
+	end
+end

data/lib/rubygsm/log.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+# vim: noet
+
+module Gsm
+class Modem
+	private
+	
+	# Symbols accepted by the Gsm::Modem.new _verbosity_
+	# argument. Each level includes all of the levels
+	# below it (ie. :debug includes all :warn messages)
+	LOG_LEVELS = {
+		:file    => 5,
+		:traffic => 4,
+		:debug   => 3,
+		:warn    => 2,
+		:error   => 1 }
+	
+	def log(msg, level=:debug)
+		ind = "  " * (@log_indents[Thread.current] or 0)
+		
+		# create a 
+		thr = Thread.current["name"]
+		thr = (thr.nil?) ? "" : "[#{thr}] "
+		
+		# dump (almost) everything to file
+		if LOG_LEVELS[level] >= LOG_LEVELS[:debug]\
+		or level == :file
+		
+			@log.puts thr + ind + msg
+			@log.flush
+		end
+		
+		# also print to the rolling
+		# screen log, if necessary
+		if LOG_LEVELS[@verbosity] >= LOG_LEVELS[level]
+			$stderr.puts thr + ind + msg
+		end
+	end
+	
+	# log a message, and increment future messages
+	# in this thread. useful for nesting logic
+	def log_incr(*args)
+		log(*args) unless args.empty?
+		@log_indents[Thread.current] += 1
+	end
+	
+	# close the logical block, and (optionally) log
+	def log_decr(*args)
+		@log_indents[Thread.current] -= 1\
+			if @log_indents[Thread.current] > 0
+		log(*args) unless args.empty?
+	end
+	
+	# the last message in a logical block
+	def log_then_decr(*args)
+		log(*args)
+		log_decr
+	end
+end # Modem
+end # Gsm

data/lib/rubygsm/msg/incoming.rb

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+# vim: noet
+
+module Gsm
+	class Incoming
+		attr_reader :device, :sender, :sent, :received, :text
+		
+		def initialize(device, sender, sent, text)
+			
+			# move all arguments into read-only
+			# attributes. ugly, but Struct only
+			# supports read/write attrs
+			@device = device
+			@sender = sender
+			@sent = sent
+			@text = text
+			
+			# assume that the message was
+			# received right now, since we
+			# don't have an incoming buffer
+			@received = Time.now
+		end
+		
+		def to_a
+			[@device, @sender, @sent, @text]
+		end
+	end
+end

data/lib/rubygsm/msg/outgoing.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# vim: noet
+
+module Gsm
+	class Outgoing
+		attr_accessor :recipient, :text
+		attr_reader :device, :sent
+		
+		def initialize(device, recipient=nil, text=nil)
+			
+			# check that the device is 
+			#raise ArgumentError, "Invalid device"\
+			#	unless device.respond_to?(:send_sms)
+			
+			# init the instance vars
+			@recipient = recipient
+			@device = device
+			@text = text
+		end
+		
+		def send!
+			@device.send_sms(self)
+			@sent = Time.now
+			
+			# once sent, allow no
+			# more modifications
+			freeze
+		end
+	end
+end

data/lib/rubygsm.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+# vim: noet
+
+dir = File.dirname(__FILE__)
+require "#{dir}/rubygsm/core.rb"
+require "#{dir}/rubygsm/errors.rb"
+require "#{dir}/rubygsm/log.rb"
+
+# messages are now passed around
+# using objects, rather than flat
+# arguments (from, time, msg, etc)
+require "#{dir}/rubygsm/msg/incoming.rb"
+require "#{dir}/rubygsm/msg/outgoing.rb"
+
+# during development, it's important to EXPLODE
+# as early as possible when something goes wrong
+Thread.abort_on_exception = true
+Thread.current["name"] = "main"

data/rubygsm.gemspec

@@ -0,0 +1,28 @@
+Gem::Specification.new do |s|
+	s.name     = "rubygsm"
+	s.version  = "0.3.1"
+	s.date     = "2009-01-09"
+	s.summary  = "Send and receive SMS with a GSM modem"
+	s.email    = "adam.mckaig@gmail.com"
+	s.homepage = "http://github.com/adammck/rubygsm"
+	s.authors  = ["Adam Mckaig"]
+	s.has_rdoc = true
+	
+	s.files = [
+		"rubygsm.gemspec",
+		"README.rdoc",
+		"lib/rubygsm.rb",
+		"lib/rubygsm/core.rb",
+		"lib/rubygsm/errors.rb",
+		"lib/rubygsm/log.rb",
+		"lib/rubygsm/msg/incoming.rb",
+		"lib/rubygsm/msg/outgoing.rb",
+		"bin/gsm-modem-band"
+	]
+	
+	s.executables = [
+		"gsm-modem-band"
+	]
+	
+	s.add_dependency("toholio-serialport", ["> 0.7.1"])
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: jeffrafter-rubygsm
+version: !ruby/object:Gem::Version 
+  version: 0.3.1
+platform: ruby
+authors: 
+- Adam Mckaig
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-01-09 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: toholio-serialport
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.7.1
+    version: 
+description: 
+email: adam.mckaig@gmail.com
+executables: 
+- gsm-modem-band
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- rubygsm.gemspec
+- README.rdoc
+- lib/rubygsm.rb
+- lib/rubygsm/core.rb
+- lib/rubygsm/errors.rb
+- lib/rubygsm/log.rb
+- lib/rubygsm/msg/incoming.rb
+- lib/rubygsm/msg/outgoing.rb
+- bin/gsm-modem-band
+has_rdoc: true
+homepage: http://github.com/adammck/rubygsm
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Send and receive SMS with a GSM modem
+test_files: []
+