Development

README.md

@@ -1,34 +1,41 @@
 # MAVLink Payload Codec (Java)
 
-This repository provides a lightweight, schema-driven MAVLink payload
+This repository provides a lightweight, schema-driven MAVLink **payload**
 encoder and decoder for Java.
 
-It parses MAVLink XML dialects (including `<include>` handling), compiles
-message definitions, and provides fast, thread-safe encoding and decoding
-of MAVLink message **payloads**.
+It parses MAVLink XML dialects (including `{@code <include>}` handling),
+compiles message definitions, and provides fast, thread-safe encoding and
+decoding of MAVLink message **payloads only**.
 
-This library is intentionally limited in scope.
+This library is intentionally limited in scope and designed to be composed
+into larger MAVLink-capable systems.
 
+---
 
-## Scope (Important)
+## Scope (Read This First)
 
 This library operates **only on MAVLink message payloads**.
 
-It does **not**:
+It **does**:
 
-- Parse or generate MAVLink v1/v2 frames
-- Handle headers, CRCs, signing, or message framing
-- Manage system IDs, component IDs, or sequence numbers
-- Implement any transport (UART, UDP, TCP, etc.)
+- Parse MAVLink XML dialects
+- Compile message definitions into an immutable registry
+- Encode Java field maps into MAVLink payload bytes
+- Decode MAVLink payload bytes into typed field maps
+- Provides ability to sign and validate V2 messages
+- Correctly handle MAVLink field ordering, arrays, enums, and extensions
+- Creates JsonSchemas to match the fields that it parses to and from
 
-If you need a full MAVLink stack, this library is not it.
+It **does not**:
 
-This library is designed to sit **under** a framing and transport layer.
+- Manage system IDs, component IDs, or sequence numbers
+- Implement any transport (UART, UDP, TCP, etc.)
 
+---
 
 ## Features
 
-- MAVLink XML dialect parsing with `<include>` support
+- MAVLink XML dialect parsing with `{@code <include>}` support
 - Canonical dialect compilation (e.g. `common.xml`)
 - Immutable, thread-safe compiled registries
 - Correct MAVLink field ordering and packing rules
@@ -38,6 +45,7 @@ This library is designed to sit **under** a framing and transport layer.
 - Safe failure on invalid or truncated payloads
 - No shared mutable state at runtime
 
+---
 
 ## Getting Started
 
@@ -51,6 +59,9 @@ MavlinkCodec codec =
     loader.getDialectOrThrow("common");
 ```
 
+The built-in `common` dialect is loaded eagerly and is always available.
+
+---
 
 ## Encoding a Payload
 
@@ -70,6 +81,7 @@ Map<String, Object> values = Map.of(
 byte[] payload = codec.encodePayload(1, values);
 ```
 
+---
 
 ## Decoding a Payload
 
@@ -80,6 +92,10 @@ Map<String, Object> decoded =
 int load = (int) decoded.get("load");
 ```
 
+Field values are returned using standard Java types based on the MAVLink
+message definition.
+
+---
 
 ## Loading Custom Dialects
 
@@ -92,8 +108,11 @@ try (InputStream xml = Files.newInputStream(Path.of("custom.xml"))) {
 }
 ```
 
-Dialects are compiled once and cached by name.
+- Dialects are compiled once
+- Compiled codecs are cached by name
+- Subsequent lookups are lock-free
 
+---
 
 ## Thread Safety
 
@@ -107,16 +126,20 @@ A single codec instance may be safely:
 - Cached globally
 - Used in high-throughput systems
 
+---
 
 ## Error Handling
 
-- Unknown message IDs result in `IOException`
-- Invalid field types result in `IOException`
-- Invalid enum values result in `IOException`
-- Truncated or malformed payloads result in `IOException`
+All parsing and encoding errors are reported explicitly:
 
-No unchecked exceptions escape parsing paths.
+- Unknown message IDs → `IOException`
+- Invalid field types → `IOException`
+- Invalid enum values → `IOException`
+- Truncated or malformed payloads → `IOException`
 
+No unchecked exceptions escape payload encode/decode paths.
+
+---
 
 ## Design Philosophy
 
@@ -126,13 +149,7 @@ No unchecked exceptions escape parsing paths.
 - Explicit errors over silent failure
 - Practical MAVLink usage, not theoretical completeness
 
-
-## License
-
-Apache License 2.0
-
-See the `LICENSE` file for details.
-
+---
 
 ## Intended Users
 
@@ -143,5 +160,14 @@ This library is intended for:
 - Telemetry ingestion pipelines
 - MAVLink-aware tooling that does not want transport coupling
 
-If you want a full MAVLink stack, use something else.
+If you want a full MAVLink stack, use something else.  
 If you want a clean, deterministic payload codec, this is it.
+
+---
+
+## License
+
+Apache License 2.0
+
+See the `LICENSE` file for details.
+

pom.xml

@@ -23,7 +23,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>io.mapsmessaging</groupId>
     <artifactId>mavlink</artifactId>
-    <version>1.0.0</version>
+    <version>1.0.1-SNAPSHOT</version>
     <packaging>jar</packaging>
 
     <name>Mavlink parser, message formatter and schema</name>
@@ -229,7 +229,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-source-plugin</artifactId>
-                <version>3.3.1</version>
+                <version>3.4.0</version>
                 <executions>
                     <execution>
                         <id>attach-sources</id>
@@ -281,7 +281,7 @@
                     </includes>
                 </configuration>
                 <groupId>org.apache.maven.plugins</groupId>
-                <version>3.5.4</version>
+                <version>3.5.5</version>
             </plugin>
 
             <!-- sBOM  generator -->
@@ -370,6 +370,14 @@
             <version>2.13.2</version>
         </dependency>
 
