can_messenger 0.2.3 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4fc9aa1a5061f03c93f08c98700ed0036218c2c6fe91f0a2c661522b3e86f36e
-  data.tar.gz: 77dccf7d1b719254e253c86bfd9f31e193b7ae20c9902ec453dbb510ec6a8acb
+  metadata.gz: c3c1f6bf2353eb4b67b93f9aa9e167a4474b8c65cc1abe2327b520d04695cec2
+  data.tar.gz: 6afe7242348e786084de8c6d8afe25f18727ac57b2eeea727518ddd77d53330a
 SHA512:
-  metadata.gz: a52172045469c761c4dd7eac2d47d998e1cd236624cda4c1a75ed711499374e917259da1465d3b0323b18b99d800d0e53ce6578b9e86c582851d940933a969f3
-  data.tar.gz: 76142086690c5542ee39afddfd3e54309bff19482ad1385b80092ce0c2998cba5181cf77ad101cc3614e029bcc79cc6ac0ef23e37bb95f44274b6d2274917108
+  metadata.gz: 7cd537434d6c9f0d41a6a9ad6dd37229bb569057d9b9e259ac301792e71b629df1b66f2ece6c3d5606e7224410d4f42d1c2488894f5341faecb551e46b222140
+  data.tar.gz: 18620bf7cc07a7694438b0e3da277a3b96d4767cb87d36c5310920dbce5976cc21971e4c3e572869c99ee3a37a7eac7e9996f7948f2d5d2001875b9dead5f4c1

data/README.md

@@ -44,7 +44,7 @@ To create a new instance of `CanMessenger` and start sending messages:
 ```ruby
 require 'can_messenger'
 
-messenger = CanMessenger::Messenger.new('can0')
+messenger = CanMessenger::Messenger.new(interface_name: 'can0')
 ```
 
 ### Sending CAN Messages
@@ -52,7 +52,7 @@ messenger = CanMessenger::Messenger.new('can0')
 To send a message:
 
 ```ruby
-messenger.send_can_message(0x123, [0xDE, 0xAD, 0xBE, 0xEF])
+messenger.send_can_message(id: 0x123, data: [0xDE, 0xAD, 0xBE, 0xEF])
 ```
 
 ### Receiving CAN Messages
@@ -103,21 +103,57 @@ To stop listening, use:
 messenger.stop_listening
 ```
 
+## Important Considerations
+
+Before using `can_messenger`, please note the following:
+
+- **Environment Requirements:**
+
+  - **Permissions:** Working with raw sockets may require elevated privileges or membership in a specific group to open and bind to CAN interfaces without running as root.
+
+- **API Changes (v1.0.0 and later):**
+
+  - **Keyword Arguments:** The Messenger API now requires keyword arguments. For example, when initializing the Messenger, use:
+    ```ruby
+    messenger = CanMessenger::Messenger.new(interface_name: 'can0')
+    ```
+    Similarly, methods like `send_can_message` now require named parameters:
+    ```ruby
+    messenger.send_can_message(id: 0x123, data: [0xDE, 0xAD, 0xBE, 0xEF])
+    ```
+    If you're upgrading from an earlier version, update your code accordingly.
+  - **Block Requirement for `start_listening`:**  
+    The `start_listening` method now requires a block. If no block is provided, the method logs an error and exits without processing messages. Ensure you pass a block to handle incoming CAN messages:
+    ```ruby
+    messenger.start_listening do |message|
+      # Process the message here
+      puts "Received: #{message}"
+    end
+    ```
+
+- **Threading & Socket Management:**
+
+  - **Blocking Behavior:** The gem uses blocking socket calls and continuously listens for messages. Be sure to manage the listener's lifecycle appropriately,especially if using it in a multi-threaded application. Always call `stop_listening` to gracefully shut down the listener.
+  - **Resource Cleanup:** The socket is automatically closed when the listening loop terminates. However, you should ensure that your application stops the listener to avoid resource leaks.
+
+- **Logging:**
+
+  - **Default Logger:** By default, if no logger is provided, the gem logs to standard output. For more controlled logging, pass a custom logger when initializing the Messenger.
+
+- **CAN Frame Format Assumptions:**
+  - The gem expects a standard CAN frame format with a minimum frame size and specific layout (e.g., the first 4 bytes for the CAN ID, followed by a byte indicating data length, etc.). If you work with non-standard frames, you may need to adjust the implementation.
+
+By keeping these points in mind, you can avoid common pitfalls and ensure that `can_messenger` is integrated smoothly into your project.
+
 ## Features
 
-- **Send CAN Messages**: Send data to specified CAN IDs.
+- **Send CAN Messages**: Send CAN messages with a specified ID.
 - **Receive CAN Messages**: Continuously listen for messages on a CAN interface.
 - **Logging**: Logs errors and events for debugging and troubleshooting.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
-
-To install this gem onto your local machine, run:
-
-```bash
-bundle exec rake install
-```
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test:rspec` to run the tests.
 
 ## Contributing
 

