mavlink 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 53f52062bc7c9418b318763b74bdd79e29b0cac403b29fd1401b8930eb7f8d3a
+  data.tar.gz: 92928da3f63698734bfb5ea85840e2f876c89535294a559a1f3ee36cbfb894e6
+SHA512:
+  metadata.gz: 20c3b3be194b748a413ced15a052debe077f0bd6a5b9ea368e83205c811852167c3c0ac6a841865391a818f9ca4025060719b88dc649ddda9fa6dea0b80a22fa
+  data.tar.gz: d7360441513fe8435886b0581d88e52f4a17cc4f79b15c5c8865efcabff5bd6143419cd7579f8f832174477fb375c3248a382becff720cde0810ee1705c22614

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Smith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,149 @@
+# MAVLink Ruby
+
+A compact MAVLink implementation for Ruby. It packs and unpacks MAVLink 1 and MAVLink 2 frames, checks CRC-16/MCRF4XX checksums, and scans a byte stream for the start of a frame.
+
+Requires Ruby 3.2 or newer.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "mavlink"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself:
+
+```bash
+gem install mavlink
+```
+
+## Usage
+
+```ruby
+require "mavlink"
+```
+
+Payloads are raw bytes. This gem frames those bytes. It does not decode dialect fields such as `HEARTBEAT.type`. Pass the message's `CRC_EXTRA` byte into `pack` and `unpack`. `MAVLink::CRC_EXTRA_HEARTBEAT` is `50`.
+
+### Pack and unpack a frame
+
+A frame is a header, a payload, and a checksum. `pack` recomputes the checksum and appends it. `unpack` raises `ArgumentError` when the length or checksum is wrong.
+
+```ruby
+payload = [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x03].pack("C*")
+
+header = MAVLink::Message.new(
+  payload_length: payload.bytesize,
+  sequence: 0,
+  system_id: 1,
+  component_id: 1,
+  message_id: 0
+)
+
+wire = MAVLink::Frame.new(header: header, payload: payload, checksum: 0)
+  .pack(crc_extra: MAVLink::CRC_EXTRA_HEARTBEAT)
+
+frame = MAVLink::Frame.unpack(wire, crc_extra: MAVLink::CRC_EXTRA_HEARTBEAT)
+frame.header.message_id # => 0
+frame.payload           # => the 9 payload bytes
+frame.checksum          # => 0xA1B1
+```
+
+`Frame.new` checks that `payload.bytesize` matches `header.payload_length` and that `checksum` is an integer in `0..0xFFFF`.
+
+### Headers
+
+`MAVLink::Message` is the packet header. MAVLink 2 is the default (`stx` `0xFD`, 10 bytes, 24-bit `message_id`). MAVLink 1 uses `stx: MAVLink::STX_V1` (`0xFE`, 6 bytes, `message_id` in `0..255`).
+
+```ruby
+header = MAVLink::Message.new(
+  payload_length: 9,
+  sequence: 0,
+  system_id: 1,
+  component_id: 1,
+  message_id: 0
+)
+
+header.mavlink2?  # => true
+header.pack       # => 10-byte binary header
+MAVLink::Message.unpack(header.pack) # => header
+```
+
+MAVLink 1:
+
+```ruby
+header = MAVLink::Message.new(
+  stx: MAVLink::STX_V1,
+  payload_length: 9,
+  sequence: 0,
+  system_id: 1,
+  component_id: 1,
+  message_id: 0
+)
+
+header.pack.bytesize # => 6
+```
+
+Header fields:
+
+| Field | Range |
+| --- | --- |
+| `stx` | `STX_V1` (`0xFE`) or `STX_V2` (`0xFD`) |
+| `payload_length` | `0..255` |
+| `incompatibility_flags` | `0..255` (must be `0` for MAVLink 1) |
+| `compatibility_flags` | `0..255` (must be `0` for MAVLink 1) |
+| `sequence` | `0..255` |
+| `system_id` | `0..255` |
+| `component_id` | `0..255` |
+| `message_id` | `0..0xFFFFFF` (`0..255` for MAVLink 1) |
+
+`Message.unpack` expects exactly 10 bytes for MAVLink 2 and exactly 6 bytes for MAVLink 1.
+
+### Scan a byte stream
+
+`MAVLink::Parser` reads a continuous stream. It drops bytes until it sees `0xFE` or `0xFD`, then keeps that byte and everything after it. `feed` accepts a binary `String` or one integer in `0..255`, and returns the parser. `<<` is an alias.
+
+```ruby
+parser = MAVLink::Parser.new
+parser.waiting_for_stx? # => true
+
+parser.feed([0x00, 0x11, MAVLink::STX_V2, 0x09].pack("C*"))
+parser.got_stx?  # => true
+parser.stx       # => 0xFD
+parser.buffer    # => bytes from 0xFD onward
+```
+
+`buffer` is a copy. The parser does not yet split that buffer into frames. Once a full frame is buffered, decode it with `MAVLink::Frame.unpack`.
+
+### Checksum
+
+`MAVLink::CRC` is CRC-16/MCRF4XX: init `0xFFFF`, no final XOR. The check vector `"123456789"` is `0x6F91`.
+
+```ruby
+MAVLink::CRC.calculate("123456789") # => 0x6F91
+
+crc = MAVLink::CRC::INIT
+crc = MAVLink::CRC.accumulate(byte, crc)
+```
+
+A frame checksum covers the header without the magic byte, the payload, and one extra `CRC_EXTRA` byte that depends on the message id.
+
+## Development
+
+```bash
+bin/setup
+bundle exec rake test
+```
+
+`bundle exec rake build` writes the package to `pkg/`. `bundle exec rake release` tags the current version and pushes it to RubyGems.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/lib/mavlink/crc.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module MAVLink
+  # CRC-16/MCRF4XX (MAVLink checksum)
+  # Init 0xFFFF, no final XOR.
+  module CRC
+    INIT = 0xFFFF
+
+    def self.accumulate(byte, crc)
+      tmp = (byte ^ (crc & 0xFF)) & 0xFF
+      tmp = (tmp ^ (tmp << 4)) & 0xFF
+      ((crc >> 8) ^ (tmp << 8) ^ (tmp << 3) ^ (tmp >> 4)) & 0xFFFF
+    end
+
+    def self.calculate(data)
+      crc = INIT
+      data.each_byte { |byte| crc = accumulate(byte, crc) }
+      crc
+    end
+  end
+end

