can_messenger 2.3.1 → 2.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69c5314c6880b4bda9d98417e41373982bc5a8bc82c45edce46df8e0df375d08
-  data.tar.gz: 31a3e9ca727c04480f9fffb93ea06118115e69473d4814a0903b7ad842dc046a
+  metadata.gz: 146ac35cbdc1ef83f90ebc6fb0e41385d2c1787cff145aa8ca346ceb606ed9da
+  data.tar.gz: b09ee62d02ddd427688c3fa8e33b39ee633108e504b3675386d3d01f30a02f79
 SHA512:
-  metadata.gz: 21dafa39e0e12683372645b6f8ecd97ed8be8ae011f154810305c177a2b4ab0fbf4c2d0f6b04ccf6907e61c39ebbfbb5fe7013b7863fe5e588ad843d7b525b25
-  data.tar.gz: '08fd4c66a964f99a81e724633265c0809e54582d95a61de95ff8821fc309bf6106b85825fd594313dc9aa32f0b6f3f155dfed87c2ae587c48899bde5065b9f39'
+  metadata.gz: 1072360ce734343ffe92e47c47524f19ca9975705b3d12667e95d1d7ddff980e9ffbcfce630e05c10eacfa07b56dbabd4da0f801cb474d0d639e446f38f8c59e
+  data.tar.gz: d1c4ed455124f0fcf8a18985ad111daa3fe429fe688dc40584a31be439afeb34c5f6a32fb91740e03eaa2f8dbccc83eae0fe14aba18b80ad425d37971f91e643

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [Unreleased]
 
+## [2.3.2] - 2026-10-30
+
+### Changed
+
+- **Breaking:** Require Ruby 4.0.9 or higher and update the Ruby development and CI images.
+- Update the docs toolchain to Node.js 24.22.1 and Docusaurus 3.10.2, refresh locked dependencies, and override vulnerable transitive dependencies with patched versions.
+- Update the locked Ruby JSON dependency to address published security advisories.
+- DBC signals with integral scaling now decode to `Integer` values to preserve precision; fractional scaling continues to return `Float` values.
+- Promote the docs site stable snapshot to `2.3.2`.
+
+### Fixed
+
+- Let the SocketCAN listener stop on an idle bus by bounding receive waits.
+- Preserve remote transmission requests as distinct frames and skip DBC decoding for them.
+- Reject CAN payload elements outside the integer byte range instead of silently wrapping them.
+- Preserve large integer DBC values and round correctly when directly constructed signals use integer scaling factors.
+- Reject malformed DBC scaling, invalid byte order, unsupported metadata directives, and unsupported floating-point signal types with line context.
+- Declare Logger as a runtime dependency so minimal Bundler applications can load the gem.
+- Ship the RBS signatures in the gem and load them explicitly during signature validation.
+
 ## [2.3.1] - 2026-04-15
 
 ### Changed
@@ -200,7 +220,8 @@
 ## [0.1.0] - 2024-11-10
 
 - Initial release
-  [Unreleased]: https://github.com/fk1018/can_messenger/compare/v2.3.1...HEAD
+  [Unreleased]: https://github.com/fk1018/can_messenger/compare/v2.3.2...HEAD
+  [2.3.2]: https://github.com/fk1018/can_messenger/compare/v2.3.1...v2.3.2
   [2.3.1]: https://github.com/fk1018/can_messenger/compare/v2.3.0...v2.3.1
   [2.3.0]: https://github.com/fk1018/can_messenger/compare/v2.2.0...v2.3.0
   [2.2.0]: https://github.com/fk1018/can_messenger/compare/v2.1.0...v2.2.0

data/README.md

@@ -12,7 +12,7 @@
 
 ## Requirements
 
-- Ruby 4.0.1 or higher.
+- Ruby 4.0.9 or higher.
 - Docker (optional, for containerized development without installing Ruby locally).
 
 ## Installation
@@ -57,6 +57,8 @@ To send a message:
 messenger.send_can_message(id: 0x123, data: [0xDE, 0xAD, 0xBE, 0xEF])
 ```
 
+Each payload element must be an integer in `0..255`; invalid bytes raise `ArgumentError`.
+
 > **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.
 > The SocketCAN adapter builds the Linux socket address itself, so it does not depend on Ruby exposing `CAN_RAW` or `pack_sockaddr_can`.
 
@@ -85,6 +87,8 @@ messenger.start_listening do |msg|
 end
 ```
 
+Remote transmission request (RTR) frames include `remote: true`, the requested byte count in `dlc`, and an empty `data` array. They are yielded without DBC decoding because they contain no signal data.
+
 #### Listening with Filters
 
 The `start_listening` method supports filtering incoming messages based on CAN ID:
@@ -138,7 +142,9 @@ end
 If the DBC message definition uses an extended CAN ID, `send_dbc_message` automatically sends it as an extended frame and `start_listening(dbc: ...)` decodes received extended frames back through the same DBC definition.
 If DBC decoding raises because the payload does not match the signal definition, the raw frame is still yielded and includes `decode_error: { class:, message: }`.
 
-Malformed DBC files now fail fast with `ArgumentError` that includes the line number and offending line text. Standard metadata directives such as `VERSION`, `NS_`, `BS_`, `BU_`, `CM_`, `VAL_`, `BA_`, `BA_DEF_`, `BA_DEF_DEF_`, `SIG_VALTYPE_`, and `BO_TX_BU_` are still ignored. Other non-empty directives, including unsupported `BA_*` variants, raise with line context.
+Malformed DBC files fail fast with `ArgumentError` that includes the line number and offending line text. Signal byte order must be `@0` or `@1`, and scaling values must be valid numeric literals. Standard metadata directives such as `VERSION`, `NS_`, `BS_`, `BU_`, `CM_`, `VAL_`, `BA_`, `BA_DEF_`, `BA_DEF_DEF_`, and `BO_TX_BU_` are ignored. `SIG_VALTYPE_` accepts integer type `0`; floating-point types `1` and `2` are unsupported and raise explicitly. Other non-empty directives, including unsupported `BA_*` variants, raise with line context.
+
+Identity-scaled integer signals preserve all 64 bits during encoding and decoding. Integral scaling returns `Integer` values; fractional scaling returns `Float` values. Directly constructed signals also round correctly with integer scaling factors.
 
 ### Stopping the Listener
 
@@ -148,6 +154,8 @@ To stop listening, use:
 messenger.stop_listening
 ```
 
+The default SocketCAN adapter checks for shutdown at least once per second while the bus is idle. When listening in another thread, join that thread after stopping to wait for socket cleanup.
+
 ### Adapters
 
 `CanMessenger::Messenger` delegates low-level CAN bus operations to an adapter. By default it uses the
@@ -199,7 +207,7 @@ Before using `can_messenger`, please note the following:
     ```
 
 - **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.
+  - **Blocking Behavior:** `start_listening` runs until stopped. The default SocketCAN adapter bounds each receive wait to one second so shutdown also works on an idle bus. Always call `stop_listening` to gracefully shut down the listener; custom adapters should also bound their receive waits.
   - **Resource Cleanup:** The socket is automatically closed when the listening loop terminates. Stop the listener to avoid resource leaks.
 
 - **Logging:**
