From efb83dc900a01aafc89b2cdc4895620af0300e95 Mon Sep 17 00:00:00 2001 From: James Smith Date: Thu, 21 Aug 2008 10:36:53 +0100 Subject: [PATCH] Add decent rdoc documentation --- README | 15 ++++++----- lib/rb232/text_protocol.rb | 18 +++++++++++++ rb232.gemspec | 4 +-- src/port.c | 52 +++++++++++++++++++++++++++++--------- src/port.h | 47 ++++++++++++++++++++++++++++------ src/rb232.c | 21 ++++++++------- src/utility.c | 10 ++++++++ 7 files changed, 127 insertions(+), 40 deletions(-) diff --git a/README b/README index 3b90556..07dcdfc 100644 --- a/README +++ b/README @@ -45,10 +45,11 @@ You can provide alternative settings when you create a new port: :parity => true, :stop_bits => 2) -If you are using a simple text protocol over RS232, you can use the TextProtocol -class to help you out. It automatically monitors the port and splits messages -up by detecting separator characters. See examples/listen.rb for an example of -how to use this class. - -See http://github.com/Floppy/rb232/tree/master/spec/port_spec.rb for more -details. \ No newline at end of file +See http://github.com/Floppy/rb232/tree/master/spec/port_spec.rb or RB232::Port +documentation for more details. + +If you are using a simple text protocol over RS232, you can use the +RB232::TextProtocol class to help you out. It automatically monitors the port +and splits messages up by detecting separator characters. See +http://github.com/Floppy/rb232/tree/master/examples/listen.rb for an example of +how to use this class. \ No newline at end of file diff --git a/lib/rb232/text_protocol.rb b/lib/rb232/text_protocol.rb index 2ea9e41..27d9aef 100644 --- a/lib/rb232/text_protocol.rb +++ b/lib/rb232/text_protocol.rb @@ -3,18 +3,35 @@ module RB232 + # A helper class for RB232::Port which implements a simple text-based + # protocol on top of a serial port. Data is read from the serial port and split + # into individual messages based on a separator character. + # + # This class is Observable. Client code should implement an update(string) function + # add call TextProtocol#add_observer(self). When a complete message is received, + # the update() function will be called with the message string. class TextProtocol include Observable + # Create a protocol object. _port_ should be a RB232::Port object. + # _separator_ is the character which separates messages in the text protocol, + # "\n" by default. def initialize(port, separator = "\n") @port = port @separator = separator end + # Separator character, as specified in TextProtocol#new attr_reader :separator + + # Port object, as specified in TextProtocol#new attr_reader :port + # Begin processing incoming data from the serial port. + # A thread is started which monitors the port for data and detects + # complete messages. + # Call TextProtocol#stop to halt this process. def start @stop = false @reader_thread = Thread.new { @@ -31,6 +48,7 @@ def start } end + # Stop processing incoming data from the serial port. def stop @stop = true @reader_thread.join diff --git a/rb232.gemspec b/rb232.gemspec index b9d1be8..1b2f363 100644 --- a/rb232.gemspec +++ b/rb232.gemspec @@ -1,7 +1,7 @@ Gem::Specification.new do |s| s.name = "rb232" - s.version = "0.2.1" - s.date = "2008-08-20" + s.version = "0.2.2" + s.date = "2008-08-21" s.summary = "A simple serial port library for Ruby" s.email = "james@floppy.org.uk" s.homepage = "http://github.com/Floppy/rb232" diff --git a/src/port.c b/src/port.c index 24c8531..9977fe0 100644 --- a/src/port.c +++ b/src/port.c @@ -169,10 +169,14 @@ VALUE rb232_port_initialize_with_options(VALUE self, VALUE port, VALUE options) } /* - * This function implements a default argument for initialize(). - * Equivalent Ruby would be def initialize(port, options = {}). - * This function calls the _with_options version, providing an empty - * hash if one is not passed in. + * Create a Port object, using the port filename specified in _port_ (e.g. '/dev/ttyS0' or 'COM1'). + * + * Valid options are :baud_rate (integer), :data_bits (integer), :parity + * (boolean), and :stop_bits (integer). Default values are 9600, 8, false, and 1 respectively. + * + * call-seq: + * new(port, options = {}) + * */ VALUE rb232_port_initialize(int argc, VALUE* argv, VALUE self) { /* Only allow 1 or 2 arguments */ @@ -193,25 +197,33 @@ VALUE rb232_port_initialize(int argc, VALUE* argv, VALUE self) { return rb232_port_initialize_with_options(self, port, options); } -/* def port_name */ +/* + * Get the port name (for instance, '/dev/ttyS0' or 'COM1'), as set in Port#new. + */ VALUE rb232_port_get_port_name(VALUE self) { /* Return baud rate */ return rb_str_new2(get_port_data(self)->port_name); } -/* def baud_rate */ +/* + * Get the baud rate, as set in the _options_ argument to Port#new. + */ VALUE rb232_port_get_baud_rate(VALUE self) { /* Return baud rate */ return rb_uint_new(get_port_data(self)->baud_rate); } -/* def data_bits */ +/* + * Get the number of data bits, as set in the _options_ argument to Port#new. + */ VALUE rb232_port_get_data_bits(VALUE self) { /* Return baud rate */ return rb_uint_new(get_port_data(self)->data_bits); } -/* def parity */ +/* + * Get the parity setting, as set in the _options_ argument to Port#new. + */ VALUE rb232_port_get_parity(VALUE self) { /* Return baud rate */ if (get_port_data(self)->parity == TRUE) @@ -220,13 +232,17 @@ VALUE rb232_port_get_parity(VALUE self) { return Qfalse; } -/* def stop_bits */ +/* + * Get the number of stop bits, as set in the _options_ argument to Port#new. + */ VALUE rb232_port_get_stop_bits(VALUE self) { /* Return baud rate */ return rb_uint_new(get_port_data(self)->stop_bits); } -/* Read raw data from port */ +/* + * Read raw data from port + */ int rb232_port_read(VALUE self, char* buffer, VALUE count) { int bytes_to_read = NUM2INT(count); if (bytes_to_read > 255) @@ -234,7 +250,13 @@ int rb232_port_read(VALUE self, char* buffer, VALUE count) { return read(get_port_data(self)->port_handle, buffer, bytes_to_read); } -/* def read_bytes(count) */ +/* + * Read _count_ raw byte values from the port. + * Returns an array of values. Useful for binary protocols. + * call-seq: + * read_bytes(count) + * + */ VALUE rb232_port_read_bytes(VALUE self, VALUE count) { char buffer[256]; int bytes_read = rb232_port_read(self, buffer, count); @@ -245,7 +267,13 @@ VALUE rb232_port_read_bytes(VALUE self, VALUE count) { } } -/* def read_string(count) */ +/* + * Read _count_ characters from the port. + * Returns a string. Useful for text-based protocols. + * call-seq: + * read_string(count) + * + */ VALUE rb232_port_read_string(VALUE self, VALUE count) { char buffer[256]; int bytes_read = rb232_port_read(self, buffer, count); diff --git a/src/port.h b/src/port.h index 3752292..4cbd8a7 100644 --- a/src/port.h +++ b/src/port.h @@ -9,26 +9,57 @@ extern VALUE RB232_Port; /* Allocator for Port class */ VALUE rb232_port_alloc(VALUE klass); -/* def initialize(options = {}) */ +/* + * Create a Port object, using the port filename specified in _port_ (e.g. '/dev/ttyS0' or 'COM1'). + * + * Valid options are :baud_rate (integer), :data_bits (integer), :parity + * (boolean), and :stop_bits (integer). Default values are 9600, 8, false, and 1 respectively. + * + * call-seq: + * new(port, options = {}) + * + */ VALUE rb232_port_initialize(int argc, VALUE* argv, VALUE self); -/* def port_name */ +/* + * Get the port name (for instance, '/dev/ttyS0' or 'COM1'), as set in Port#new. + */ VALUE rb232_port_get_port_name(VALUE self); -/* def baud_rate */ +/* + * Get the baud rate, as set in the _options_ argument to Port#new. + */ VALUE rb232_port_get_baud_rate(VALUE self); -/* def data_bits */ +/* + * Get the number of data bits, as set in the _options_ argument to Port#new. + */ VALUE rb232_port_get_data_bits(VALUE self); -/* def parity */ +/* + * Get the parity setting, as set in the _options_ argument to Port#new. + */ VALUE rb232_port_get_parity(VALUE self); -/* def stop_bits */ +/* + * Get the number of stop bits, as set in the _options_ argument to Port#new. + */ VALUE rb232_port_get_stop_bits(VALUE self); -/* def read_bytes(count) */ +/* + * Read _count_ raw byte values from the port. + * Returns an array of values. Useful for binary protocols. + * call-seq: + * read_bytes(count) + * + */ VALUE rb232_port_read_bytes(VALUE self, VALUE count); -/* def read_string(count) */ +/* + * Read _count_ characters from the port. + * Returns a string. Useful for text-based protocols. + * call-seq: + * read_string(count) + * + */ VALUE rb232_port_read_string(VALUE self, VALUE count); diff --git a/src/rb232.c b/src/rb232.c index 7370147..fbca116 100644 --- a/src/rb232.c +++ b/src/rb232.c @@ -2,20 +2,19 @@ #include "port.h" /* - * Library initialization. - * Registers all classes and methods with the Ruby interpreter. - * Called automatically on require 'rb232'. + * Serial port communications. The class RB232::Port provides access to a hardware + * port on the local machine. Currently only Linux systems are supported. */ void Init_rb232() { RB232 = rb_define_module("RB232"); RB232_Port = rb_define_class_under(RB232, "Port", rb_cObject); rb_define_alloc_func(RB232_Port, rb232_port_alloc); - rb_define_method(RB232_Port, "initialize", rb232_port_initialize, -1); - rb_define_method(RB232_Port, "port_name", rb232_port_get_port_name, 0); - rb_define_method(RB232_Port, "baud_rate", rb232_port_get_baud_rate, 0); - rb_define_method(RB232_Port, "data_bits", rb232_port_get_data_bits, 0); - rb_define_method(RB232_Port, "parity", rb232_port_get_parity, 0); - rb_define_method(RB232_Port, "stop_bits", rb232_port_get_stop_bits, 0); - rb_define_method(RB232_Port, "read_bytes", rb232_port_read_bytes, 1); - rb_define_method(RB232_Port, "read_string", rb232_port_read_string, 1); + rb_define_method(RB232_Port, "initialize", rb232_port_initialize, -1); /* in port.c */ + rb_define_method(RB232_Port, "port_name", rb232_port_get_port_name, 0); /* in port.c */ + rb_define_method(RB232_Port, "baud_rate", rb232_port_get_baud_rate, 0); /* in port.c */ + rb_define_method(RB232_Port, "data_bits", rb232_port_get_data_bits, 0); /* in port.c */ + rb_define_method(RB232_Port, "parity", rb232_port_get_parity, 0); /* in port.c */ + rb_define_method(RB232_Port, "stop_bits", rb232_port_get_stop_bits, 0); /* in port.c */ + rb_define_method(RB232_Port, "read_bytes", rb232_port_read_bytes, 1); /* in port.c */ + rb_define_method(RB232_Port, "read_string", rb232_port_read_string, 1); /* in port.c */ } diff --git a/src/utility.c b/src/utility.c index c76bceb..dc0102a 100644 --- a/src/utility.c +++ b/src/utility.c @@ -1,5 +1,10 @@ #include "utility.h" +/* + * Get a key from a hash, or if it's not there, use the default. + * A bit like doing hash[key] || default_val in Ruby. + * Integer version. + */ int rbx_int_from_hash_or_default(VALUE hash, VALUE key, int default_val) { VALUE data = (rb_hash_aref(hash, key)); if (data == Qnil) @@ -8,6 +13,11 @@ int rbx_int_from_hash_or_default(VALUE hash, VALUE key, int default_val) { return NUM2INT(data); } +/* + * Get a key from a hash, or if it's not there, use the default. + * A bit like doing hash[key] || default_val in Ruby. + * Boolean version. + */ BOOL rbx_bool_from_hash_or_default(VALUE hash, VALUE key, BOOL default_val) { VALUE data = (rb_hash_aref(hash, key)); if (data == Qnil)