data/lib/can_messenger/messenger.rb

@@ -11,18 +11,22 @@ module CanMessenger
   # It supports sending messages with specific CAN IDs and listening for incoming messages.
   #
   # @example
-  #   socket = CanMessenger::Messenger.new('can0')
-  #   socket.send_can_message(0x123, [0xDE, 0xAD, 0xBE, 0xEF])
-  #   socket.start_listening do |message|
+  #   messenger = CanMessenger::Messenger.new(interface_name: 'can0')
+  #   messenger.send_can_message(id: 0x123, data: [0xDE, 0xAD, 0xBE, 0xEF])
+  #   messenger.start_listening do |message|
   #     puts "Received: ID=#{message[:id]}, Data=#{message[:data].map { |b| '0x%02X' % b }}"
   #   end
   class Messenger
+    FRAME_SIZE = 16
+    MIN_FRAME_SIZE = 8
+    TIMEOUT = [1, 0].pack("l_2")
     # Initializes a new Messenger instance.
     #
-    # @param [String] can_interface The CAN interface to use (e.g., 'can0').
-    # @param [Logger] logger Optional logger for error handling and debug information.
-    def initialize(can_interface, logger = nil)
-      @can_interface = can_interface
+    # @param [String] interface_name The CAN interface to use (e.g., 'can0').
+    # @param [Logger, nil] logger Optional logger for error handling and debug information.
+    # @return [void]
+    def initialize(interface_name:, logger: nil)
+      @can_interface = interface_name
       @logger = logger || Logger.new($stdout)
       @listening = true # Control flag for listening loop
     end
@@ -32,11 +36,11 @@ module CanMessenger
     # @param [Integer] id The CAN ID of the message.
     # @param [Array<Integer>] data The data bytes of the CAN message.
     # @return [void]
-    def send_can_message(id, data)
+    def send_can_message(id:, data:)
       hex_id = format("%03X", id)
       hex_data = data.map { |byte| format("%02X", byte) }.join
       command = "cansend #{@can_interface} #{hex_id}##{hex_data}"
-      system(command)
+      system(command) # @todo validate command status
     rescue StandardError => e
       @logger.error("Error sending CAN message (ID: #{id}): #{e}")
     end
@@ -44,25 +48,23 @@ module CanMessenger
     # Continuously listens for CAN messages on the specified interface.
     #
     # This method listens for incoming CAN messages and applies an optional filter.
-    # The filter can be a specific CAN ID or a range of IDs. Only messages that match
-    # the filter are yielded to the provided block.
+    # The filter can be a specific CAN ID, a range of IDs, or an array of IDs.
+    # Only messages that match the filter are yielded to the provided block.
     #