@@ -278,7 +286,7 @@ If you already have Ruby installed locally, you can still use:
 
 ```bash
 bin/setup
-rbs validate
+rbs -I sig -r logger validate
 bundle exec rake test:rspec
 bundle exec rubocop
 ```

data/lib/can_messenger/adapter/base.rb

@@ -2,11 +2,19 @@
 
 module CanMessenger
   module Adapter
-    # Base adapter defines the interface for CAN bus adapters.
-    # Concrete adapters must implement all of the methods defined here.
+    # Defines the transport interface used by Messenger.
+    #
+    # Provides shared interface, logging, and CAN ID byte-order configuration.
+    # Concrete adapters implement socket creation, frame building, receiving,
+    # and parsing for their transport.
+    #
+    # @abstract Subclass and implement the four transport methods below.
     class Base
       attr_reader :interface_name, :logger, :endianness
 
+      # Detects the host's byte order by comparing native and explicit integer packing.
+      #
+      # @return [Symbol] :little or :big
       def self.native_endianness
         native = pack_uint(1, "I")
         return :little if native == pack_uint(1, "V")
@@ -16,11 +24,26 @@ module CanMessenger
         native.bytes.first == 1 ? :little : :big
       end
 
+      # Packs an unsigned integer for byte-order detection.
+      #
+      # @param [Integer] value The integer to pack
+      # @param [String] template The Array#pack format specifying width and byte order
+      # @return [String] The packed bytes
       def self.pack_uint(value, template)
         [value].pack(template)
       end
       private_class_method :pack_uint
 
+      # Initializes the shared adapter configuration without opening a socket.
+      #
+      # Resolves :native to the host's byte order so transport methods only need
+      # to handle :little and :big.
+      #
+      # @param [String] interface_name The CAN interface to use (e.g., "can0")
+      # @param [Logger] logger The logger for transport errors and diagnostic messages
+      # @param [Symbol, String] endianness CAN ID byte order: native, little, or big
+      # @return [void]
+      # @raise [ArgumentError] If the byte-order setting is unsupported
       def initialize(interface_name:, logger:, endianness: :native)
         @interface_name = interface_name
         @logger = logger
@@ -28,29 +51,64 @@ module CanMessenger
         @endianness = normalized_endianness == :native ? self.class.native_endianness : normalized_endianness
       end
 
-      # Open a socket for the underlying interface.
-      # @return [Object] adapter-specific socket
+      # Opens a socket for the underlying interface.
+      #
+      # Messenger owns the returned socket and closes it after sending or listening.
+      #
+      # @param [Boolean, nil] can_fd Whether to enable CAN FD frames
+      # @return [Object, nil] The adapter-specific socket, or nil if opening fails
+      # @raise [NotImplementedError] If a subclass does not implement this method
       def open_socket(can_fd: false)
         raise NotImplementedError, "open_socket must be implemented in subclasses"
       end
 
-      # Build a frame ready to be written to the socket.
+      # Builds a frame ready to be written to the socket.
+      #
+      # @param [Integer] id The CAN identifier without frame flags
+      # @param [Array<Integer>] data The payload bytes, each in 0..255
+      # @param [Boolean] extended_id Whether to use a 29-bit identifier instead of an 11-bit identifier
+      # @param [Boolean, nil] can_fd Whether to build a CAN FD frame
+      # @return [String] The serialized frame
+      # @raise [NotImplementedError] If a subclass does not implement this method
       def build_can_frame(id:, data:, extended_id: false, can_fd: false)
         raise NotImplementedError, "build_can_frame must be implemented in subclasses"
       end
 
-      # Receive and parse a frame from the socket.
+      # Receives and parses a frame from the socket.
+      #
+      # Implementations should bound their receive wait and return nil on timeout
+      # so Messenger can check whether listening has been stopped.
+      #
+      # @param [Object] socket The adapter-specific socket to read from
+      # @param [Boolean, nil] can_fd Whether CAN FD reception is enabled
+      # @return [Hash, nil] A message with :id, :data, and :extended, or nil when no message is available
+      # @raise [NotImplementedError] If a subclass does not implement this method
       def receive_message(socket:, can_fd: false)
         raise NotImplementedError, "receive_message must be implemented in subclasses"
       end
 
-      # Parse a raw frame string into a message hash.
+      # Parses a raw frame string into a message hash.
+      #
+      # Remote transmission requests should include :remote and :dlc, with empty
+      # :data, so Messenger can distinguish them from frames containing signals.
+      #
+      # @param [String] frame The serialized frame
+      # @param [Boolean, nil] can_fd Whether to parse CAN FD, or nil for adapter-specific detection
+      # @return [Hash, nil] A message with :id, :data, and :extended, or nil if parsing fails
+      # @raise [NotImplementedError] If a subclass does not implement this method
       def parse_frame(frame:, can_fd: false)
         raise NotImplementedError, "parse_frame must be implemented in subclasses"
       end
 
       private
 
+      # Converts a supported byte-order setting to a symbol.
+      #
+      # String settings are case-insensitive and may contain surrounding whitespace.
+      #
+      # @param [Symbol, String] endianness The requested CAN ID byte order
+      # @return [Symbol] :native, :little, or :big
+      # @raise [ArgumentError] If the setting does not name a supported byte order
       def normalize_endianness(endianness)
         normalized = endianness.is_a?(String) ? endianness.strip.downcase.to_sym : endianness
         return normalized if %i[native little big].include?(normalized)

data/lib/can_messenger/adapter/socketcan.rb

@@ -1,29 +1,52 @@
 # frozen_string_literal: true
 
 require "socket"
+require "io/wait"
 require_relative "base"
 require_relative "../constants"
 
 module CanMessenger
   module Adapter
-    # Adapter implementation for Linux SocketCAN interfaces.
+    # Sends and receives frames through Linux SocketCAN raw sockets.
+    #
+    # Supports classic CAN and CAN FD, with CAN ID byte order resolved by Base.
+    # Frame building and parsing can also be used without opening an interface.
+    #
+    # @example Building a classic CAN frame
+    #   adapter = CanMessenger::Adapter::Socketcan.new(interface_name: "can0", logger: Logger.new($stdout))
+    #   frame = adapter.build_can_frame(id: 0x123, data: [0xDE, 0xAD])
+    #   frame.bytesize # => 16
     class Socketcan < Base # rubocop:disable Metrics/ClassLength
+      # Linux protocol and socket-option identifiers for raw CAN and CAN FD support.
       CAN_RAW = 1
       SOL_CAN_BASE = 100
       SOL_CAN_RAW = SOL_CAN_BASE + CAN_RAW
       CAN_RAW_FD_FRAMES = 5
+
+      # Complete frame sizes include the header and the fixed-size payload area.
       FRAME_SIZE = 16
       CANFD_FRAME_SIZE = 72
+      # Both frame layouts place payload bytes after an eight-byte header.
       MIN_FRAME_SIZE = 8
       MAX_FD_DATA = 64
       MAX_STANDARD_ID = 0x7FF
+
+      # sockaddr_can has a native family, alignment padding, interface index, and address union.
       SOCKADDR_CAN_ADDR_SIZE = 16
       SOCKADDR_CAN_SIZE = 24
       SOCKADDR_CAN_PADDING = 2
+      # Kernel receive timeout as a native timeval: seconds followed by microseconds.
       TIMEOUT = [1, 0].pack("l_2")