data/lib/mavlink/frame.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module MAVLink
+  # Full MAVLink packet: header + payload + CRC-16 checksum
+  Frame = ::Data.define(:header, :payload, :checksum) do
+    HEADER_LEN_V1 = 6
+    HEADER_LEN_V2 = 10
+    CHECKSUM_LEN = 2
+
+    def initialize(header:, payload:, checksum:)
+      raise ArgumentError, "header must be a MAVLink::Message, got #{header.class}" unless header.is_a?(Message)
+      raise ArgumentError, "payload must be a String, got #{payload.class}" unless payload.is_a?(String)
+      unless payload.bytesize == header.payload_length
+        raise ArgumentError,
+              "payload length #{payload.bytesize} does not match header.payload_length #{header.payload_length}"
+      end
+      unless checksum.is_a?(Integer) && checksum.between?(0, 0xFFFF)
+        raise ArgumentError, "checksum must be an integer in 0..0xFFFF, got #{checksum.inspect}"
+      end
+
+      super(header: header, payload: payload.b, checksum: checksum)
+    end
+
+    def pack(crc_extra:)
+      header_bytes = header.pack
+      ck = self.class.compute_checksum(header_bytes, payload, crc_extra)
+      header_bytes + payload + [ck & 0xFF, (ck >> 8) & 0xFF].pack("C*")
+    end
+
+    def self.unpack(binary, crc_extra:)
+      raise ArgumentError, "binary must be a String, got #{binary.class}" unless binary.is_a?(String)
+      raise ArgumentError, "binary is empty" if binary.empty?
+
+      stx = binary.getbyte(0)
+      header_len = header_length_for(stx)
+      raise ArgumentError, "frame too short for header, got #{binary.bytesize} bytes" if binary.bytesize < header_len
+
+      payload_length = binary.getbyte(1)
+      expected = header_len + payload_length + CHECKSUM_LEN
+      unless binary.bytesize == expected
+        raise ArgumentError, "frame requires #{expected} bytes, got #{binary.bytesize}"
+      end
+
+      header = Message.unpack(binary.byteslice(0, header_len))
+      payload = binary.byteslice(header_len, payload_length).b
+      checksum = binary.getbyte(header_len + payload_length) |
+                 (binary.getbyte(header_len + payload_length + 1) << 8)
+
+      expected_checksum = compute_checksum(binary.byteslice(0, header_len), payload, crc_extra)
+      unless checksum == expected_checksum
+        raise ArgumentError,
+              "checksum mismatch: got 0x#{checksum.to_s(16)}, expected 0x#{expected_checksum.to_s(16)}"
+      end
+
+      new(header: header, payload: payload, checksum: checksum)
+    end
+
+    def self.compute_checksum(header_bytes, payload, crc_extra)
+      crc = CRC.calculate(header_bytes.byteslice(1, header_bytes.bytesize - 1) + payload)
+      CRC.accumulate(crc_extra, crc)
+    end
+
+    def self.header_length_for(stx)
+      case stx
+      when STX_V2 then HEADER_LEN_V2
+      when STX_V1 then HEADER_LEN_V1
+      else
+        raise ArgumentError, "stx must be STX_V1 (0xFE) or STX_V2 (0xFD), got #{stx.inspect}"
+      end
+    end
+    private_class_method :header_length_for
+  end
+end

