can_messenger 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d26615bdfc66cb0379649692d151278aea8056338510b2d73f144f9d0fe0fe4
-  data.tar.gz: 1259bc700f8adf69e1de5f73cdd1dcbef783612b081be9757a31e918855e1b2a
+  metadata.gz: 8a3eb889a0115b86ec0c286505b92919e55271f7c95e5423ee7216bd49587237
+  data.tar.gz: 97806e21ddccdcd8815219de47ed0ba0f6acad5182b878db7b2b19b1aa9cde95
 SHA512:
-  metadata.gz: a79e6a61508e0915d1b52e2e31c1b7104597c46db9d21c838952acac87060efe88fb4914d9ad64e4ac7c63287ef32a8b0a927f4b494c0212aed95cdd198ff693
-  data.tar.gz: 61904213c26ef9b468a4083af58cbf00c95102b5ee841a943b3e559504d324234d3b57d3a1b99a829141a0f629705c6b3240e7d02f8f0081d004b86684088459
+  metadata.gz: 61c5455b82b6b707885d0babaaea5643b3e0587f4389850dd51aa5956587ca2ea25a040136d075c5d8a01590e8ab9abf445dd1d34b77b0c8556958cefffe8bbe
+  data.tar.gz: 0ec5d24c6612c889f472b201037b533b0ac612a7826dfbc2d45ed218f5f6600d0d8e366c0ce90dd04c28d2c421450af28832bac1984223c0da12b512e3b4ff94

data/README.md

@@ -1,20 +1,26 @@
 # CanMessenger
 