+      # Raw CAN does not use the protocol-specific address union.
       ZERO_CAN_ADDR = "\x00" * SOCKADDR_CAN_ADDR_SIZE
 
       # Creates and configures a CAN socket bound to the interface.
+      #
+      # Socket creation or configuration errors are logged. Any partially opened
+      # socket is closed before returning nil.
+      #
+      # @param [Boolean, nil] can_fd Whether to enable CAN FD reception and transmission
+      # @return [Socket, nil] The bound socket, or nil if it could not be opened
       def open_socket(can_fd: nil)
         socket = Socket.open(Socket::PF_CAN, Socket::SOCK_RAW, CAN_RAW)
         configure_socket(socket, can_fd: can_fd)
@@ -35,7 +58,19 @@ module CanMessenger
       end
 
       # Builds a raw CAN or CAN FD frame for SocketCAN.
+      #
+      # Sets the extended-frame flag when requested and zero-pads the payload area.
+      # The header records the supplied byte count, excluding that padding.
+      #
+      # @param [Integer] id The CAN identifier without frame flags
+      # @param [Array<Integer>] data Payload bytes in 0..255; at most 8 for classic CAN or 64 for CAN FD
+      # @param [Boolean] extended_id Whether to use a 29-bit identifier instead of an 11-bit identifier
+      # @param [Boolean, nil] can_fd Whether to build a CAN FD frame; nil selects classic CAN
+      # @return [String] A 16-byte classic CAN frame or a 72-byte CAN FD frame
+      # @raise [ArgumentError] If the identifier, payload type, byte values, or payload length are invalid
       def build_can_frame(id:, data:, extended_id: false, can_fd: nil) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/PerceivedComplexity
+        validate_data!(data)
+
         if can_fd
           raise ArgumentError, "CAN FD data cannot exceed #{MAX_FD_DATA} bytes" if data.size > MAX_FD_DATA
         elsif data.size > 8
@@ -63,9 +98,19 @@ module CanMessenger
       end
 
       # Reads a frame from the socket and parses it into a hash.
+      #
+      # Uses a one-second readiness timeout followed by a nonblocking receive so
+      # an idle listener can stop. A timeout or loss of readiness returns nil;
+      # other receive errors are logged and also return nil.
+      #
+      # @param [Socket] socket The bound CAN socket to read from
+      # @param [Boolean, nil] can_fd Whether to reserve space for CAN FD; nil selects classic CAN
+      # @return [Hash, nil] The parsed message, or nil when no frame can be returned
       def receive_message(socket:, can_fd: nil)
+        return nil unless socket.wait_readable(1)
+
         frame_size = can_fd ? CANFD_FRAME_SIZE : FRAME_SIZE
-        frame = socket.recv(frame_size)
+        frame = socket.recv_nonblock(frame_size)
         return nil if frame.nil? || frame.size < MIN_FRAME_SIZE
 
         parse_frame(frame: frame, can_fd: can_fd)
@@ -77,20 +122,27 @@ module CanMessenger
       end
 
       # Parses a raw CAN frame string into a hash with id, data and extended flag.
-      def parse_frame(frame:, can_fd: nil) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/PerceivedComplexity
+      #
+      # The :id excludes frame flags. Remote requests also include :remote => true
+      # and the requested byte count in :dlc, with empty :data. If the header is
+      # present but the declared payload is incomplete, :data is empty.
+      # Parsing errors are logged and return nil.
+      #
+      # @param [String] frame The raw frame bytes, including the header
+      # @param [Boolean, nil] can_fd The frame format, or nil to infer it from the frame size
+      # @return [Hash, nil] The message, or nil if the header is missing or parsing fails
+      def parse_frame(frame:, can_fd: nil) # rubocop:disable Metrics/MethodLength
         return nil unless frame && frame.size >= MIN_FRAME_SIZE
 
-        use_fd = can_fd.nil? ? frame.size >= CANFD_FRAME_SIZE : can_fd
-
         raw_id = unpack_frame_id(frame: frame)
         extended = raw_id.anybits?(Constants::EXTENDED_ID_FLAG)
         id = raw_id & Constants::MAX_EXTENDED_ID
 
-        data_length = if use_fd
-                        frame[4].ord
-                      else
-                        frame[4].ord & 0x0F
-                      end
+        data_length = frame_data_length(frame, can_fd: can_fd)
+
+        if raw_id.anybits?(Constants::REMOTE_TRANSMISSION_REQUEST_FLAG)
+          return { id: id, data: [], extended: extended, remote: true, dlc: data_length }
+        end
 
         data = if frame.size >= MIN_FRAME_SIZE + data_length
                  frame[MIN_FRAME_SIZE, data_length].unpack("C*")
@@ -106,6 +158,20 @@ module CanMessenger
 
       private
 
+      # Reads the declared payload length using the selected frame layout.
+      #
+      # @param [String] frame A frame containing at least the complete header
+      # @param [Boolean, nil] can_fd Whether to use CAN FD, or nil to infer the format from size
+      # @return [Integer] The declared number of payload bytes
+      def frame_data_length(frame, can_fd:)
+        use_fd = can_fd.nil? ? frame.size >= CANFD_FRAME_SIZE : can_fd
+        use_fd ? frame[4].ord : frame[4].ord & 0x0F
+      end
+
+      # Reads the CAN identifier and frame flags using the configured byte order.
+      #
+      # @param [String] frame The raw frame containing the four-byte identifier field
+      # @return [Integer] The identifier with any frame flags still set
       def unpack_frame_id(frame:)
         if endianness == :big
           frame[0..3].unpack1("L>")
@@ -114,6 +180,16 @@ module CanMessenger
         end
       end
 
+      # Binds a socket, sets its kernel receive timeout, and optionally enables CAN FD.
+      #
+      # receive_message also bounds its readiness wait because the kernel timeout
+      # alone does not limit Ruby's wait for a readable socket.
+      #
+      # @param [Socket] socket The newly opened CAN socket
+      # @param [Boolean, nil] can_fd Whether to enable CAN FD frames
+      # @return [void]
+      # @raise [ArgumentError] If the configured interface cannot be resolved
+      # @raise [SystemCallError] If binding or setting a socket option fails
       def configure_socket(socket, can_fd:)
         socket.bind(build_sockaddr_can(interface_index))
         socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, TIMEOUT)
@@ -122,6 +198,10 @@ module CanMessenger
         socket.setsockopt(SOL_CAN_RAW, CAN_RAW_FD_FRAMES, 1)
       end
 
+      # Closes a socket during failed setup without masking the original error.
+      #
+      # @param [Socket, nil] socket The socket to close, if one was created
+      # @return [void]
       def close_socket(socket)
         return unless socket
         return if socket.respond_to?(:closed?) && socket.closed?
@@ -131,6 +211,12 @@ module CanMessenger
         # Ignore close errors so we can report the original failure.
       end
 
+      # Resolves the configured interface name to its Linux interface index.
+      #
+      # Uses Ruby's interface list first, then falls back to the sysfs entry.
+      #
+      # @return [Integer] The positive interface index used for binding
+      # @raise [ArgumentError] If neither lookup can resolve the interface
       def interface_index
         index = interface_index_from_ifaddrs || interface_index_from_sysfs
         return index if index
