Merge pull request #105 from grid-x/feat/modbus-device-identification

feat(modbus): implement Read Device Identification (0x2B/0x0E)

Author: mochaibi

api.go

@@ -49,4 +49,13 @@ type Client interface {
 	//ReadFIFOQueue reads the contents of a First-In-First-Out (FIFO) queue
 	// of register in a remote device and returns FIFO value register.
 	ReadFIFOQueue(ctx context.Context, address uint16) (results []byte, err error)
+
+	// Byte access
+
+	// ReadDeviceIdentification reads the device identification objects using Modbus Function Code 0x2B (MEI type 0x0E).
+	// It supports Basic, Regular, and Extended identification requests, including handling multi-part responses via
+	// the "More Follows" field and iteratively fetching objects until all are received.
+	ReadDeviceIdentification(ctx context.Context, readDeviceIDCode ReadDeviceIDCode) (results [][]byte, err error)
+	// ReadDeviceIdentification behaves like ReadDeviceIdentification but with an Object ID offset
+	ReadDeviceIdentificationWithObjectIDOffset(ctx context.Context, readDeviceIDCode ReadDeviceIDCode, objectIDOffset int) (results [][]byte, err error)
 }

client.go

@@ -505,6 +505,111 @@ func (mb *client) ReadFIFOQueue(ctx context.Context, address uint16) (results []
 	return
 }
 
+// Request:
+//
+//	Function code         : 1 byte (0x2B)
+//	MEI Type              : 1 byte (0x0E)
+//	Read Device ID Code   : 1 byte (01 for basic, 02 for regular, 03 for extended, 04 for specific)
+//	Object ID             : 1 byte (0x00 to 0xFF)
+//
+// Response:
+//
+//	Function code         : 1 byte (0x2B)
+//	MEI Type              : 1 byte (0x0E)
+//	Read Device ID Code   : 1 byte (01 for basic, 02 for regular, 03 for extended, 04 for specific)
+//	Conformity level 	  : 1 byte (0x01 / 0x02 / 0x03 / 0x81 / 0x82 / 0x83)
+//	More Follows          : 1 byte (0x00 for no, 0xFF for yes)
+//	Next Object ID        : 1 byte
+//	Number of Objects     : 1 byte
+//	List of (length = Number of Objects):
+//		Object ID         : 1 byte
+//		Object length     : 1 byte
+//		Object value      : Object length (see above)
+func (mb *client) ReadDeviceIdentification(ctx context.Context, readDeviceIDCode ReadDeviceIDCode) (results [][]byte, err error) {
+	return mb.ReadDeviceIdentificationWithObjectIDOffset(ctx, readDeviceIDCode, 0)
+}
+
+func (mb *client) ReadDeviceIdentificationWithObjectIDOffset(ctx context.Context, readDeviceIDCode ReadDeviceIDCode, objectIDOffset int) (results [][]byte, err error) {
+	var objectID byte
+	switch readDeviceIDCode {
+	case ReadDeviceIDCodeBasic:
+		objectID = 0x00
+	case ReadDeviceIDCodeRegular:
+		objectID = 0x03
+	case ReadDeviceIDCodeExtended:
+		objectID = 0x80
+	default:
+		return nil, fmt.Errorf("unsupported readDeviceIDCode %d", readDeviceIDCode)
+	}
+
+	objectID += byte(objectIDOffset)
+
+	return mb.readDeviceIdentificationWithObjectID(ctx, readDeviceIDCode, objectID)
+}
+
+func (mb *client) readDeviceIdentificationWithObjectID(ctx context.Context, readDeviceIDCode ReadDeviceIDCode, objectID byte) (results [][]byte, err error) {
+	const meiType = meiTypeReadDeviceIdentification
+
+	request := ProtocolDataUnit{
+		FunctionCode: FuncCodeReadDeviceIdentification,
+		Data:         []byte{byte(meiType), byte(readDeviceIDCode), objectID},
+	}
+
+	response, err := mb.send(ctx, &request)
+	if err != nil {
+		return nil, err
+	}
+
+	if got, want := len(response.Data), 6; got < want {
+		return nil, fmt.Errorf("missing required headers, got %d, want %d", got, want)
+	}
+
+	moreFollows := response.Data[3]
+	nextObjectID := response.Data[4]
+	numObjects := int(response.Data[5])
+
+	offset := 5
+	for i := 0; i < numObjects; i++ {
+		// Object ID is not required
+		offset++
+
+		// Read object length
+		offset++
+		if len(response.Data)-1 < offset {
+			return nil, fmt.Errorf("missing object length for object #%d", i)
+		}
+		objectLength := response.Data[offset]
+
+		// Read object value
+		offset++
+		end := offset + int(objectLength)
+		if len(response.Data) < end {
+			return nil, fmt.Errorf("data too short to read object #%d at index %d", i, end)
+		}
+		objectValue := response.Data[offset:end]
+
+		// Set new offset for next iteration
+		offset = end - 1
+
+		results = append(results, objectValue)
+	}
+
+	if moreFollows != 0xFF {
+		return results, nil
+	}
+
+	if nextObjectID == 0x00 {
+		return results, nil
+	}
+
+	nextResults, err := mb.readDeviceIdentificationWithObjectID(ctx, readDeviceIDCode, nextObjectID)
+	if err != nil {
+		return nil, err
+	}
+
+	return append(results, nextResults...), nil
+}
+
 // Helpers
 
 // send sends request and checks possible exception in the response.

cmd/modbus-cli/main.go

@@ -50,19 +50,21 @@ func main() {
 	flag.BoolVar(&opt.rtu.rs485.rxDuringTx, "rs485-rxDuringTx", false, "Allow bidirectional rx during tx")
 
 	var (
-		register        = flag.Int("register", -1, "")
-		fnCode          = flag.Int("fn-code", 0x03, "fn")
-		quantity        = flag.Int("quantity", 2, "register quantity, length in bytes")
-		ignoreCRCError  = flag.Bool("ignore-crc", false, "ignore crc")
-		eType           = flag.String("type-exec", "uint16", "")
-		pType           = flag.String("type-parse", "raw", "type to parse the register result. Use 'raw' if you want to see the raw bits and bytes. Use 'all' if you want to decode the result to different commonly used formats.")
-		writeValue      = flag.Float64("write-value", math.MaxFloat64, "")
-		readParseOrder  = flag.String("read-parse-order", "", "order to parse the register that was read out. Valid values: [AB, BA, ABCD, DCBA, BADC, CDAB]. Can only be used for 16bit (1 register) and 32bit (2 registers). If used, it will overwrite the big-endian or little-endian parameter.")
-		writeParseOrder = flag.String("write-exec-order", "", "order to execute the register(s) that should be written to. Valid values: [AB, BA, ABCD, DCBA, BADC, CDAB]. Can only be used for 16bit (1 register) and 32bit (2 registers). If used, it will overwrite the big-endian or little-endian parameter.")
-		parseBigEndian  = flag.Bool("order-parse-bigendian", true, "t: big, f: little")
-		execBigEndian   = flag.Bool("order-exec-bigendian", true, "t: big, f: little")
-		filename        = flag.String("filename", "", "")
-		logframe        = flag.Bool("log-frame", false, "prints received and send modbus frame to stdout")
+		register         = flag.Int("register", -1, "")
+		fnCode           = flag.Int("fn-code", 0x03, "fn")
+		quantity         = flag.Int("quantity", 2, "register quantity, length in bytes")
+		ignoreCRCError   = flag.Bool("ignore-crc", false, "ignore crc")
+		eType            = flag.String("type-exec", "uint16", "")
+		pType            = flag.String("type-parse", "raw", "type to parse the register result. Use 'raw' if you want to see the raw bits and bytes. Use 'all' if you want to decode the result to different commonly used formats.")
+		writeValue       = flag.Float64("write-value", math.MaxFloat64, "")
+		readParseOrder   = flag.String("read-parse-order", "", "order to parse the register that was read out. Valid values: [AB, BA, ABCD, DCBA, BADC, CDAB]. Can only be used for 16bit (1 register) and 32bit (2 registers). If used, it will overwrite the big-endian or little-endian parameter.")
+		writeParseOrder  = flag.String("write-exec-order", "", "order to execute the register(s) that should be written to. Valid values: [AB, BA, ABCD, DCBA, BADC, CDAB]. Can only be used for 16bit (1 register) and 32bit (2 registers). If used, it will overwrite the big-endian or little-endian parameter.")
+		parseBigEndian   = flag.Bool("order-parse-bigendian", true, "t: big, f: little")
+		execBigEndian    = flag.Bool("order-exec-bigendian", true, "t: big, f: little")
+		filename         = flag.String("filename", "", "")
+		logframe         = flag.Bool("log-frame", false, "prints received and send modbus frame to stdout")
+		readDeviceIDCode = flag.Int("device-id-code", 0x01, "Read Device ID Code (01 for basic, 02 for regular, 03 for extended, 04 for specific)")
+		objectIDOffset   = flag.Int("object-id-offset", 0, "Starting Object ID offset for device identification")
 	)
 
 	flag.Parse()
@@ -73,10 +75,12 @@ func main() {
 	}
 
 	logger := slog.Default()
-	if *register > math.MaxUint16 || *register < 0 {
-		intRegister := *register
-		logger.Error("invalid register value: " + strconv.Itoa(intRegister))
-		os.Exit(-1)
+	if *fnCode != modbus.FuncCodeReadDeviceIdentification {
+		if *register > math.MaxUint16 || *register < 0 {
+			intRegister := *register
+			logger.Error("invalid register value: " + strconv.Itoa(intRegister))
+			os.Exit(-1)
+		}
 	}
 
 	startReg := uint16(*register)
@@ -113,7 +117,7 @@ func main() {
 
 	client := modbus.NewClient(handler)
 
-	result, err := exec(ctx, client, eo, *writeParseOrder, *register, *fnCode, *writeValue, *eType, *quantity)
+	result, err := exec(ctx, client, eo, *writeParseOrder, *register, *fnCode, *writeValue, *eType, *quantity, *readDeviceIDCode, *objectIDOffset)
 	if err != nil && strings.Contains(err.Error(), "crc") && *ignoreCRCError {
 		logger.Info("ignoring crc error: %+v\n", err)
 	} else if err != nil {
@@ -122,13 +126,21 @@ func main() {
 	}
 
 	var res string
-	switch *pType {
-	case "raw":
-		res, err = resultToRawString(result, int(startReg))
-	case "all":
-		res, err = resultToAllString(result)
+	switch *fnCode {
+	case modbus.FuncCodeReadDeviceIdentification:
+		results := bytes.Split(result, []byte{'\n'})
+		for i, result := range results {
+			res += fmt.Sprintf("ObjectID[%d]: %s\n", i, string(result))
+		}
 	default:
-		res, err = resultToString(result, po, *readParseOrder, *pType)
+		switch *pType {
+		case "raw":
+			res, err = resultToRawString(result, int(startReg))
+		case "all":
+			res, err = resultToAllString(result)
+		default:
+			res, err = resultToString(result, po, *readParseOrder, *pType)
+		}
 	}
 
 	if err != nil {
@@ -158,6 +170,8 @@ func exec(
 	wval float64,
 	etype string,
 	quantity int,
+	readDeviceIDCode int,
+	objectIDOffset int,
 ) ([]byte, error) {
 	var err error
 	var result []byte
@@ -192,6 +206,12 @@ func exec(
 		result, err = client.ReadInputRegisters(ctx, uint16(register), uint16(quantity))
 	case 0x03:
 		result, err = client.ReadHoldingRegisters(ctx, uint16(register), uint16(quantity))
+	case modbus.FuncCodeReadDeviceIdentification:
+		objects, err := client.ReadDeviceIdentificationWithObjectIDOffset(ctx, modbus.ReadDeviceIDCode(readDeviceIDCode), objectIDOffset)
+		if err != nil {
+			return nil, err
+		}
+		result = bytes.Join(objects, []byte("\n"))
 	default:
 		err = fmt.Errorf("function code %d is unsupported", fnCode)
 	}

modbus.go

@@ -36,6 +36,32 @@ const (
 	FuncCodeMaskWriteRegister = 22
 	// FuncCodeReadFIFOQueue 16-bit wise access
 	FuncCodeReadFIFOQueue = 24
+	// FuncCodeReadDeviceIdentification for byte wise access
+	FuncCodeReadDeviceIdentification = 43
+)
+
+// meiType specifies a MEI Type as defined in https://www.modbus.org/docs/Modbus_Application_Protocol_V1_1b.pdf#page=44
+type meiType byte
+
+const (
+	// meiTypeReadDeviceIdentification is used together with FuncCodeReadDeviceIdentification
+	meiTypeReadDeviceIdentification meiType = 14
+)
+
+// ReadDeviceIDCode specifies a Read Device ID Code as defined in https://www.modbus.org/docs/Modbus_Application_Protocol_V1_1b.pdf#page=45
+type ReadDeviceIDCode byte
+
+const (
+	// ReadDeviceIDCodeBasic queries for VendorName, ProductCode, and MajorMinorRevision.
+	ReadDeviceIDCodeBasic ReadDeviceIDCode = iota + 1
+
+	// ReadDeviceIDCodeRegular queries for VendorURL, ProductName, ModelName, and UserApplicationName.
+	ReadDeviceIDCodeRegular
+
+	// ReadDeviceIDCodeExtended queries for regular and private (custom) objects.
+	ReadDeviceIDCodeExtended
+
+	// ReadDeviceIDCodeSpecific // Currently unsupported
 )
 
 const (

rtuclient.go

@@ -321,7 +321,8 @@ func calculateResponseLength(adu []byte) int {
 		length += 4
 	case FuncCodeMaskWriteRegister:
 		length += 6
-	case FuncCodeReadFIFOQueue:
+	case FuncCodeReadFIFOQueue,
+		FuncCodeReadDeviceIdentification:
 		// undetermined
 	default:
 	}