-    # @param [Integer, Range, nil] filter Optional filter for CAN IDs. Pass a single ID (e.g., 0x123)
-    #   or a range (e.g., 0x100..0x200). If no filter is provided, all messages are processed.
-    # @yield [Hash] Each received message in the format { id: Integer, data: Array<Integer> }.
+    # @param [Integer, Range, Array<Integer>, nil] filter Optional filter for CAN IDs.
+    #   Pass a single ID (e.g., 0x123), a range (e.g., 0x100..0x200), or an array of IDs.
+    #   If no filter is provided, all messages are processed.
+    # @yield [message] Yields each received CAN message as a hash with keys:
+    #   - `:id` [Integer] the CAN message ID
+    #   - `:data` [Array<Integer>] the message data bytes
     # @return [void]
-    def start_listening(filter: nil)
-      @logger.info("Started listening on #{@can_interface}")
-      socket = create_socket
-      while @listening
-        message = receive_message(socket)
-        next if message.nil? # Skip if no message received
-        next if filter && !matches_filter?(message[:id], filter) # Apply filter if specified
-
-        yield(message)
+    def start_listening(filter: nil, &block)
+      return @logger.error("No block provided to handle messages.") unless block_given?
+
+      with_socket do |socket|
+        @logger.info("Started listening on #{@can_interface}")
+        process_message(socket, filter, &block) while @listening
       end
-    ensure
-      socket&.close
     end
 
     # Stops the listening loop by setting @listening to false.
@@ -76,28 +78,68 @@ module CanMessenger
 
     private
 
+    # Yields an open CAN socket to the given block.
+    #
+    # Opens a socket and, if successful, yields it to the block.
+    # If the socket cannot be opened, logs an error and returns.
+    #
+    # @yield [socket] An open CAN socket.
+    # @return [void]
+    def with_socket
+      socket = open_can_socket
+      return @logger.error("Failed to open socket, cannot continue listening.") if socket.nil?
+
+      yield socket
+    ensure
+      socket&.close
+    end
+
+    # Processes a single CAN message.
+    #
+    # Reads a message from the socket, applies the filter, and yields the message if appropriate.
+    # If an error occurs during processing, it logs the error.
+    #
+    # @param socket [Socket] The CAN socket.
+    # @param filter [Integer, Range, Array<Integer>, nil] Optional filter for CAN IDs.
+    # @yield [message] Yields the message if it passes filtering.
+    # @return [void]
+    def process_message(socket, filter)
+      message = receive_message(socket: socket)
+      return if message.nil?
+      return if filter && !matches_filter?(message_id: message[:id], filter: filter)
+
+      yield(message)
+    rescue StandardError => e
+      @logger.error("Unexpected error in listening loop: #{e.message}")
+    end
+
     # Creates and configures a CAN socket.
     #
-    # @return [Socket] The configured CAN socket.
-    def create_socket
+    # @return [Socket, nil] The configured CAN socket, or nil if the socket cannot be opened.
+    def open_can_socket
       socket = Socket.open(Socket::PF_CAN, Socket::SOCK_RAW, Socket::CAN_RAW)
       socket.bind(Socket.pack_sockaddr_can(@can_interface))
-      socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, [1, 0].pack("l_2"))
+      socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, TIMEOUT)
       socket
     rescue StandardError => e
       @logger.error("Error creating CAN socket on interface #{@can_interface}: #{e}")
+      nil
     end
 
-    # Receives a CAN message from the socket and parses it.
+    # Receives a CAN message from the given socket and parses it.
+    #
+    # This method attempts to read a frame from the provided CAN socket. It returns a parsed
+    # message hash in the format `{ id: Integer, data: Array<Integer> }` if a valid frame is received.
+    # If no frame is received, or if an error occurs, the method returns `nil`.
     #