@@ -138,6 +224,9 @@ module CanMessenger
         raise ArgumentError, "Unknown CAN interface #{interface_name}"
       end
 
+      # Looks up the interface index through Ruby's network-interface enumeration.
+      #
+      # @return [Integer, nil] The index, or nil if unavailable, unsupported, or not found
       def interface_index_from_ifaddrs
         return nil unless Socket.respond_to?(:getifaddrs)
 
@@ -153,6 +242,9 @@ module CanMessenger
         nil
       end
 
+      # Reads the Linux sysfs interface index as a fallback for Ruby's interface lookup.
+      #
+      # @return [Integer, nil] The positive index, or nil if the entry is missing, unreadable, or invalid
       def interface_index_from_sysfs
         ifindex_path = File.join("/sys/class/net", interface_name, "ifindex")
         return nil unless File.file?(ifindex_path)
@@ -163,6 +255,14 @@ module CanMessenger
         nil
       end
 
+      # Packs the native Linux sockaddr_can structure used to bind a raw socket.
+      #
+      # Socket addresses always use host byte order, independently of the byte
+      # order selected for CAN identifiers in frame building and parsing.
+      #
+      # @param [Integer] ifindex The resolved Linux interface index
+      # @return [String] The 24-byte packed socket address
+      # @raise [RuntimeError] If the packed layout does not have the expected size
       def build_sockaddr_can(ifindex)
         can_family = Socket.const_defined?(:AF_CAN) ? Socket::AF_CAN : Socket::PF_CAN
         sockaddr = [can_family, ifindex, ZERO_CAN_ADDR].pack("S!x#{SOCKADDR_CAN_PADDING}i!a#{SOCKADDR_CAN_ADDR_SIZE}")
@@ -171,6 +271,12 @@ module CanMessenger
         raise "sockaddr_can must be #{SOCKADDR_CAN_SIZE} bytes, got #{sockaddr.bytesize}"
       end
 
+      # Checks that an identifier fits the selected CAN frame format without flags.
+      #
+      # @param [Object] id The caller-supplied identifier to validate
+      # @param [Boolean] extended_id Whether the allowed range is 29 bits instead of 11 bits
+      # @return [void]
+      # @raise [ArgumentError] If the identifier is not an integer or lies outside the allowed range
       def validate_can_id!(id, extended_id:)
         raise ArgumentError, "id must be an Integer" unless id.is_a?(Integer)
         raise ArgumentError, "CAN id cannot be negative" if id.negative?
@@ -180,6 +286,21 @@ module CanMessenger
 
         raise ArgumentError, "#{extended_id ? "Extended" : "Standard"} CAN id cannot exceed 0x#{max_id.to_s(16).upcase}"
       end
+
+      # Checks the payload container and each byte before binary packing.
+      #
+      # Explicit validation prevents Array#pack from silently wrapping integers
+      # outside the byte range or coercing noninteger values.
+      #
+      # @param [Object] data The caller-supplied payload to validate
+      # @return [void]
+      # @raise [ArgumentError] If the payload is not an array of integers in 0..255
+      def validate_data!(data)
+        raise ArgumentError, "data must be an Array of byte Integers" unless data.is_a?(Array)
+        return if data.all? { |byte| byte.is_a?(Integer) && byte.between?(0, 255) }
+
+        raise ArgumentError, "data bytes must be Integers between 0 and 255"
+      end
     end
   end
 end

data/lib/can_messenger/constants.rb

@@ -1,9 +1,19 @@
 # frozen_string_literal: true
 
 module CanMessenger
+  # Shared CAN identifier masks and frame flags.
+  #
+  # SocketCAN stores frame flags above the 29 identifier bits. DBC message IDs
+  # also use bit 31 to mark extended frames, so the same flag is used when
+  # translating between DBC definitions and received frames.
   module Constants
+    # Keeps only the 29 identifier bits and removes the frame flags.
     CAN_ID_MASK = 0x1FFFFFFF
+    # Bit 31 selects the extended frame format with a 29-bit identifier.
     EXTENDED_ID_FLAG = 0x80000000
+    # Bit 30 marks a remote request for data, which carries no signal payload.
+    REMOTE_TRANSMISSION_REQUEST_FLAG = 0x40000000
+    # Largest valid extended identifier before any frame flags are added.
     MAX_EXTENDED_ID = 0x1FFFFFFF
   end
 end

data/lib/can_messenger/dbc.rb

@@ -6,6 +6,8 @@ module CanMessenger
   # This class provides functionality to parse DBC files and encode/decode CAN messages
   # according to the signal definitions. DBC files are a standard way to describe
   # CAN network communication.
+  # Integer signals support signed or unsigned values, both byte orders, and scaling.
+  # Unsupported floating-point signal declarations raise instead of being decoded as integers.
   #
   # @example Loading and using a DBC file
   #   dbc = CanMessenger::DBC.load('vehicle.dbc')
@@ -17,7 +19,8 @@ module CanMessenger
   #   # Decode a received CAN frame
   #   decoded = dbc.decode_can(0x123, [0x09, 0xC4, 0xAB, 0x00, 0x00, 0x00, 0x00, 0x00])
   #   # => { name: 'EngineData', signals: { RPM: 2500.0, Temperature: 85.5 } }
-  class DBC
+  class DBC # rubocop:disable Metrics/ClassLength
+    # Metadata directive names that can be skipped; matching uses complete tokens.
     IGNORED_LINE_PREFIXES = %w[
       BO_TX_BU_
       VERSION
@@ -29,12 +32,19 @@ module CanMessenger
       BA_
       BA_DEF_
       BA_DEF_DEF_
-      SIG_VALTYPE_
     ].freeze
 