+        <!-- Source: https://mvnrepository.com/artifact/io.swagger.core.v3/swagger-annotations -->
+        <dependency>
+            <groupId>io.swagger.core.v3</groupId>
+            <artifactId>swagger-annotations</artifactId>
+            <version>2.2.50</version>
+            <scope>compile</scope>
+        </dependency>
+
         <!-- Junit5 -->
         <dependency>
             <artifactId>junit-jupiter-engine</artifactId>
@@ -378,6 +386,26 @@
             <version>6.0.1</version>
         </dependency>
 
+        <dependency>
+            <groupId>com.networknt</groupId>
+            <artifactId>json-schema-validator</artifactId>
+            <version>1.5.1</version>
+            <scope>test</scope>
+        </dependency>
+        <!-- Source: https://mvnrepository.com/artifact/org.mockito/mockito-junit-jupiter -->
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-junit-jupiter</artifactId>
+            <version>5.23.0</version>
+            <scope>test</scope>
+        </dependency>
+        <!-- Source: https://mvnrepository.com/artifact/org.mockito/mockito-core -->
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <version>5.23.0</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
 </project>

src/main/java/io/mapsmessaging/mavlink/MavlinkEventFactory.java

@@ -0,0 +1,102 @@
+/*
+ *  Copyright [ 2020 - 2024 ] Matthew Buckton
+ *  Copyright [ 2024 - 2026 ] MapsMessaging B.V.
+ *
+ *  Licensed under the Apache License, Version 2.0 with the Commons Clause
+ *  (the "License"); you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at:
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *      https://commonsclause.com/
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ *
+ */
+
+package io.mapsmessaging.mavlink;
+
+import io.mapsmessaging.mavlink.codec.MavlinkCodec;
+import io.mapsmessaging.mavlink.codec.MavlinkFrameCodec;
+import io.mapsmessaging.mavlink.context.Detection;
+import io.mapsmessaging.mavlink.context.FrameFailureReason;
+import io.mapsmessaging.mavlink.message.CompiledMessage;
+import io.mapsmessaging.mavlink.message.Frame;
+import org.xml.sax.SAXException;
+
+import javax.xml.parsers.ParserConfigurationException;
+import java.io.IOException;
+import java.nio.ByteBuffer;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+public class MavlinkEventFactory {
+
+  private MavlinkFrameCodec frameCodec;
+  private SystemContextManager systemContextManager;
+
+  public MavlinkEventFactory() throws IOException {
+    this("common");
+  }
+
+  public MavlinkEventFactory(String dialectName) throws IOException {
+    Optional<MavlinkCodec> codec = MavlinkMessageFormatLoader.getInstance().getDialect(dialectName);
+    if (codec.isPresent()) {
+      MavlinkCodec codecInstance = codec.get();
+      frameCodec = new MavlinkFrameCodec(codecInstance);
+      systemContextManager = new SystemContextManager();
+    }
+    else{
+      throw new IOException("Mavlink "+dialectName+" codec not found");
+    }
+  }
+
+
+  public MavlinkEventFactory(Path dialectPath) throws IOException, ParserConfigurationException, SAXException {
+    MavlinkCodec codec = MavlinkMessageFormatLoader.getInstance().loadDialect(dialectPath);
+    frameCodec = new MavlinkFrameCodec(codec);
+    systemContextManager = new SystemContextManager();
+  }
+
+  public MavlinkEventFactory(MavlinkFrameCodec frameCodec, SystemContextManager systemContextManager){
+    this.frameCodec = frameCodec;
+    this.systemContextManager = systemContextManager;
+  }
+
+  public Optional<ProcessedFrame> unpack(String streamName, ByteBuffer payload) throws IOException {
+    long timestamp = System.nanoTime();
+
+    Optional<Frame> frameOptional = frameCodec.tryUnpackFrame(payload);
+    if (frameOptional.isEmpty()) {
+      return Optional.empty();
+    }
+    Frame frame = frameOptional.get();
+    FrameFailureReason failureReason = frame.getValidated();
+    Map<String, Object> fields = frameCodec.parsePayload(frame);
+    String name = "";
+    CompiledMessage message = frameCodec.getRegistry().getCompiledMessagesById().get(frame.getMessageId());
+    if(message != null){
+      name = message.getName();
+    }
+    if (failureReason == FrameFailureReason.OK || failureReason == FrameFailureReason.UNSIGNED) {
+      List<Detection> detectionList = systemContextManager.onValidatedFrame(frame, streamName, timestamp);
+      return Optional.of(new ProcessedFrame(name, frame, fields, true, detectionList));
+    }
+    List<Detection> detectionList = systemContextManager.onInvalidFrame(
+        frame.getSystemId(),
+        streamName,
+        timestamp,
+        failureReason
+    );
+    return Optional.of(new ProcessedFrame(name, frame, Map.of(), false, detectionList));
+  }
+
+
+
+}

src/main/java/io/mapsmessaging/mavlink/MavlinkFrameEnvelope.java

@@ -0,0 +1,40 @@
+/*
+ *  Copyright [ 2020 - 2024 ] Matthew Buckton
+ *  Copyright [ 2024 - 2026 ] MapsMessaging B.V.
+ *
+ *  Licensed under the Apache License, Version 2.0 with the Commons Clause
+ *  (the "License"); you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at:
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *      https://commonsclause.com/
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ *
+ */
+
+package io.mapsmessaging.mavlink;
+
+import io.mapsmessaging.mavlink.message.Version;
+import lombok.Value;
+
+@Value
+public class MavlinkFrameEnvelope {
+
+  Version version;
+  int messageId;
+
+  int systemId;
+  int componentId;
+  int sequence;
+
+  int payloadLength;
+  byte[] payload;
+
+  boolean signed;
+}