can_messenger 1.0.3 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3c1f6bf2353eb4b67b93f9aa9e167a4474b8c65cc1abe2327b520d04695cec2
-  data.tar.gz: 6afe7242348e786084de8c6d8afe25f18727ac57b2eeea727518ddd77d53330a
+  metadata.gz: 67c064d4b8899c012642e83b9c348cf72da13eb136bc81283a2acb7116e79897
+  data.tar.gz: ddb8c322325800be6b03813510e1831348e724967e4f05daa9ac0c2b5b32dad3
 SHA512:
-  metadata.gz: 7cd537434d6c9f0d41a6a9ad6dd37229bb569057d9b9e259ac301792e71b629df1b66f2ece6c3d5606e7224410d4f42d1c2488894f5341faecb551e46b222140
-  data.tar.gz: 18620bf7cc07a7694438b0e3da277a3b96d4767cb87d36c5310920dbce5976cc21971e4c3e572869c99ee3a37a7eac7e9996f7948f2d5d2001875b9dead5f4c1
+  metadata.gz: 3d248a72be8fb4b407fa4b79f42fc291658b39340db84c255440cd33b465c02ca7a2d6bf9274a1b52cae8b4cb3b4890d0d2562238040d2365649c1d7d7e0300e
+  data.tar.gz: 7749d6a7544e43db00dfec4a44a967362b449b78bb657da2f7e3afefc04956a466a9348c9414f05c2b72669858e8cecc27f8ac0b32fa2d6c8b58cbaca492e041

data/README.md

@@ -1,22 +1,16 @@
 # 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`:
-
-```bash
-sudo apt install can-utils
-```
-
 To install `can_messenger`, add it to your application's Gemfile:
 
 ```ruby
@@ -55,45 +49,51 @@ To send a message:
 messenger.send_can_message(id: 0x123, data: [0xDE, 0xAD, 0xBE, 0xEF])
 ```
 
-### Receiving CAN Messages
+> **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.
 
-To listen for incoming messages, set up a listener:
+If you need to send an extended CAN frame (29-bit ID), set extended_id: true. The gem then sets the Extended Frame Format (EFF) bit automatically:### Receiving CAN Messages
 
 ```ruby
-messenger.start_listening do |message|
-    puts "Received: ID=#{message[:id]}, Data=#{message[:data]}"
-end
+messenger.send_can_message(id: 0x123456, data: [0x01, 0x02, 0x03], extended_id: true)
 ```
 
-#### Listening with Filters
+### Listen to CAN Messages
 
-The `start_listening` method supports filtering incoming messages based on CAN ID:
-
-Single CAN ID:
+To listen for incoming messages, set up a listener:
 
 ```ruby
-messenger.start_listening(filter: 0x123) do |message|
-  puts "Received filtered message: #{message}"
+messenger.start_listening do |msg|
+  puts "Received ID=0x#{msg[:id].to_s(16)}, Extended=#{msg[:extended]}, Data=#{msg[:data]}"
 end
 ```
 
-Range of CAN IDs:
+#### Listening with Filters
 
-```ruby
-messenger.start_listening(filter: 0x100..0x200) do |message|
-  puts "Received filtered message: #{message}"
-end
+The `start_listening` method supports filtering incoming messages based on CAN ID:
 
-```
+- Single CAN ID:
 
-Array of CAN IDs:
+  ```ruby
+  messenger.start_listening(filter: 0x123) do |message|
+    puts "Received filtered message: #{message}"
+  end
+  ```
 
-```ruby
-messenger.start_listening(filter: [0x123, 0x456, 0x789]) do |message|
-  puts "Received filtered message: #{message}"
-end
+- Range of CAN IDs:
 
-```
+  ```ruby
+  messenger.start_listening(filter: 0x100..0x200) 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
 
@@ -109,51 +109,56 @@ 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, use:
+  - **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` now require named parameters:
+
+    Similarly, methods like `send_can_message` use 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.
+
+    If 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:
+    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|
-      # 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.
+  - **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:** 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.
+  - **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:**
-  - 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.
+  - 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
 
@@ -161,7 +166,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"
@@ -16,31 +15,34 @@ module CanMessenger
   #   messenger.start_listening do |message|
   #     puts "Received: ID=#{message[:id]}, Data=#{message[:data].map { |b| '0x%02X' % b }}"
   #   end
-  class Messenger
+  class Messenger # rubocop:disable Metrics/ClassLength
     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
+    def send_can_message(id:, data:, extended_id: false)
+      with_socket do |socket|
+        frame = build_can_frame(id: id, data: data, extended_id: extended_id)
+        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,65 @@ 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.
+    #
+    # @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.
     #
-    # 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 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:, extended_id: false)
+      raise ArgumentError, "CAN data cannot exceed 8 bytes" if data.size > 8
+
+      # Mask the ID to 29 bits
+      can_id = id & 0x1FFFFFFF
+
+      # If extended_id == true, set bit 31 (CAN_EFF_FLAG)
+      can_id |= 0x80000000 if extended_id
+
+      # Pack the 4‐byte ID (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 (4 for ID, 1 for DLC, 3 padding, 8 data)
+      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 +149,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,39 +161,55 @@ 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.
-    def parse_frame(frame:)
+    # @param [String] frame
+    # @return [Hash, nil]
+    def parse_frame(frame:) # rubocop:disable Metrics/MethodLength
       return nil unless frame && frame.size >= MIN_FRAME_SIZE
 
-      id = frame[0..3].unpack1("L>") & 0x1FFFFFFF
+      raw_id = unpack_frame_id(frame: frame)
+
+      # Determine if EFF bit is set
+      extended = raw_id.anybits?(0x80000000)
+      # or raw_id.anybits?(0x80000000) if your Ruby version supports `Integer#anybits?`
+
+      # Now mask off everything except the lower 29 bits
+      id = raw_id & 0x1FFFFFFF
+
+      # DLC is the lower 4 bits of byte 4
       data_length = frame[4].ord & 0x0F
-      data = (frame[MIN_FRAME_SIZE, data_length].unpack("C*") if frame.size >= MIN_FRAME_SIZE + data_length)
-      { id: id, data: data }
+
+      # Extract data
+      data = if frame.size >= MIN_FRAME_SIZE + data_length
+               frame[MIN_FRAME_SIZE, data_length].unpack("C*")
+             else
+               []
+             end
+
+      { id: id, data: data, extended: extended }
     rescue StandardError => e
       @logger.error("Error parsing CAN frame: #{e}")
       nil
     end
 
+    def unpack_frame_id(frame:)
+      if @endianness == :big
+        frame[0..3].unpack1("L>")
+      else
+        frame[0..3].unpack1("V")
+      end
+    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.3"
+  VERSION = "1.2.0"
 end

metadata

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