Improve protocol header documentation

Signed-off-by: Jacob Laursen <[email protected]>

bundles/org.openhab.binding.bluetooth.grundfosalpha/src/main/java/org/openhab/binding/bluetooth/grundfosalpha/internal/protocol/CRC16Calculator.java

@@ -40,9 +40,9 @@ public class CRC16Calculator {
             48554, 44427, 40424, 36297, 31782, 27655, 23652, 19525, 15522, 11395, 7392, 3265, 61215, 65342, 53085,
             57212, 44955, 49082, 36825, 40952, 28183, 32310, 20053, 24180, 11923, 16050, 3793, 7920 };
 
-    private static final int CRC16_INITIAL_VALUE = 0xFFFF;
-    private static final int CRC16_FINAL_XOR = 0xFFFF;
-    private static final int BYTE_MASK = 0xFF;
+    private static final int CRC16_INITIAL_VALUE = 0xffff;
+    private static final int CRC16_FINAL_XOR = 0xffff;
+    private static final int BYTE_MASK = 0xff;
 
     private CRC16Calculator() {
         // Prevent instantiation
@@ -59,35 +59,53 @@ public static boolean check(byte[] data) {
             throw new IllegalArgumentException("Data array must contain at least 3 bytes.");
         }
 
-        int dataLength = (data[1] & BYTE_MASK) + 1;
-        if (dataLength + 3 > data.length) {
+        int dataLength = (data[1] & BYTE_MASK);
+        if (dataLength + 4 > data.length) {
             throw new IllegalArgumentException("Invalid data length specified in the array.");
         }
 
-        int crcValue = calculateCRC(data, 1, dataLength);
-        byte highByte = (byte) getHighByte(crcValue);
-        byte lowByte = (byte) getLowByte(crcValue);
+        int crcValue = calculate(data, 1, dataLength + 1);
+        byte lowByte = getLowByte(crcValue);
+        byte highByte = getHighByte(crcValue);
 
-        return data[dataLength + 1] == highByte && data[dataLength + 2] == lowByte;
+        return data[dataLength + 2] == highByte && data[dataLength + 3] == lowByte;
     }
 
-    private static int calculateCRC(byte[] data, int start, int length) {
+    /**
+     * Calculates the CRC-16 checksum for the given data and puts it into
+     * the last two bytes of the given data array.
+     *
+     * @param data The data array to calculate CRC-16 with the two last bytes reserved for the result
+     * @param length The message size excluding start delimiter/size (first two bytes) and CRC-16 checksum (last two
+     *            bytes)
+     */
+    public static void put(byte[] data, int length) {
+        int dataLength = (data[1] & BYTE_MASK);
+        if (dataLength + 4 > data.length) {
+            throw new IllegalArgumentException("Invalid data length specified in the array.");
+        }
+        int crcValue = calculate(data, 1, length + 1);
+        data[length + 2] = getHighByte(crcValue);
+        data[length + 3] = getLowByte(crcValue);
+    }
+
+    private static int calculate(byte[] data, int start, int length) {
         int value = CRC16_INITIAL_VALUE;
 
         for (int i = 0; i < length; i++) {
             int inputByte = data[start + i] & BYTE_MASK;
             int tableIndex = (inputByte ^ (value >> 8)) & BYTE_MASK;
-            value = (LOOKUP_TABLE[tableIndex] ^ (value << 8)) & 0xFFFF;
+            value = (LOOKUP_TABLE[tableIndex] ^ (value << 8)) & 0xffff;
         }
 
         return value ^ CRC16_FINAL_XOR;
     }
 
-    private static int getHighByte(int word) {
-        return (word >> 8) & BYTE_MASK;
+    private static byte getLowByte(int word) {
+        return (byte) (word & BYTE_MASK);
     }
 
-    private static int getLowByte(int word) {
-        return word & BYTE_MASK;
+    private static byte getHighByte(int word) {
+        return (byte) ((word >> 8) & BYTE_MASK);
     }
 }

bundles/org.openhab.binding.bluetooth.grundfosalpha/src/main/java/org/openhab/binding/bluetooth/grundfosalpha/internal/protocol/Header.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2010-2025 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.bluetooth.grundfosalpha.internal.protocol;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * This defines protocol header related constants.
+ *
+ * @author Jacob Laursen - Initial contribution
+ */
+@NonNullByDefault
+public class Header {
+    /**
+     * Header length including {@link MessageStartDelimiter} and size byte.
+     */
+    public static final int LENGTH = 5;
+
+    /**
+     * Identifier for requests (last three bytes of header).
+     * The first two bytes appear to be swapped in the initial response message header.
+     */
+    public static final byte[] REQUEST_IDENTIFIER = { (byte) 0xe7, (byte) 0xf8, (byte) 0x0a };
+}

bundles/org.openhab.binding.bluetooth.grundfosalpha/src/main/java/org/openhab/binding/bluetooth/grundfosalpha/internal/protocol/MessageStartDelimiter.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) 2010-2025 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.bluetooth.grundfosalpha.internal.protocol;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * This defines the start delimiters for different kinds of messages.
+ *
+ * @author Jacob Laursen - Initial contribution
+ */
+@NonNullByDefault
+public enum MessageStartDelimiter {
+    Reply((byte) 0x24),
+    Message((byte) 0x26),
+    Request((byte) 0x27);
+
+    private final byte value;
+
+    MessageStartDelimiter(byte value) {
+        this.value = value;
+    }
+
+    public byte getValue() {
+        return value;
+    }
+}

bundles/org.openhab.binding.bluetooth.grundfosalpha/src/main/java/org/openhab/binding/bluetooth/grundfosalpha/internal/protocol/MessageType.java

@@ -22,18 +22,30 @@
 @NonNullByDefault
 public enum MessageType {
     FlowHead(new byte[] { 0x1f, 0x00, 0x01, 0x30, 0x01, 0x00, 0x00, 0x18 },
-            new byte[] { (byte) 0x27, (byte) 0x07, (byte) 0xe7, (byte) 0xf8, (byte) 0x0a, (byte) 0x03, (byte) 0x5d,
-                    (byte) 0x01, (byte) 0x21, (byte) 0x52, (byte) 0x1f }),
+            new byte[] { (byte) 0x03, (byte) 0x5d, (byte) 0x01, (byte) 0x21 }),
     Power(new byte[] { 0x2c, 0x00, 0x01, 0x00, 0x01, 0x00, 0x00, 0x25 },
-            new byte[] { (byte) 0x27, (byte) 0x07, (byte) 0xe7, (byte) 0xf8, (byte) 0x0a, (byte) 0x03, (byte) 0x57,
-                    (byte) 0x00, (byte) 0x45, (byte) 0x8a, (byte) 0xcd });
+            new byte[] { (byte) 0x03, (byte) 0x57, (byte) 0x00, (byte) 0x45 });
 
     private final byte[] identifier;
     private final byte[] request;
 
-    MessageType(byte[] identifier, byte[] request) {
+    MessageType(byte[] identifier, byte[] requestMessage) {
         this.identifier = identifier;
-        this.request = request;
+
+        int messageLength = requestMessage.length + Header.REQUEST_IDENTIFIER.length;
+        request = new byte[messageLength + 4];
+
+        // Append the start delimiter and message length
+        request[0] = MessageStartDelimiter.Request.getValue();
+        request[1] = (byte) messageLength;
+
+        // Append the rest of the protocol header
+        System.arraycopy(Header.REQUEST_IDENTIFIER, 0, request, 2, Header.REQUEST_IDENTIFIER.length);
+
+        // Append the message type-specific part
+        System.arraycopy(requestMessage, 0, request, Header.LENGTH, requestMessage.length);
+
+        CRC16Calculator.put(request, messageLength);
     }
 
     public byte[] identifier() {

bundles/org.openhab.binding.bluetooth.grundfosalpha/src/main/java/org/openhab/binding/bluetooth/grundfosalpha/internal/protocol/ResponseMessage.java

@@ -39,7 +39,6 @@ public class ResponseMessage {
     private final Logger logger = LoggerFactory.getLogger(ResponseMessage.class);
 
     private static final int GENI_RESPONSE_MAX_SIZE = 259;
-    private static final int GENI_RESPONSE_HEADER_LENGTH = 5;
     private static final int GENI_RESPONSE_TYPE_LENGTH = 8;
 
     private int responseTotalSize;
@@ -63,8 +62,8 @@ public boolean addPacket(byte[] packet) {
         if (responseRemaining == Integer.MAX_VALUE) {
             if (!isInitialPacket(packet)) {
                 if (logger.isDebugEnabled()) {
-                    byte[] header = new byte[GENI_RESPONSE_HEADER_LENGTH];
-                    System.arraycopy(packet, 0, header, 0, GENI_RESPONSE_HEADER_LENGTH);
+                    byte[] header = new byte[Header.LENGTH];
+                    System.arraycopy(packet, 0, header, 0, Header.LENGTH);
                     if (logger.isDebugEnabled()) {
                         logger.debug("Response bytes {} don't match GENI header", HexUtils.bytesToHex(header));
                     }
@@ -124,21 +123,21 @@ public Map<SensorDataType, BigDecimal> decode() {
     private Optional<ByteBuffer> decode(SensorDataType dataType) {
         byte[] expectedResponseType = dataType.messageType().identifier();
         byte[] responseType = new byte[GENI_RESPONSE_TYPE_LENGTH];
-        System.arraycopy(response, GENI_RESPONSE_HEADER_LENGTH, responseType, 0, GENI_RESPONSE_TYPE_LENGTH);
+        System.arraycopy(response, Header.LENGTH, responseType, 0, GENI_RESPONSE_TYPE_LENGTH);
 
         if (!Arrays.equals(expectedResponseType, responseType)) {
             return Optional.empty();
         }
 
-        int valueOffset = GENI_RESPONSE_HEADER_LENGTH + GENI_RESPONSE_TYPE_LENGTH + dataType.offset();
+        int valueOffset = Header.LENGTH + GENI_RESPONSE_TYPE_LENGTH + dataType.offset();
         byte[] valueBuffer = Arrays.copyOfRange(response, valueOffset, valueOffset + 4);
 
         return Optional.of(ByteBuffer.wrap(valueBuffer).order(ByteOrder.BIG_ENDIAN));
     }
 
     private boolean isInitialPacket(byte[] packet) {
-        return packet[0] == (byte) 0x24 && packet[2] == (byte) 0xf8 && packet[3] == (byte) 0xe7
-                && packet[4] == (byte) 0x0a;
+        return packet[0] == MessageStartDelimiter.Reply.getValue() && packet[2] == Header.REQUEST_IDENTIFIER[1]
+                && packet[3] == Header.REQUEST_IDENTIFIER[0] && packet[4] == Header.REQUEST_IDENTIFIER[2];
     }
 
     private int getTotalSize(byte[] initialPacket) {

bundles/org.openhab.binding.bluetooth.grundfosalpha/src/test/java/org/openhab/binding/bluetooth/grundfosalpha/internal/protocol/CRC16CalculatorTest.java

@@ -33,7 +33,7 @@ public class CRC16CalculatorTest {
 
     private static final int MAX_16BIT = 0xFFFF;
     private static final int MSB_16BIT = 0x8000;
-    private static final int POLYNOMIAL = 0x1021; // CRC-16-CCITT polynomial (4129 in decimal)
+    private static final int POLYNOMIAL = 0x1021; // CRC-16-CCITT polynomial
 
     @Test
     void precomputedValuesAreCorrect() {

bundles/org.openhab.binding.bluetooth.grundfosalpha/src/test/java/org/openhab/binding/bluetooth/grundfosalpha/internal/protocol/MessageTypeTest.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2010-2025 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.bluetooth.grundfosalpha.internal.protocol;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.is;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.junit.jupiter.api.Test;
+import org.openhab.core.util.HexUtils;
+
+/**
+ * Tests for {@link MessageType}.
+ *
+ * @author Jacob Laursen - Initial contribution
+ */
+@NonNullByDefault
+public class MessageTypeTest {
+    @Test
+    void requestFlowHead() {
+        String expected = "27 07 E7 F8 0A 03 5D 01 21 52 1F";
+        assertThat(HexUtils.bytesToHex(MessageType.FlowHead.request(), " "), is(expected));
+    }
+
+    @Test
+    void requestPower() {
+        String expected = "27 07 E7 F8 0A 03 57 00 45 8A CD";
+        assertThat(HexUtils.bytesToHex(MessageType.Power.request(), " "), is(expected));
+    }
+}