data/lib/mavlink/message.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module MAVLink
+  # Immutable MAVLink packet header (v1 or v2 framing)
+  Message = ::Data.define(
+    :stx,
+    :payload_length,
+    :incompatibility_flags,
+    :compatibility_flags,
+    :sequence,
+    :system_id,
+    :component_id,
+    :message_id
+  ) do
+    def initialize(
+      stx: STX_V2,
+      payload_length:,
+      incompatibility_flags: 0,
+      compatibility_flags: 0,
+      sequence:,
+      system_id:,
+      component_id:,
+      message_id:
+    )
+      validate_stx!(stx)
+      validate_uint8!(:payload_length, payload_length)
+      validate_uint8!(:incompatibility_flags, incompatibility_flags)
+      validate_uint8!(:compatibility_flags, compatibility_flags)
+      validate_uint8!(:sequence, sequence)
+      validate_uint8!(:system_id, system_id)
+      validate_uint8!(:component_id, component_id)
+      validate_message_id!(message_id)
+      validate_v1_constraints!(stx, incompatibility_flags, compatibility_flags, message_id)
+
+      super(
+        stx: stx,
+        payload_length: payload_length,
+        incompatibility_flags: incompatibility_flags,
+        compatibility_flags: compatibility_flags,
+        sequence: sequence,
+        system_id: system_id,
+        component_id: component_id,
+        message_id: message_id
+      )
+    end
+
+    def mavlink2?
+      stx == STX_V2
+    end
+
+    def mavlink1?
+      stx == STX_V1
+    end
+
+    def pack
+      if mavlink2?
+        [
+          stx, payload_length, incompatibility_flags, compatibility_flags,
+          sequence, system_id, component_id, message_id & 0xFF,
+          (message_id >> 8) & 0xFF, (message_id >> 16) & 0xFF
+        ].pack("C*")
+      else
+        [stx, payload_length, sequence, system_id, component_id, message_id].pack("C*")
+      end
+    end
+
+    def self.unpack(binary)
+      raise ArgumentError, "binary must be a String, got #{binary.class}" unless binary.is_a?(String)
+      raise ArgumentError, "binary is empty" if binary.empty?
+
+      stx = binary.getbyte(0)
+      case stx
+      when STX_V2
+        raise ArgumentError, "MAVLink 2 header requires 10 bytes, got #{binary.bytesize}" unless binary.bytesize == 10
+        b = binary.unpack("C10")
+        new(
+          stx: b[0],
+          payload_length: b[1],
+          incompatibility_flags: b[2],
+          compatibility_flags: b[3],
+          sequence: b[4],
+          system_id: b[5],
+          component_id: b[6],
+          message_id: b[7] | (b[8] << 8) | (b[9] << 16)
+        )
+      when STX_V1
+        raise ArgumentError, "MAVLink 1 header requires 6 bytes, got #{binary.bytesize}" unless binary.bytesize == 6
+        b = binary.unpack("C6")
+        new(
+          stx: b[0],
+          payload_length: b[1],
+          sequence: b[2],
+          system_id: b[3],
+          component_id: b[4],
+          message_id: b[5]
+        )
+      else
+        raise ArgumentError, "stx must be STX_V1 (0xFE) or STX_V2 (0xFD), got #{stx.inspect}"
+      end
+    end
+
+    private
+
+    def validate_stx!(stx)
+      return if stx == STX_V1 || stx == STX_V2
+
+      raise ArgumentError, "stx must be STX_V1 (0xFE) or STX_V2 (0xFD), got #{stx.inspect}"
+    end
+
+    def validate_uint8!(name, value)
+      return if value.is_a?(Integer) && value.between?(0, 255)
+
+      raise ArgumentError, "#{name} must be an integer in 0..255, got #{value.inspect}"
+    end
+
+    def validate_message_id!(message_id)
+      return if message_id.is_a?(Integer) && message_id.between?(0, 0xFFFFFF)
+
+      raise ArgumentError, "message_id must be an integer in 0..0xFFFFFF, got #{message_id.inspect}"
+    end
+
+    def validate_v1_constraints!(stx, incompatibility_flags, compatibility_flags, message_id)
+      return unless stx == STX_V1
+
+      if incompatibility_flags != 0 || compatibility_flags != 0
+        raise ArgumentError, "MAVLink 1 headers must have zero incompatibility_flags and compatibility_flags"
+      end
+
+      return if message_id <= 255
+
+      raise ArgumentError, "MAVLink 1 message_id must be in 0..255, got #{message_id.inspect}"
+    end
+  end
+end