-[![Gem Version](https://badge.fury.io/rb/can_messenger.svg?icon=si%3Arubygems&icon_color=%23e77682)](https://badge.fury.io/rb/can_messenger)
+[![Gem Version](https://badge.fury.io/rb/can_messenger.svg?icon=si%3Arubygems&icon_color=%23e77682&123)](https://badge.fury.io/rb/can_messenger)
 [![Build Status](https://github.com/fk1018/can_messenger/actions/workflows/ruby.yml/badge.svg)](https://github.com/fk1018/can_messenger/actions)
 [![Test Coverage](https://codecov.io/gh/fk1018/can_messenger/branch/main/graph/badge.svg)](https://codecov.io/gh/fk1018/can_messenger)
 ![Status](https://img.shields.io/badge/status-stable-green)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 ![Gem Total Downloads](https://img.shields.io/gem/dt/can_messenger)
 
-`can_messenger` is a Ruby gem that provides an interface for communicating over the CAN bus, allowing users to send and receive CAN messages. This gem is designed for developers who need an easy way to interact with CAN-enabled devices.
+`can_messenger` is a Ruby gem that provides an interface for communicating over the CAN bus, allowing users to send and receive CAN messages `via raw SocketCAN sockets`. This gem is designed for developers who need an easy way to interact with CAN-enabled devices on Linux.
 
 ## Installation
 
-This gem relies on `cansend` from the `can-utils` package, which is typically available on Linux-based systems. Make sure to install `can-utils` before using `can_messenger`:
+Ensure you have `SocketCAN` available on your system. Typically on Linux (e.g., Debian/Ubuntu), you install SocketCAN support with:
 
 ```bash
-sudo apt install can-utils
+sudo apt-get install net-tools iproute2
+```
+
+Then bring up your CAN interface (e.g., `can0`) using `ip` commands or a tool like `can-utils` (though this gem no longer depends on `cansend`):
+
+```bash
+sudo ip link set can0 up type can bitrate 500000
 ```
 
 To install `can_messenger`, add it to your application's Gemfile:
@@ -55,13 +61,15 @@ To send a message:
 messenger.send_can_message(id: 0x123, data: [0xDE, 0xAD, 0xBE, 0xEF])
 ```
 
+> **Note:** Under the hood, the gem now writes CAN frames to a raw socket instead of calling `cansend`. No external dependencies are required beyond raw-socket permissions.
+
 ### Receiving CAN Messages
 
 To listen for incoming messages, set up a listener:
 
 ```ruby
 messenger.start_listening do |message|
-    puts "Received: ID=#{message[:id]}, Data=#{message[:data]}"
+  puts "Received: ID=#{message[:id]}, Data=#{message[:data]}"
 end
 ```
 
@@ -69,31 +77,29 @@ end
 
 The `start_listening` method supports filtering incoming messages based on CAN ID:
 
-Single CAN ID:
-
-```ruby
-messenger.start_listening(filter: 0x123) do |message|
-  puts "Received filtered message: #{message}"
-end
-```
-
-Range of CAN IDs:
+- Single CAN ID:
 
-```ruby
-messenger.start_listening(filter: 0x100..0x200) do |message|
-  puts "Received filtered message: #{message}"
-end
+  ```ruby
+  messenger.start_listening(filter: 0x123) do |message|
+    puts "Received filtered message: #{message}"
+  end
+  ```
 
-```
+- Range of CAN IDs:
 
-Array of CAN IDs:
+  ```ruby
+  messenger.start_listening(filter: 0x100..0x200) do |message|
+    puts "Received filtered message: #{message}"
+  end
+  ```
 
-```ruby
-messenger.start_listening(filter: [0x123, 0x456, 0x789]) do |message|
-  puts "Received filtered message: #{message}"
-end
+- Array of CAN IDs:
 
-```
+  ```ruby
+  messenger.start_listening(filter: [0x123, 0x456, 0x789]) do |message|
+    puts "Received filtered message: #{message}"
+  end
+  ```
 
 ### Stopping the Listener
 
@@ -103,15 +109,62 @@ To stop listening, use:
 messenger.stop_listening
 ```
 
+## Important Considerations
+
+Before using `can_messenger`, please note the following:
+
+- **Environment Requirements:**
+
+  - **SocketCAN** must be available on your Linux system.
+  - **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:
+
+    ```ruby
+    messenger = CanMessenger::Messenger.new(interface_name: 'can0')
+    ```
+
+    Similarly, methods like `send_can_message` use named parameters:
+
+    ```ruby
+    messenger.send_can_message(id: 0x123, data: [0xDE, 0xAD, 0xBE, 0xEF])
+    ```
+
+    If upgrading from an earlier version, update your code accordingly.
+
+  - **Block Requirement for `start_listening`:**  
+    The `start_listening` method requires a block. If no block is provided, the method logs an error and exits without processing messages:
+    ```ruby
+    messenger.start_listening do |message|
+      puts "Received: #{message}"
+    end
+    ```
+
+- **Threading & Socket Management:**
+
+  - **Blocking Behavior:** The gem uses blocking socket calls and continuously listens for messages. Manage the listener’s lifecycle appropriately, especially in multi-threaded environments. Always call `stop_listening` to gracefully shut down the listener.
+  - **Resource Cleanup:** The socket is automatically closed when the listening loop terminates. Stop the listener to avoid resource leaks.
+
+- **Logging:**
+
+  - **Default Logger:** If no logger is provided, logs go to standard output. Provide a custom logger if you want more control.
+
+- **CAN Frame Format Assumptions:**
+  - By default, the gem uses **big-endian** packing for CAN IDs. If you integrate with a system using little-endian, you may need to adjust or specify an endianness in the code.
+  - The gem expects a standard CAN frame layout (16 bytes total, with the first 4 for the ID, followed by 1 byte for DLC, 3 bytes of padding, and up to 8 bytes of data). If you work with non-standard frames or CAN FD (64-byte data), you’ll need to customize the parsing/sending logic.
+
 ## Features
 
-- **Send CAN Messages**: Send CAN messages with a specified ID.
+- **Send CAN Messages**: Send CAN messages (up to 8 data bytes).
 - **Receive CAN Messages**: Continuously listen for messages on a CAN interface.
-- **Logging**: Logs errors and events for debugging and troubleshooting.
+- **Filtering**: Optional ID filters for incoming messages (single ID, range, or array).
+- **Logging**: Logs errors and events for debugging/troubleshooting.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test:rspec` to run the tests.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test:rspec` to execute the test suite.
 
 ## Contributing
 
@@ -119,7 +172,7 @@ Bug reports and pull requests are welcome on GitHub at [https://github.com/fk101
 
 ## License
 
-The gem is available as open-source under the terms of the MIT License.
+The gem is available as open-source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## Author
 

data/lib/can_messenger/messenger.rb

@@ -1,4 +1,3 @@
-# lib/can_messenger/messenger.rb
 # frozen_string_literal: true
 
 require "socket"
@@ -20,27 +19,30 @@ module CanMessenger
     FRAME_SIZE = 16
     MIN_FRAME_SIZE = 8
     TIMEOUT = [1, 0].pack("l_2")
+
     # Initializes a new Messenger instance.
     #
     # @param [String] interface_name The CAN interface to use (e.g., 'can0').
     # @param [Logger, nil] logger Optional logger for error handling and debug information.
+    # @param [Symbol] endianness The endianness of the CAN ID (default: :big) can be :big or :little.
     # @return [void]
-    def initialize(interface_name:, logger: nil)
-      @can_interface = interface_name
+    def initialize(interface_name:, logger: nil, endianness: :big)
+      @interface_name = interface_name
       @logger = logger || Logger.new($stdout)
       @listening = true # Control flag for listening loop
+      @endianness    = endianness # :big or :little
     end
 
-    # Sends a CAN message using the `cansend` command.
+    # Sends a CAN message by writing directly to a raw CAN socket
     #
-    # @param [Integer] id The CAN ID of the message.
-    # @param [Array<Integer>] data The data bytes of the CAN message.
+    # @param [Integer] id The CAN ID of the message (up to 29 bits for extended IDs).
+    # @param [Array<Integer>] data The data bytes of the CAN message (0 to 8 bytes).
     # @return [void]
     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) # @todo validate command status
+      with_socket do |socket|
+        frame = build_can_frame(id: id, data: data)
+        socket.write(frame)
+      end
     rescue StandardError => e
       @logger.error("Error sending CAN message (ID: #{id}): #{e}")
     end
@@ -62,7 +64,7 @@ module CanMessenger
       return @logger.error("No block provided to handle messages.") unless block_given?
 
       with_socket do |socket|
-        @logger.info("Started listening on #{@can_interface}")
+        @logger.info("Started listening on #{@interface_name}")
         process_message(socket, filter, &block) while @listening
       end
     end
@@ -73,31 +75,62 @@ module CanMessenger
     # @return [void]
     def stop_listening
       @listening = false
-      @logger.info("Stopped listening on #{@can_interface}")
+      @logger.info("Stopped listening on #{@interface_name}")
     end
 
     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.
+    # Opens a socket, yields it, and closes it when done.
     #
     # @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?
+      return @logger.error("Failed to open socket, cannot continue operation.") if socket.nil?
 
       yield socket
     ensure
       socket&.close
     end
 
-    # Processes a single CAN message.
+    # Creates and configures a CAN socket bound to @interface_name.
     #
-    # 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.
+    # @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(@interface_name))
+      socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, TIMEOUT)
+      socket
+    rescue StandardError => e
+      @logger.error("Error creating CAN socket on interface #{@interface_name}: #{e}")
+      nil
+    end
+
+    # Builds a raw CAN frame for SocketCAN, big-endian ID, 1-byte DLC, up to 8 data bytes, and 3 padding bytes.
+    #
+    # @param id [Integer] the CAN ID
+    # @param data [Array<Integer>] up to 8 bytes
+    # @return [String] a 16-byte string representing a classic CAN frame
+    def build_can_frame(id:, data:)
+      raise ArgumentError, "CAN data cannot exceed 8 bytes" if data.size > 8
+
+      # Apply 29-bit mask if extended ID is used
+      can_id = id & 0x1FFFFFFF
+
+      # Pack the ID as 4 bytes in big-endian or little-endian
+      id_bytes = @endianness == :big ? [can_id].pack("L>") : [can_id].pack("V")
+
+      # 1 byte for DLC, then 3 bytes of padding
+      dlc_and_pad = [data.size, 0, 0, 0].pack("C*")
+
+      # Up to 8 data bytes, pad with 0 if fewer
+      payload = data.pack("C*").ljust(8, "\x00")
+
+      # Total 16 bytes
+      id_bytes + dlc_and_pad + payload
+    end
+
+    # Processes a single CAN message from `socket`. Applies filter, yields to block if it matches.
     #
     # @param socket [Socket] The CAN socket.
     # @param filter [Integer, Range, Array<Integer>, nil] Optional filter for CAN IDs.
@@ -113,28 +146,10 @@ module CanMessenger
       @logger.error("Unexpected error in listening loop: #{e.message}")
     end
 
-    # Creates and configures a CAN socket.
+    # Reads a frame from the socket and parses it into { id:, data: }, or nil if none is received.
     #
-    # @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, TIMEOUT)
-      socket
-    rescue StandardError => e
-      @logger.error("Error creating CAN socket on interface #{@can_interface}: #{e}")
-      nil
-    end
-
-    # 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 [{ id: Integer, data: Array<Integer> }, nil] A hash representing the CAN message, or `nil` if no message
-    #   is received or an error occurs.
+    # @param socket [Socket]
+    # @return [Hash, nil]
     def receive_message(socket:)
       frame = socket.recv(FRAME_SIZE)
       return nil if frame.nil? || frame.size < MIN_FRAME_SIZE
@@ -143,20 +158,24 @@ module CanMessenger
     rescue IO::WaitReadable
       nil
     rescue StandardError => e
-      @logger.error("Error receiving CAN message on interface #{@can_interface}: #{e}")
+      @logger.error("Error receiving CAN message on interface #{@interface_name}: #{e}")
       nil
     end
 
-    # Parses a raw CAN frame into a message hash.
+    # Parses a raw CAN frame into { id: Integer, data: Array<Integer> }, or nil on error.
     #
-    # @param [String] frame The raw CAN frame.
-    # @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.
+    # @param [String] frame
+    # @return [Hash, nil]
     def parse_frame(frame:)
       return nil unless frame && frame.size >= MIN_FRAME_SIZE
 
-      id = frame[0..3].unpack1("L>") & 0x1FFFFFFF
+      # Big-endian ID in bytes [0..3]
+      id = unpack_frame_id(frame: frame)
+
+      # DLC is the lower 4 bits of byte 4
       data_length = frame[4].ord & 0x0F
+
+      # Data follows at byte index 8, up to data_length bytes
       data = (frame[MIN_FRAME_SIZE, data_length].unpack("C*") if frame.size >= MIN_FRAME_SIZE + data_length)
       { id: id, data: data }
     rescue StandardError => e
@@ -164,18 +183,15 @@ module CanMessenger
       nil
     end
 
+    def unpack_frame_id(frame:)
+      @endianness == :big ? frame[0..3].unpack1("L>") & 0x1FFFFFFF : frame[0..3].unpack1("V") & 0x1FFFFFFF
+    end
+
     # 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.
-    #
-    # If the filter is nil or unrecognized, the method returns true.
-    #
     # @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.
+    # @param filter [Integer, Range, Array<Integer>, nil]
+    # @return [Boolean]
     def matches_filter?(message_id:, filter:)
       case filter
       when Integer then message_id == filter

data/lib/can_messenger/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: can_messenger
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - fk1018
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-02-10 00:00:00.000000000 Z
+date: 2025-02-11 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.