+    # Numeric tokens allow a sign, decimal point, and optional scientific exponent.
+    NUMBER_PATTERN = /[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?/
+    # Message headers provide the stored identifier, name, payload size, and sender.
     MESSAGE_LINE_PATTERN = /^BO_\s+(\d+)\s+(\w+)\s*:\s*(\d+)\s+\S.*$/
-    SIGNAL_LINE_PATTERN = /^SG_\s+(\w+)\s*:\s*(\d+)\|(\d+)@(\d)([+-])\s*\(([^,]+),([^)]+)\)/
+    # Capture the signal layout and scaling; byte order is restricted to @0 or @1.
+    SIGNAL_LINE_PATTERN = /^SG_\s+(\w+)\s*:\s*(\d+)\|(\d+)@([01])([+-])\s*
+                           \(\s*(#{NUMBER_PATTERN})\s*,\s*(#{NUMBER_PATTERN})\s*\)/x
+    # Type 0 is an integer; types 1 and 2 declare unsupported IEEE float and double signals.
+    SIGNAL_VALUE_TYPE_PATTERN = /\ASIG_VALTYPE_\s+\d+\s+\w+\s*:\s*(\d+)\s*;\z/
 
+    # @return [Hash<String, Message>] Parsed message definitions keyed by their names
     attr_reader :messages
 
     # Loads a DBC file from disk and parses its contents.
@@ -50,6 +60,8 @@ module CanMessenger
     # Initializes a new DBC instance.
     #
     # @param [String] content The DBC file content to parse (optional)
+    # @return [void]
+    # @raise [ArgumentError] If the content contains a malformed or unsupported definition
     def initialize(content = "")
       @messages = {}
       parse(content) unless content.empty?
@@ -60,9 +72,11 @@ module CanMessenger
     # This method processes each line of the DBC content, identifying message
     # definitions (BO_) and signal definitions (SG_). It builds a complete
     # message structure with all associated signals.
+    # Existing messages are retained unless a new definition uses the same name.
     #
     # @param [String] content The DBC file content to parse
     # @return [void]
+    # @raise [ArgumentError] If a definition is malformed or unsupported, with line number and text
     def parse(content) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       current = nil
       in_namespace_section = false
@@ -70,11 +84,10 @@ module CanMessenger
       # The parser is intentionally strict so malformed DBC files fail early with line context.
       # We still ignore a small allowlist of standard metadata directives that do not affect encode/decode.
       content.each_line.with_index(1) do |line, line_number|
-        raw_line = line.rstrip
-        stripped_line = raw_line.strip
+        stripped_line = line.strip
 
         if in_namespace_section
-          next if raw_line.match?(/^\s+/)
+          next if line.match?(/^\s+\S/)
 
           in_namespace_section = false
         end
@@ -99,6 +112,8 @@ module CanMessenger
           raise_parse_error("Invalid signal definition", line_number, stripped_line) unless sig
 
           current.signals << sig
+        elsif stripped_line.start_with?("SIG_VALTYPE_")
+          validate_signal_value_type(stripped_line, line_number)
         else
           raise_parse_error("Unsupported or malformed DBC line", line_number, stripped_line)
         end
@@ -127,24 +142,21 @@ module CanMessenger
     #
     # @param [String] line A single line from the DBC file
     # @param [Message] _current The current message being processed (unused but kept for API consistency)
-    # @return [Signal, nil] A Signal object if the line matches, nil otherwise
+    # @return [Signal, nil] The signal, or nil if its layout or scaling cannot be parsed
     def parse_signal_line(line, _current) # rubocop:disable Metrics/MethodLength
       return unless (m = line.match(SIGNAL_LINE_PATTERN))
 
-      sig_name = m[1]
-      start_bit = m[2].to_i
-      length = m[3].to_i
-      endian = m[4] == "1" ? :little : :big
-      sign = m[5] == "-" ? :signed : :unsigned
-      factor = m[6].to_f
-      offset = m[7].to_f
+      factor = parse_number(m[6])
+      offset = parse_number(m[7])
+      return unless factor && offset
+      return if factor.zero?
 
       Signal.new(
-        sig_name,
-        start_bit: start_bit,
-        length: length,
-        endianness: endian,
-        sign: sign,
+        m[1],
+        start_bit: m[2].to_i,
+        length: m[3].to_i,
+        endianness: m[4] == "1" ? :little : :big,
+        sign: m[5] == "-" ? :signed : :unsigned,
         factor: factor,
         offset: offset
       )
@@ -158,7 +170,7 @@ module CanMessenger
     # @param [String] name The name of the message to encode
     # @param [Hash<Symbol|String, Numeric>] values Signal names mapped to their values
     # @return [Hash] A hash containing :id (Integer) and :data (Array<Integer>)
-    # @raise [ArgumentError] If the message name is not found in the DBC
+    # @raise [ArgumentError] If the name is unknown, a value is out of range, or a signal exceeds the payload
     #
     # @example
     #   frame = dbc.encode_can('EngineData', RPM: 2500, Temperature: 85.5)
@@ -174,10 +186,13 @@ module CanMessenger
     #
     # Takes a CAN ID and data bytes, finds the matching message definition,
     # and decodes the data into individual signal values according to the DBC.
+    # The identifier must match the stored DBC ID, including its extended-frame
+    # flag when present; Messenger handles this conversion for received frames.
     #
     # @param [Integer] id The CAN message ID
     # @param [Array<Integer>] data The CAN message data bytes
     # @return [Hash, nil] A hash containing :name (String) and :signals (Hash), or nil if no matching message
+    # @raise [ArgumentError] If a signal references bits outside the supplied payload
     #
     # @example
     #   decoded = dbc.decode_can(0x123, [0x09, 0xC4, 0xAB, 0x00, 0x00, 0x00, 0x00, 0x00])
@@ -191,10 +206,58 @@ module CanMessenger
 
     private
 
+    # Checks whether a line begins with an explicitly supported metadata directive.
+    #
+    # Comparing the complete token prevents unsupported names such as BA_UNKNOWN_
+    # from being mistaken for the supported BA_ directive.
+    #
+    # @param [String] line The stripped DBC line
+    # @return [Boolean] Whether the parser can skip this directive
     def ignored_line?(line)
-      line.start_with?(*IGNORED_LINE_PREFIXES)
+      IGNORED_LINE_PREFIXES.include?(line.split(/[\s:]/, 2).first)
+    end
+
+    # Parses a scaling token without losing precision for integral values.
+    #
+    # Decimal and exponent spellings such as "1.0" and "1e0" remain exact integers.
+    # Fractional values use Float to retain the existing scaling behavior.
+    #
+    # @param [String] value A numeric token matched by the signal pattern
+    # @return [Integer, Float, nil] The parsed value, or nil if a fractional value is not finite
+    def parse_number(value)
+      value = value.sub(/\.(?=[eE]|\z)/, ".0")
+      exact = Rational(value)
+      return exact.to_i if exact.denominator == 1
+
+      number = Float(value)
+      number if number.finite?
+    end
+
+    # Validates a SIG_VALTYPE_ declaration and rejects unsupported signal representations.
+    #
+    # Only integer type 0 is supported. Accepting IEEE types 1 or 2 without handling
+    # their binary representation would silently change the encoded or decoded value.
+    #
+    # @param [String] line The stripped signal-type declaration
+    # @param [Integer] line_number The one-based line number in the DBC content
+    # @return [void]
+    # @raise [ArgumentError] If the declaration is malformed or names an unsupported type
+    def validate_signal_value_type(line, line_number)
+      match = line.match(SIGNAL_VALUE_TYPE_PATTERN)
+      raise_parse_error("Invalid signal value type definition", line_number, line) unless match
+      return if match[1] == "0"
+
+      raise_parse_error("Unsupported signal value type #{match[1]} (only integer type 0 is supported)",
+                        line_number, line)
     end
 
+    # Raises a parse error with enough source context to locate the definition.
+    #
+    # @param [String] reason The explanation of the parse failure
+    # @param [Integer] line_number The one-based line number in the DBC content
+    # @param [String] line The offending DBC line
+    # @return [void]
+    # @raise [ArgumentError] Always, with the reason, line number, and offending text
     def raise_parse_error(reason, line_number, line)
       raise ArgumentError, "#{reason} at line #{line_number}: #{line}"
     end
@@ -214,9 +277,10 @@ module CanMessenger
 
     # Initializes a new Message instance.
     #
-    # @param [Integer] id The CAN message ID (11-bit standard or 29-bit extended)
+    # @param [Integer] id The stored CAN ID, including the DBC extended-frame flag when present
     # @param [String] name The symbolic name of the message
-    # @param [Integer] dlc Data Length Code - number of bytes in the message (0-8 for classic CAN)
+    # @param [Integer] dlc Payload size in bytes; at most 8 for classic CAN or 64 for CAN FD
+    # @return [void]
     def initialize(id, name, dlc)
       @id = id
       @name = name
@@ -228,9 +292,11 @@ module CanMessenger
     #
     # Iterates through all signals in the message and encodes their values
     # into the appropriate bit positions within the message data bytes.
+    # The new payload is filled with zeros, and only supplied signal values are written.
     #
     # @param [Hash<Symbol|String, Numeric>] values Signal names mapped to their values
     # @return [Array<Integer>] Array of bytes representing the encoded message
+    # @raise [ArgumentError] If a value is out of range or a signal exceeds the payload size
     def encode(values)
       bytes = Array.new(@dlc, 0)
       @signals.each do |sig|
@@ -249,7 +315,8 @@ module CanMessenger
     # the final engineering unit values.
     #
     # @param [Array<Integer>] data The message data bytes to decode
-    # @return [Hash<Symbol, Float>] Signal names mapped to their decoded values
+    # @return [Hash<Symbol, Numeric>] Signal names mapped to their decoded values
+    # @raise [ArgumentError] If a signal references bits outside the supplied payload
     def decode(data)
       res = {}
       @signals.each do |sig|
@@ -285,16 +352,17 @@ module CanMessenger
     # @param [Integer] length The number of bits the signal occupies (1-64)
     # @param [Symbol] endianness Byte order - :little for little-endian, :big for big-endian
     # @param [Symbol] sign Value type - :unsigned for unsigned integers, :signed for signed integers
-    # @param [Float] factor Scaling factor to convert raw value to engineering units
-    # @param [Float] offset Offset to add after scaling
+    # @param [Numeric] factor Scaling factor to convert raw value to engineering units
+    # @param [Numeric] offset Offset to add after scaling
+    # @return [void]
     def initialize(name, start_bit:, length:, endianness:, sign:, factor:, offset:) # rubocop:disable Metrics/ParameterLists
       @name = name
       @start_bit = start_bit
       @length = length
       @endianness = endianness
       @sign = sign
-      @factor = factor
-      @offset = offset
+      @factor = normalize_integral_number(factor)
+      @offset = normalize_integral_number(offset)
     end
 
     # Encodes a value into the message byte array at this signal's bit position.
@@ -302,13 +370,14 @@ module CanMessenger
     # Converts the engineering unit value to a raw integer using the signal's
     # factor and offset, then places the bits into the appropriate positions
     # within the message bytes.
+    # Fractional raw values round to the nearest integer, with ties away from zero.
     #
     # @param [Array<Integer>] bytes The message byte array to modify
     # @param [Numeric] value The engineering unit value to encode
     # @return [void]
     # @raise [ArgumentError] If the value is out of range or signal exceeds message bounds
     def encode(bytes, value)
-      raw = ((value - offset) / factor).round
+      raw = (value - offset).quo(factor).round
       validate_signal_bounds(bytes.size)
       insert_bits(bytes, raw)
     end
@@ -318,9 +387,11 @@ module CanMessenger
     # Extracts the raw integer value from the appropriate bit positions,
     # then applies the signal's scaling (factor and offset) to convert
     # it to engineering units.
+    # Integer factors and offsets preserve exact Integer results; fractional Float scaling returns a Float.
     #
     # @param [Array<Integer>] bytes The message byte array to decode from
-    # @return [Float] The decoded value in engineering units
+    # @return [Numeric] The decoded value in engineering units
+    # @raise [ArgumentError] If a signal bit falls outside the supplied payload
     def decode(bytes)
       raw = extract_bits(bytes)
       (raw * factor) + offset
@@ -328,6 +399,19 @@ module CanMessenger
 
     private
 
+    # Converts integral Float scaling values to Integer without changing fractional values.
+    #
+    # Keeping identity scaling such as 1.0 and 0.0 integral avoids rounding large
+    # signal values through floating-point arithmetic.
+    #
+    # @param [Numeric] number The factor or offset supplied to the signal constructor
+    # @return [Numeric] An Integer for integral finite Floats, otherwise the original number
+    def normalize_integral_number(number)
+      return number unless number.is_a?(Float) && number.finite? && number.denominator == 1
+
+      number.to_i
+    end
+
     # Validates that the signal fits within the message boundaries.
     #
     # Ensures that all bits used by this signal fall within the message's
@@ -565,10 +649,25 @@ module CanMessenger
       msb_set ? value - (1 << length) : value
     end
 
+    # Reverses the bit numbering within each byte for Motorola signal positions.
+    #
+    # DBC sawtooth numbering labels a byte's least significant bit as 0, whereas
+    # sequential network numbering starts with its most significant bit. Applying
+    # this conversion twice returns the original position.
+    #
+    # @param [Integer] bitnum The absolute bit position in either numbering scheme
+    # @return [Integer] The corresponding position in the other scheme
     def sawtooth_to_network_bitnum(bitnum)
       (8 * (bitnum / 8)) + (7 - (bitnum % 8))
     end
 
+    # Finds the first signal bit that falls outside the payload boundaries.
+    #
+    # Checks mapped positions so Motorola signals spanning multiple bytes use
+    # the same bounds rules as their encoding and decoding paths.
+    #
+    # @param [Integer] max_allowed_bit The highest valid bit index in the payload
+    # @return [Integer, nil] The first invalid position encountered, or nil if all positions fit
     def invalid_bit_position(max_allowed_bit)
       length.times do |i|
         bit_pos = calculate_bit_position(i)
@@ -578,6 +677,10 @@ module CanMessenger
       nil
     end
 
+    # Converts a payload size to its highest valid zero-based bit index.
+    #
+    # @param [Integer] message_size_bytes The payload size in bytes
+    # @return [Integer] The highest bit index, or -1 for an empty payload
     def max_allowed_bit_for(message_size_bytes)
       (message_size_bytes * 8) - 1
     end

data/lib/can_messenger/messenger.rb

@@ -132,6 +132,7 @@ module CanMessenger
     # @return [void]
     def process_message(socket, filter, can_fd, dbc, &block)
       message = @adapter.receive_message(socket: socket, can_fd: can_fd)
+      return unless @listening
       return if message.nil?
       return if filter && !matches_filter?(message_id: message[:id], filter: filter)
 
@@ -186,6 +187,8 @@ module CanMessenger
     end
 
     def attach_dbc_payload!(message, dbc)
+      return if message[:remote]
+
       decoded = dbc.decode_can(dbc_decode_id(message), message[:data])
       message[:decoded] = decoded if decoded
     rescue StandardError => e

data/lib/can_messenger/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module CanMessenger
-  VERSION = "2.3.1"
+  # Gem release version used by packaging and available to applications at runtime.
+  VERSION = "2.3.2"
 end

data/lib/can_messenger.rb

@@ -6,6 +6,9 @@ require_relative "can_messenger/constants"
 require_relative "can_messenger/messenger"
 require_relative "can_messenger/dbc"
 
+# Public namespace for CAN messaging, transport adapters, and DBC encoding/decoding.
+# Requiring "can_messenger" loads these components together.
 module CanMessenger
+  # Library-specific error type available to callers and adapter extensions.
   class Error < StandardError; end
 end

data/sig/can_messenger/adapter/base.rbs

@@ -0,0 +1,42 @@
+module CanMessenger
+  module Adapter
+    class Base
+      @interface_name: String
+      @logger: Logger
+      @endianness: Symbol
+
+      attr_reader interface_name: String
+      attr_reader logger: Logger
+      attr_reader endianness: Symbol
+
+      def self.native_endianness: () -> Symbol
+
+      def initialize: (
+        interface_name: String,
+        logger: Logger,
+        ?endianness: (String | Symbol)
+      ) -> void
+
+      def open_socket: (?can_fd: bool?) -> untyped
+      def build_can_frame: (
+        id: Integer,
+        data: Array[Integer],
+        ?extended_id: bool,
+        ?can_fd: bool?
+      ) -> String
+      def receive_message: (
+        socket: untyped,
+        ?can_fd: bool?
+      ) -> ({ id: Integer, data: Array[Integer], extended: bool, ?remote: bool, ?dlc: Integer } | nil)
+      def parse_frame: (
+        frame: String,
+        ?can_fd: bool?
+      ) -> ({ id: Integer, data: Array[Integer], extended: bool, ?remote: bool, ?dlc: Integer } | nil)
+
+      private
+
+      def self.pack_uint: (Integer value, String template) -> String
+      def normalize_endianness: ((String | Symbol) endianness) -> Symbol
+    end
+  end
+end

data/sig/can_messenger/adapter/socketcan.rbs

@@ -0,0 +1,49 @@
+module CanMessenger
+  module Adapter
+    class Socketcan < Base
+      CAN_RAW: Integer
+      SOL_CAN_BASE: Integer
+      SOL_CAN_RAW: Integer
+      CAN_RAW_FD_FRAMES: Integer
+      FRAME_SIZE: Integer
+      CANFD_FRAME_SIZE: Integer
+      MIN_FRAME_SIZE: Integer
+      MAX_FD_DATA: Integer
+      MAX_STANDARD_ID: Integer
+      SOCKADDR_CAN_ADDR_SIZE: Integer
+      SOCKADDR_CAN_SIZE: Integer
+      SOCKADDR_CAN_PADDING: Integer
+      TIMEOUT: String
+      ZERO_CAN_ADDR: String
+
+      def open_socket: (?can_fd: bool?) -> untyped
+      def build_can_frame: (
+        id: Integer,
+        data: Array[Integer],
+        ?extended_id: bool,
+        ?can_fd: bool?
+      ) -> String
+      def receive_message: (
+        socket: untyped,
+        ?can_fd: bool?
+      ) -> ({ id: Integer, data: Array[Integer], extended: bool, ?remote: bool, ?dlc: Integer } | nil)
+      def parse_frame: (
+        frame: String,
+        ?can_fd: bool?
+      ) -> ({ id: Integer, data: Array[Integer], extended: bool, ?remote: bool, ?dlc: Integer } | nil)
+
+      private
+
+      def frame_data_length: (String frame, can_fd: bool?) -> Integer
+      def unpack_frame_id: (frame: String) -> Integer
+      def configure_socket: (untyped socket, can_fd: bool?) -> void
+      def close_socket: (untyped socket) -> void
+      def interface_index: () -> Integer
+      def interface_index_from_ifaddrs: () -> Integer?
+      def interface_index_from_sysfs: () -> Integer?
+      def build_sockaddr_can: (Integer ifindex) -> String
+      def validate_can_id!: (untyped id, extended_id: bool) -> void
+      def validate_data!: (untyped data) -> void
+    end
+  end
+end

data/sig/can_messenger/constants.rbs

@@ -0,0 +1,8 @@
+module CanMessenger
+  module Constants
+    CAN_ID_MASK: Integer
+    EXTENDED_ID_FLAG: Integer
+    REMOTE_TRANSMISSION_REQUEST_FLAG: Integer
+    MAX_EXTENDED_ID: Integer
+  end
+end

data/sig/can_messenger/dbc.rbs

@@ -0,0 +1,158 @@
+module CanMessenger
+  # DBC (Database CAN) Parser and Encoder/Decoder
+  class DBC
+    IGNORED_LINE_PREFIXES: Array[String]
+    NUMBER_PATTERN: Regexp
+    MESSAGE_LINE_PATTERN: Regexp
+    SIGNAL_LINE_PATTERN: Regexp
+    SIGNAL_VALUE_TYPE_PATTERN: Regexp
+
+    @messages: Hash[String, Message]
+
+    attr_reader messages: Hash[String, Message]
+
+    # Loads a DBC file from disk and parses its contents
+    def self.load: (String path) -> DBC
+
+    # Initializes a new DBC instance
+    def initialize: (?String content) -> void
+
+    # Parses DBC content and populates the messages hash
+    def parse: (String content) -> void
+
+    # Parses a message definition line from DBC content
+    def parse_message_line: (String line) -> (Message | nil)
+
+    # Parses a signal definition line from DBC content
+    def parse_signal_line: (String line, Message? _current) -> (Signal | nil)
+
+    # Encodes signal values into a CAN message frame
+    def encode_can: (String name, Hash[Symbol | String, Numeric] values) -> { id: Integer, data: Array[Integer] }
+
+    # Decodes a CAN message frame into signal values
+    def decode_can: (Integer id, Array[Integer] data) -> ({ name: String, signals: Hash[Symbol, Numeric] } | nil)
+
+    private
+
+    def ignored_line?: (String line) -> bool
+    def parse_number: (String value) -> (Integer | Float | nil)
+    def validate_signal_value_type: (String line, Integer line_number) -> void
+    def raise_parse_error: (String reason, Integer line_number, String line) -> void
+  end
+
+  # Represents a CAN message definition from a DBC file
+  class Message
+    @id: Integer
+    @name: String
+    @dlc: Integer
+    @signals: Array[Signal]
+
+    attr_reader id: Integer
+    attr_reader name: String
+    attr_reader dlc: Integer
+    attr_reader signals: Array[Signal]
+
+    # Initializes a new Message instance
+    def initialize: (Integer id, String name, Integer dlc) -> void
+
+    # Encodes signal values into the message byte array
+    def encode: (Hash[Symbol | String, Numeric] values) -> Array[Integer]
+
+    # Decodes message data bytes into individual signal values
+    def decode: (Array[Integer] data) -> Hash[Symbol, Numeric]
+  end
+
+  # Represents a signal within a CAN message
+  class Signal
+    @name: String
+    @start_bit: Integer
+    @length: Integer
+    @endianness: Symbol
+    @sign: Symbol
+    @factor: Numeric
+    @offset: Numeric
+
+    attr_reader name: String
+    attr_reader start_bit: Integer
+    attr_reader length: Integer
+    attr_reader endianness: Symbol
+    attr_reader sign: Symbol
+    attr_reader factor: Numeric
+    attr_reader offset: Numeric
+
+    # Initializes a new Signal instance
+    def initialize: (
+      String name,
+      start_bit: Integer,
+      length: Integer,
+      endianness: Symbol,
+      sign: Symbol,
+      factor: Numeric,
+      offset: Numeric
+    ) -> void
+
+    # Encodes a value into the message byte array at this signal's bit position
+    def encode: (Array[Integer] bytes, Numeric value) -> void
+
+    # Decodes this signal's value from the message byte array
+    def decode: (Array[Integer] bytes) -> Numeric
+
+    private
+
+    def normalize_integral_number: (Numeric number) -> Numeric
+
+    # Validates that the signal fits within the message boundaries
+    def validate_signal_bounds: (Integer message_size_bytes) -> void
+
+    # Encodes a raw integer value into the message byte array
+    def insert_bits: (Array[Integer] bytes, Integer raw) -> void
+
+    # Validates the raw integer value before encoding
+    def validate_raw_value: (Integer raw) -> void
+
+    # Validates unsigned values to ensure they're not negative
+    def validate_unsigned_value: (Integer raw) -> void
+
+    # Validates signed values to ensure they fit in the signal's bit range
+    def validate_signed_value: (Integer raw) -> void
+
+    # Processes the raw value for encoding (handles two's complement conversion)
+    def process_raw_value: (Integer raw) -> Integer
+
+    # Writes the processed bits into the message byte array
+    def write_bits_to_bytes: (Array[Integer] bytes, Integer raw) -> void
+
+    # Calculates the bit position for a given bit offset within the signal
+    def calculate_bit_position: (Integer bit_offset) -> Integer
+
+    # Calculates byte and bit indices from an absolute bit position
+    def calculate_byte_and_bit_indices: (Integer bit_pos) -> [Integer, Integer]
+
+    # Validates that a bit position is within the message boundaries
+    def validate_bit_position: (Integer bit_pos, Integer bytes_size) -> void
+
+    # Updates a specific bit within a byte in the message array
+    def update_byte_with_bit: (Array[Integer] bytes, Integer byte_index, Integer bit_index, Integer bit) -> void
+
+    # Extracts the signal value from the message byte array
+    def extract_bits: (Array[Integer] bytes) -> Integer
+
+    # Reads the raw bits from the message byte array
+    def read_bits_from_bytes: (Array[Integer] bytes) -> Integer
+
+    # Validates bit position during extraction to ensure it's within bounds
+    def validate_extraction_bounds: (Integer bit_pos, Integer bytes_size) -> void
+
+    # Converts unsigned value to signed if the signal is signed and the MSB is set
+    def convert_to_signed_if_needed: (Integer value) -> Integer
+
+    # Converts a sawtooth bit number to sequential network bit numbering
+    def sawtooth_to_network_bitnum: (Integer bitnum) -> Integer
+
+    # Returns the first invalid bit position for this signal, if any
+    def invalid_bit_position: (Integer max_allowed_bit) -> (Integer | nil)
+
+    # Calculates the maximum valid bit index for a message size
+    def max_allowed_bit_for: (Integer message_size_bytes) -> Integer
+  end
+end

data/sig/can_messenger/messenger.rbs

@@ -0,0 +1,78 @@
+module CanMessenger
+  # Messenger class for CAN bus communication
+  class Messenger
+    @interface_name: String
+    @logger: Logger
+    @listening: bool
+    @endianness: (String | Symbol)
+    @can_fd: bool
+    @adapter: untyped
+
+    # Initializes a new Messenger instance
+    def initialize: (
+        interface_name: String,
+        ?logger: Logger?,
+        ?endianness: (String | Symbol),
+        ?can_fd: bool,
+        ?adapter: untyped
+      ) -> void
+
+    # Sends a CAN message by writing directly to a raw CAN socket
+    def send_can_message: (
+        id: Integer,
+        data: Array[Integer],
+        ?extended_id: bool,
+        ?can_fd: bool?
+      ) -> void
+
+    # Encodes and sends a CAN message using a DBC definition
+    def send_dbc_message: (
+        message_name: String,
+        signals: Hash[Symbol | String, Numeric],
+        ?dbc: CanMessenger::DBC?,
+        ?extended_id: bool,
+        ?can_fd: bool?
+      ) -> void
+
+    # Continuously listens for CAN messages on the specified interface
+    def start_listening: (
+        ?filter: (Integer | Range[Integer] | Array[Integer])?,
+        ?can_fd: bool?,
+        ?dbc: CanMessenger::DBC?
+      ) { ({ id: Integer, data: Array[Integer], extended: bool, ?remote: bool, ?dlc: Integer, ?decoded: { name: String, signals: Hash[Symbol, Numeric] }, ?decode_error: { class: String, message: String } }) -> untyped } -> void
+
+    # Stops the listening loop
+    def stop_listening: () -> void
+
+    private
+
+    # Opens a socket, yields it, and closes it when done
+    def with_socket: (?can_fd: bool?) { (untyped socket) -> untyped } -> void
+
+    # Processes a single CAN message from socket
+    def process_message: (
+      untyped socket,
+      (Integer | Range[Integer] | Array[Integer])? filter,
+      bool can_fd,
+      CanMessenger::DBC? dbc
+    ) { ({ id: Integer, data: Array[Integer], extended: bool, ?remote: bool, ?dlc: Integer, ?decoded: { name: String, signals: Hash[Symbol, Numeric] }, ?decode_error: { class: String, message: String } }) -> untyped } -> void
+
+    # Checks whether the given message ID matches the specified filter
+    def matches_filter?: (message_id: Integer, filter: (Integer | Range[Integer] | Array[Integer])?) -> bool
+
+    def validate_filter!: ((Integer | Range[Integer] | Array[Integer])?) -> void
+    def validate_range_filter!: (Range[Integer] filter) -> void
+    def validate_array_filter!: (Array[Integer] filter) -> void
+    def attach_dbc_payload!: (
+      { id: Integer, data: Array[Integer], extended: bool, ?remote: bool, ?dlc: Integer, ?decoded: { name: String, signals: Hash[Symbol, Numeric] }, ?decode_error: { class: String, message: String } } message,
+      CanMessenger::DBC dbc
+    ) -> void
+    def normalize_can_id: (Integer id) -> Integer
+    def dbc_extended_id?: (Integer id) -> bool
+    def normalized_dbc_message: (
+      { id: Integer, data: Array[Integer] } encoded,
+      extended_id: bool
+    ) -> { id: Integer, data: Array[Integer], extended_id: bool }
+    def dbc_decode_id: ({ id: Integer, extended: bool, ?remote: bool, ?dlc: Integer } message) -> Integer
+  end
+end

data/sig/can_messenger/version.rbs

@@ -0,0 +1,3 @@
+module CanMessenger
+  VERSION: String
+end

data/sig/can_messenger.rbs

@@ -0,0 +1,4 @@
+module CanMessenger
+  class Error < StandardError
+  end
+end

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: can_messenger
 version: !ruby/object:Gem::Version
-  version: 2.3.1
+  version: 2.3.2
 platform: ruby
 authors:
 - fk1018
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
 description: CanMessenger provides an interface to send and receive messages over
   the CAN bus, useful for applications requiring CAN communication in Ruby.
 email:
@@ -27,6 +41,13 @@ files:
 - lib/can_messenger/dbc.rb
 - lib/can_messenger/messenger.rb
 - lib/can_messenger/version.rb
+- sig/can_messenger.rbs
+- sig/can_messenger/adapter/base.rbs
+- sig/can_messenger/adapter/socketcan.rbs
+- sig/can_messenger/constants.rbs
+- sig/can_messenger/dbc.rbs
+- sig/can_messenger/messenger.rbs
+- sig/can_messenger/version.rbs
 homepage: https://can-messenger.github.io/
 licenses:
 - MIT
@@ -43,14 +64,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 4.0.1
+      version: 4.0.9
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.20
 specification_version: 4
 summary: A simple Ruby wrapper to read and write CAN bus messages.
 test_files: []