data/lib/mavlink/parser.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module MAVLink
+  # Incremental state machine for a continuous MAVLink byte stream.
+  #
+  # Starts in WAITING_FOR_STX and discards bytes until a start-of-frame
+  # marker arrives: STX_V1 (0xFE) or STX_V2 (0xFD). That byte is kept and
+  # the machine moves to GOT_STX. Later bytes are retained and not treated
+  # as a new search.
+  class Parser
+    WAITING_FOR_STX = :waiting_for_stx
+    GOT_STX = :got_stx
+
+    attr_reader :state, :stx
+
+    def initialize
+      @state = WAITING_FOR_STX
+      @stx = nil
+      @buffer = String.new(encoding: Encoding::BINARY)
+    end
+
+    def waiting_for_stx?
+      state == WAITING_FOR_STX
+    end
+
+    def got_stx?
+      state == GOT_STX
+    end
+
+    # Bytes kept from the start-of-frame onward. Empty while still scanning.
+    def buffer
+      @buffer.dup
+    end
+
+    # Consume a String of bytes, or a single Integer byte in 0..255.
+    # Returns self so chunks can be chained.
+    def feed(data)
+      each_input_byte(data) { |byte| accept(byte) }
+      self
+    end
+    alias << feed
+
+    private
+
+    def accept(byte)
+      case state
+      when WAITING_FOR_STX
+        return unless start_of_frame?(byte)
+
+        @stx = byte
+        @buffer << byte
+        @state = GOT_STX
+      when GOT_STX
+        @buffer << byte
+      end
+    end
+
+    def start_of_frame?(byte)
+      byte == STX_V1 || byte == STX_V2
+    end
+
+    def each_input_byte(data)
+      case data
+      when String
+        data.each_byte { |byte| yield byte }
+      when Integer
+        unless data.between?(0, 255)
+          raise ArgumentError, "byte must be an integer in 0..255, got #{data}"
+        end
+
+        yield data
+      else
+        raise ArgumentError, "data must be a String or Integer byte, got #{data.class}"
+      end
+    end
+  end
+end

data/lib/mavlink/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MAVLink
+  VERSION = "0.1.0"
+end

data/lib/mavlink.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "mavlink/version"
+
+module MAVLink
+  STX_V1 = 0xFE
+  STX_V2 = 0xFD
+  CRC_EXTRA_HEARTBEAT = 50
+end
+
+require_relative "mavlink/crc"
+require_relative "mavlink/message"
+require_relative "mavlink/frame"
+require_relative "mavlink/parser"

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: mavlink
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Thomas Smith
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-09-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: A compact, high-performance implementation of the MAVLink protocol written
+  in Ruby.
+email: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- lib/mavlink.rb
+- lib/mavlink/crc.rb
+- lib/mavlink/frame.rb
+- lib/mavlink/message.rb
+- lib/mavlink/parser.rb
+- lib/mavlink/version.rb
+homepage: https://github.com/thomassmithdev/mavlink-ruby
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/thomassmithdev/mavlink-ruby
+  source_code_uri: https://github.com/thomassmithdev/mavlink-ruby
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: A compact, high-performance MAVLink protocol implementation for Ruby
+test_files: []