-    # @param [Socket] socket The CAN socket to read from.
-    # @return [Hash, nil] Parsed message in the format { id: Integer, data: Array<Integer> },
-    # or nil if no message is received or an error occurs.
-    def receive_message(socket)
-      frame = socket.recv(16)
-      return nil if frame.nil? || frame.size < 8
+    # @param socket [Socket] The CAN socket to read from.
+    # @return [{ id: Integer, data: Array<Integer> }, nil] A hash representing the CAN message, or `nil` if no message
+    #   is received or an error occurs.
+    def receive_message(socket:)
+      frame = socket.recv(FRAME_SIZE)
+      return nil if frame.nil? || frame.size < MIN_FRAME_SIZE
 
-      parse_frame(frame)
+      parse_frame(frame: frame)
     rescue IO::WaitReadable
       nil
     rescue StandardError => e
@@ -108,41 +150,38 @@ module CanMessenger
     # Parses a raw CAN frame into a message hash.
     #
     # @param [String] frame The raw CAN frame.
-    # @return [Hash, nil] Parsed message with :id and :data keys, or nil if the frame is incomplete.
-    def parse_frame(frame)
-      return nil unless frame && frame.size >= 8
+    # @return [{ id: Integer, data: Array<Integer> }, nil] Parsed message with :id and :data keys,
+    #   or nil if the frame is incomplete or an error occurs.
+    def parse_frame(frame:)
+      return nil unless frame && frame.size >= MIN_FRAME_SIZE
 
       id = frame[0..3].unpack1("L>") & 0x1FFFFFFF
       data_length = frame[4].ord & 0x0F
-      data = (frame[8, data_length].unpack("C*") if frame.size >= 8 + data_length)
-
+      data = (frame[MIN_FRAME_SIZE, data_length].unpack("C*") if frame.size >= MIN_FRAME_SIZE + data_length)
       { id: id, data: data }
     rescue StandardError => e
       @logger.error("Error parsing CAN frame: #{e}")
       nil
     end
 
-    # Checks if a message ID matches the given filter.
+    # Checks whether the given message ID matches the specified filter.
+    #
+    # The filter can be one of the following:
+    # - An Integer, which requires an exact match.
+    # - A Range of Integers, where the message ID must fall within the range.
+    # - An Array of Integers, where the message ID must be included in the array.
     #
-    # Supported filters:
-    # - A single ID (e.g., 0x123)
-    # - A range of IDs (e.g., 0x100..0x200)
-    # - An array of IDs (e.g., [0x123, 0x200, 0x300])
+    # If the filter is nil or unrecognized, the method returns true.
     #
-    # @param [Integer] message_id The ID of the incoming CAN message.
-    # @param [Integer, Range, Array<Integer>, nil] filter The filter to apply.
-    #   If nil, the method always returns true.
-    # @return [Boolean] True if the message ID matches the filter, false otherwise.
-    def matches_filter?(message_id, filter)
+    # @param message_id [Integer] The ID of the incoming CAN message.
+    # @param filter [Integer, Range, Array<Integer>, nil] The filter to apply.
+    # @return [Boolean] Returns true if the message ID matches the filter otherwise false.
+    def matches_filter?(message_id:, filter:)
       case filter
-      when Integer
-        message_id == filter
-      when Range
-        filter.cover?(message_id)
-      when Array
-        filter.include?(message_id)
-      else
-        true # No filter or unrecognized filter
+      when Integer then message_id == filter
+      when Range   then filter.cover?(message_id)
+      when Array   then filter.include?(message_id)
+      else true
       end
     end
   end

data/lib/can_messenger/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CanMessenger
-  VERSION = "0.2.3"
+  VERSION = "1.0.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: can_messenger
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 1.0.3
 platform: ruby
 authors:
 - fk1018
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-02-01 00:00:00.000000000 Z
+date: 2025-02-10 00:00:00.000000000 Z
 dependencies: []
 description: CanMessenger provides an interface to send and receive messages over
   the CAN bus, useful for applications requiring CAN communication in Ruby.
@@ -30,6 +30,7 @@ metadata:
   homepage_uri: https://github.com/fk1018/can_messenger
   source_code_uri: https://github.com/fk1018/can_messenger
   changelog_uri: https://github.com/fk1018/can_messenger/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths: