v1.0.1 Added changelog, version file, and updated the XML Parser

ssmethurst · ssmethurst · commit 3acd32269cf8 · 2026-03-06T10:40:53.000-08:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## Unreleased
+
+### Added
+
+- Add `changelog.md` to track unreleased and released project changes.
+- Add `agents.md` to require changelog updates for every project change.
+
+### Changed
+
+- Move application version constants into `ApplicationVersion` so version updates are centralized.
+
+## 0.1.0 - 2026-03-06
+
+_First tracked release baseline._
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # BACnetClientExampleJava
 
-A beginner-focused BACnet/IP client tutorial in Java using the CAS BACnet Stack.
+A beginner-focused BACnet/IP client tutorial in Java using the [CAS BACnet Stack](https://store.chipkin.com/services/stacks/bacnet-stack) v4.5.6.2626
 
 This example shows how to:
 - Send `Who-Is`
@@ -28,7 +28,7 @@ This project intentionally does **not** use stack Hook APIs.
 
 - Java 8+
 - Maven
-- CAS BACnet Stack native library available on `PATH` or `java.library.path`
+- [CAS BACnet Stack](https://store.chipkin.com/services/stacks/bacnet-stack) native library available on `PATH` or `java.library.path`
   - Example on Windows x64: `CASBACnetStack_x64_Release.dll`
 
 ## Build
@@ -114,6 +114,7 @@ Commands:
 Input tip: type a command key and press Enter.
 
 w
+
 Command W: sending Who-Is (unconfirmed discovery).
   Destination: broadcast via 192.168.2.217:47808 (actual UDP destination 255.255.255.255:47808)
   BACnet network: 0 (local network)
diff --git a/agents.md b/agents.md
@@ -0,0 +1,26 @@
+# AGENTS.md
+
+## Scope
+
+These instructions apply to the entire repository.
+
+## Required Changelog Policy
+
+- Any change to code, behavior, configuration, dependencies, build scripts, docs, or tests must be documented in `changelog.md`.
+- Add new notes under `## Unreleased`, which must remain the first changelog entry at the top of `changelog.md`.
+- Do not move unreleased notes into a versioned section until a release is cut.
+
+## Changelog Rules (Common Changelog aligned)
+
+- Keep entries human-focused, concise, and impact-oriented.
+- Use change groups as needed: `Changed`, `Added`, `Removed`, `Fixed`.
+- Write each item in imperative mood (for example: `Add`, `Fix`, `Refactor`, `Document`).
+- Keep each item to one line when possible.
+- Include references (issues, PRs, commits) when available.
+- Prefix breaking changes with `**Breaking:**`.
+- For released versions, use `## <version> - <YYYY-MM-DD>`.
+
+## Agent Workflow Requirement
+
+- Before finishing any task that changes the repository, update `changelog.md` under `## Unreleased`.
+- If no user-visible or developer-relevant change occurred, document why no changelog entry was added.
diff --git a/src/main/java/com/chipkin/bacnet/ApplicationVersion.java b/src/main/java/com/chipkin/bacnet/ApplicationVersion.java
@@ -0,0 +1,15 @@
+package com.chipkin.bacnet;
+
+/**
+ * Central application version values.
+ *
+ * Update this file when bumping the example version.
+ */
+public final class ApplicationVersion {
+    public static final int MAJOR = 1;
+    public static final int MINOR = 0;
+    public static final int PATCH = 1;
+
+    private ApplicationVersion() {
+    }
+}
diff --git a/src/main/java/com/chipkin/bacnet/SimpleBACnetClientExample.java b/src/main/java/com/chipkin/bacnet/SimpleBACnetClientExample.java
@@ -1,7 +1,13 @@
+/*
+ * Copyright and License Notice
+ * Chipkin Automation Systems Inc (CAS)
+ * BACnet Stack as Source Code Product
+ * 
+ * Simple BACnet Client Example with Business Logic
+ */
+
 package com.chipkin.bacnet;
 
-import com.sun.jna.Memory;
-import com.sun.jna.Pointer;
 import java.io.BufferedReader;
 import java.io.IOException;
 import java.io.InputStreamReader;
@@ -13,6 +19,9 @@
 import java.util.Queue;
 import java.util.concurrent.ConcurrentLinkedQueue;
 
+import com.sun.jna.Memory;
+import com.sun.jna.Pointer;
+
 /**
  * BACnet client tutorial example.
  *
@@ -22,10 +31,6 @@
  */
 public class SimpleBACnetClientExample {
 
-    private static final int APPLICATION_VERSION_MAJOR = 1;
-    private static final int APPLICATION_VERSION_MINOR = 0;
-    private static final int APPLICATION_VERSION_PATCH = 0;
-
     private static final int BACNET_UDP_PORT = 47808;
     private static final int UDP_TIMEOUT_MS = 2;
     private static final int MAX_MESSAGE_LENGTH = 2048;
@@ -96,7 +101,7 @@ public static void main(String[] args) {
 
     private void initializeStack() throws BACnetException {
         System.out.println("CAS BACnet Stack Client Example (Java) v"
-            + APPLICATION_VERSION_MAJOR + "." + APPLICATION_VERSION_MINOR + "." + APPLICATION_VERSION_PATCH);
+            + ApplicationVersion.MAJOR + "." + ApplicationVersion.MINOR + "." + ApplicationVersion.PATCH);
         System.out.println("Stack version: " + adapter.getVersionString());
 
         // Core integration point:
@@ -127,12 +132,13 @@ private void initializeStack() throws BACnetException {
     }
 
     private void runLoop() {
+        final long TICK_SLEEP_MS = 5;
         while (running) {
             // Tick is the stack "heartbeat". Call this frequently.
             // It handles retries, timeouts, request tracking, and packet parsing.
             library.BACnetStack_Tick();
             processConsoleInput();
-            sleepQuietly(5);
+            sleepQuietly(TICK_SLEEP_MS);
         }
 
         udpSocket.close();
@@ -171,10 +177,16 @@ private void handleCommand(char input) {
     }
 
     private void sendWhoIs() {
+        final String BROADCAST_IP = "255.255.255.255";
+        final String BROADCAST_ENDPOINT = BROADCAST_IP + ":" + BACNET_UDP_PORT;
+        final boolean IS_BROADCAST = true;
+        final short LOCAL_NETWORK = 0;
+        final Pointer ROUTER_MAC = Pointer.NULL;
+        final byte ROUTER_MAC_LENGTH = 0;
         String target = connectionStringToHuman(targetConnectionString, targetConnectionString.length);
         System.out.println("Command W: sending Who-Is (unconfirmed discovery).");
-        System.out.println("  Destination: broadcast via " + target + " (actual UDP destination 255.255.255.255:47808)");
-        System.out.println("  BACnet network: 0 (local network)");
+        System.out.println("  Destination: broadcast via " + target + " (actual UDP destination " + BROADCAST_ENDPOINT + ")");
+        System.out.println("  BACnet network: " + LOCAL_NETWORK + " (local network)");
 
         Memory connection = new Memory(targetConnectionString.length);
         connection.write(0, targetConnectionString, 0, targetConnectionString.length);
@@ -183,10 +195,10 @@ private void sendWhoIs() {
             connection,
             (byte) targetConnectionString.length,
             BACnetConstants.NETWORK_TYPE_IP,
-            true,
-            (short) 0,
-            Pointer.NULL,
-            (byte) 0
+            IS_BROADCAST,
+            LOCAL_NETWORK,
+            ROUTER_MAC,
+            ROUTER_MAC_LENGTH
         );
 
         if (!sent) {
@@ -195,6 +207,12 @@ private void sendWhoIs() {
     }
 
     private void sendReadProperty() {
+        final boolean USE_ARRAY_INDEX = false;
+        final int ARRAY_INDEX = 0;
+        final int INVOKE_ID_LENGTH = 1;
+        final short LOCAL_NETWORK = 0;
+        final Pointer ROUTER_MAC = Pointer.NULL;
+        final byte ROUTER_MAC_LENGTH = 0;
         String target = connectionStringToHuman(targetConnectionString, targetConnectionString.length);
         System.out.println("Command R: sending ReadProperty (confirmed request).");
         System.out.println("  Destination: " + target + ", deviceInstance=" + targetDeviceInstance);
@@ -209,16 +227,16 @@ private void sendReadProperty() {
             readObjectType,
             readObjectInstance,
             readProperty,
-            false,
-            0
+            USE_ARRAY_INDEX,
+            ARRAY_INDEX
         );
 
         if (!built) {
             System.out.println("BuildReadProperty failed.");
             return;
         }
 
-        Memory invokeId = new Memory(1);
+        Memory invokeId = new Memory(INVOKE_ID_LENGTH);
         Memory connection = new Memory(targetConnectionString.length);
         connection.write(0, targetConnectionString, 0, targetConnectionString.length);
 
@@ -227,9 +245,9 @@ private void sendReadProperty() {
             connection,
             (byte) targetConnectionString.length,
             BACnetConstants.NETWORK_TYPE_IP,
-            (short) 0,
-            Pointer.NULL,
-            (byte) 0
+            LOCAL_NETWORK,
+            ROUTER_MAC,
+            ROUTER_MAC_LENGTH
         );
 
         if (!sent) {
@@ -238,44 +256,54 @@ private void sendReadProperty() {
     }
 
     private void sendSubscribeCov() {
+        final int INVOKE_ID_LENGTH = 1;
+        final boolean CONFIRMED_NOTIFICATIONS = false;
+        final short LOCAL_NETWORK = 0;
+        final Pointer ROUTER_MAC = Pointer.NULL;
+        final byte ROUTER_MAC_LENGTH = 0;
+        final int ANALOG_INPUT_PROCESS_ID = 1;
+        final int ANALOG_VALUE_PROCESS_ID = 2;
+        final int ANALOG_INPUT_INSTANCE = 0;
+        final int ANALOG_VALUE_INSTANCE = 2;
         String target = connectionStringToHuman(targetConnectionString, targetConnectionString.length);
         System.out.println("Command S: sending SubscribeCOV (confirmed request).");
         System.out.println("  Destination: " + target + ", deviceInstance=" + targetDeviceInstance);
         System.out.println("  Subscription lifetime: " + SUBSCRIPTION_LIFETIME_SECONDS + " seconds");
-        System.out.println("  Requests: analogInput:0 (processId=1), analogValue:2 (processId=2)");
+        System.out.println("  Requests: analogInput:" + ANALOG_INPUT_INSTANCE + " (processId=" + ANALOG_INPUT_PROCESS_ID + "), analogValue:"
+            + ANALOG_VALUE_INSTANCE + " (processId=" + ANALOG_VALUE_PROCESS_ID + ")");
 
-        Memory invokeId = new Memory(1);
+        Memory invokeId = new Memory(INVOKE_ID_LENGTH);
         Memory connection = new Memory(targetConnectionString.length);
         connection.write(0, targetConnectionString, 0, targetConnectionString.length);
 
         boolean sentAi = library.BACnetStack_SendSubscribeCOV(
             invokeId,
-            1,
+            ANALOG_INPUT_PROCESS_ID,
             BACnetConstants.OBJECT_TYPE_ANALOG_INPUT,
-            0,
-            false,
+            ANALOG_INPUT_INSTANCE,
+            CONFIRMED_NOTIFICATIONS,
             SUBSCRIPTION_LIFETIME_SECONDS,
             connection,
             (byte) targetConnectionString.length,
             BACnetConstants.NETWORK_TYPE_IP,
-            (short) 0,
-            Pointer.NULL,
-            (byte) 0
+            LOCAL_NETWORK,
+            ROUTER_MAC,
+            ROUTER_MAC_LENGTH
         );
 
         boolean sentAv = library.BACnetStack_SendSubscribeCOV(
             invokeId,
-            2,
+            ANALOG_VALUE_PROCESS_ID,
             BACnetConstants.OBJECT_TYPE_ANALOG_VALUE,
-            2,
-            false,
+            ANALOG_VALUE_INSTANCE,
+            CONFIRMED_NOTIFICATIONS,
             SUBSCRIPTION_LIFETIME_SECONDS,
             connection,
             (byte) targetConnectionString.length,
             BACnetConstants.NETWORK_TYPE_IP,
-            (short) 0,
-            Pointer.NULL,
-            (byte) 0
+            LOCAL_NETWORK,
+            ROUTER_MAC,
+            ROUTER_MAC_LENGTH
         );
 
         if (!sentAi || !sentAv) {
@@ -333,6 +361,7 @@ private short handleSendMessage(Pointer message,
                                     byte connectionStringLength,
                                     byte networkType,
                                     boolean broadcast) {
+        final int MIN_CONNECTION_STRING_LENGTH = 6;
         if (messageLength <= 0) {
             return 0;
         }
@@ -343,7 +372,7 @@ private short handleSendMessage(Pointer message,
         }
 
         int connLength = Byte.toUnsignedInt(connectionStringLength);
-        if (connLength < 6) {
+        if (connLength < MIN_CONNECTION_STRING_LENGTH) {
             System.out.println("Cannot send, connection string too short: " + connLength);
             return 0;
         }
@@ -464,33 +493,41 @@ private void parseArguments(String[] args) {
     }
 
     private void buildTargetConnectionString(String ip, int port) {
+        final int IPV4_OCTET_COUNT = 4;
+        final int PORT_HIGH_INDEX = 4;
+        final int PORT_LOW_INDEX = 5;
         String[] parts = ip.split("\\.");
-        if (parts.length != 4) {
+        if (parts.length != IPV4_OCTET_COUNT) {
             throw new IllegalArgumentException("Invalid IPv4 address: " + ip);
         }
 
-        for (int i = 0; i < 4; i++) {
+        for (int i = 0; i < IPV4_OCTET_COUNT; i++) {
             targetConnectionString[i] = (byte) parseIntOrDefault(parts[i], 0);
         }
-        targetConnectionString[4] = (byte) ((port >> 8) & 0xFF);
-        targetConnectionString[5] = (byte) (port & 0xFF);
+        targetConnectionString[PORT_HIGH_INDEX] = (byte) ((port >> 8) & 0xFF);
+        targetConnectionString[PORT_LOW_INDEX] = (byte) (port & 0xFF);
     }
 
     private byte[] toConnectionString(InetAddress address, int port) {
-        byte[] out = new byte[6];
+        final int IPV4_OCTET_COUNT = 4;
+        final int CONNECTION_STRING_LENGTH = 6;
+        final int PORT_HIGH_INDEX = 4;
+        final int PORT_LOW_INDEX = 5;
+        byte[] out = new byte[CONNECTION_STRING_LENGTH];
         byte[] ipBytes = address.getAddress();
-        if (ipBytes.length != 4) {
+        if (ipBytes.length != IPV4_OCTET_COUNT) {
             throw new IllegalStateException("Expected IPv4 address, got length=" + ipBytes.length);
         }
 
-        System.arraycopy(ipBytes, 0, out, 0, 4);
-        out[4] = (byte) ((port >> 8) & 0xFF);
-        out[5] = (byte) (port & 0xFF);
+        System.arraycopy(ipBytes, 0, out, 0, IPV4_OCTET_COUNT);
+        out[PORT_HIGH_INDEX] = (byte) ((port >> 8) & 0xFF);
+        out[PORT_LOW_INDEX] = (byte) (port & 0xFF);
         return out;
     }
 
     private static String connectionStringToHuman(byte[] connectionString, int length) {
-        if (connectionString == null || length < 6) {
+        final int CONNECTION_STRING_LENGTH = 6;
+        if (connectionString == null || length < CONNECTION_STRING_LENGTH) {
             return "invalid-connection-string";
         }
 
diff --git a/src/main/java/com/chipkin/bacnet/XmlMessageParser.java b/src/main/java/com/chipkin/bacnet/XmlMessageParser.java
