RSDK-7152 Analog Reader API rdk changes

components/board/board.go

@@ -77,12 +77,19 @@ type Board interface {
 // An Analog represents an analog pin that resides on a board.
 type Analog interface {
 	// Read reads off the current value.
-	Read(ctx context.Context, extra map[string]interface{}) (int, error)
+	Read(ctx context.Context, extra map[string]interface{}) (int, AnalogRange, error)
 
 	// Write writes a value to the analog pin.
 	Write(ctx context.Context, value int, extra map[string]interface{}) error
 }
 
+// AnalogRange contains themin, max, and stepSize of the analog reader.
+type AnalogRange struct {
+	Min      float32
+	Max      float32
+	StepSize float32
+}
+
 // FromDependencies is a helper for getting the named board from a collection of
 // dependencies.
 func FromDependencies(deps resource.Dependencies, name string) (Board, error) {

components/board/client.go

@@ -134,10 +134,10 @@ type analogClient struct {
 	analogName string
 }
 
-func (ac *analogClient) Read(ctx context.Context, extra map[string]interface{}) (int, error) {
+func (ac *analogClient) Read(ctx context.Context, extra map[string]interface{}) (int, AnalogRange, error) {
 	ext, err := protoutils.StructToStructPb(extra)
 	if err != nil {
-		return 0, err
+		return 0, AnalogRange{}, err
 	}
 	// the api method is named ReadAnalogReader, it is named differently than
 	// the board interface functions.
@@ -147,9 +147,9 @@ func (ac *analogClient) Read(ctx context.Context, extra map[string]interface{})
 		Extra:            ext,
 	})
 	if err != nil {
-		return 0, err
+		return 0, AnalogRange{}, err
 	}
-	return int(resp.Value), nil
+	return int(resp.Value), AnalogRange{Min: resp.MinRange, Max: resp.MaxRange, StepSize: resp.StepSize}, nil
 }
 
 func (ac *analogClient) Write(ctx context.Context, value int, extra map[string]interface{}) error {

components/board/client_test.go

@@ -141,13 +141,16 @@ func TestWorkingClient(t *testing.T) {
 		test.That(t, injectBoard.AnalogByNameCap(), test.ShouldResemble, []interface{}{"analog1"})
 
 		// Analog: Read
-		injectAnalog.ReadFunc = func(ctx context.Context, extra map[string]interface{}) (int, error) {
+		injectAnalog.ReadFunc = func(ctx context.Context, extra map[string]interface{}) (int, board.AnalogRange, error) {
 			actualExtra = extra
-			return 6, nil
+			return 6, board.AnalogRange{Min: 0, Max: 10, StepSize: 0.1}, nil
 		}
-		readVal, err := analog1.Read(context.Background(), expectedExtra)
+		readVal, analogRange, err := analog1.Read(context.Background(), expectedExtra)
 		test.That(t, err, test.ShouldBeNil)
 		test.That(t, readVal, test.ShouldEqual, 6)
+		test.That(t, analogRange.Min, test.ShouldEqual, 0)
+		test.That(t, analogRange.Max, test.ShouldEqual, 10)
+		test.That(t, analogRange.StepSize, test.ShouldEqual, 0.1)
 		test.That(t, actualExtra, test.ShouldResemble, expectedExtra)
 		actualExtra = nil
 

components/board/collector.go

@@ -41,12 +41,13 @@ func newAnalogCollector(resource interface{}, params data.CollectorParams) (data
 
 	cFunc := data.CaptureFunc(func(ctx context.Context, arg map[string]*anypb.Any) (interface{}, error) {
 		var value int
+		var analogRange AnalogRange
 		if _, ok := arg[analogReaderNameKey]; !ok {
 			return nil, data.FailedToReadErr(params.ComponentName, analogs.String(),
 				errors.New("Must supply reader_name in additional_params for analog collector"))
 		}
 		if reader, err := board.AnalogByName(arg[analogReaderNameKey].String()); err == nil {
-			value, err = reader.Read(ctx, data.FromDMExtraMap)
+			value, analogRange, err = reader.Read(ctx, data.FromDMExtraMap)
 			if err != nil {
 				// A modular filter component can be created to filter the readings from a component. The error ErrNoCaptureToStore
 				// is used in the datamanager to exclude readings from being captured and stored.
@@ -57,7 +58,10 @@ func newAnalogCollector(resource interface{}, params data.CollectorParams) (data
 			}
 		}
 		return pb.ReadAnalogReaderResponse{
-			Value: int32(value),
+			Value:    int32(value),
+			MinRange: analogRange.Min,
+			MaxRange: analogRange.Max,
+			StepSize: analogRange.StepSize,
 		}, nil
 	})
 	return data.NewCollector(cFunc, params)

components/board/collectors_test.go

@@ -47,7 +47,10 @@ func TestCollectors(t *testing.T) {
 			},
 			collector: board.NewAnalogCollector,
 			expected: tu.ToProtoMapIgnoreOmitEmpty(pb.ReadAnalogReaderResponse{
-				Value: 1,
+				Value:    1,
+				MinRange: 0,
+				MaxRange: 10,
+				StepSize: 0.1,
 			}),
 			shouldError: false,
 		},
@@ -96,8 +99,8 @@ func TestCollectors(t *testing.T) {
 func newBoard() board.Board {
 	b := &inject.Board{}
 	analog := &inject.Analog{}
-	analog.ReadFunc = func(ctx context.Context, extra map[string]interface{}) (int, error) {
-		return 1, nil
+	analog.ReadFunc = func(ctx context.Context, extra map[string]interface{}) (int, board.AnalogRange, error) {
+		return 1, board.AnalogRange{Min: 0, Max: 10, StepSize: 0.1}, nil
 	}
 	b.AnalogByNameFunc = func(name string) (board.Analog, error) {
 		return analog, nil

components/board/fake/board.go

@@ -289,14 +289,18 @@ func (a *Analog) reset(pin string) {
 	a.Mu.Unlock()
 }
 
-func (a *Analog) Read(ctx context.Context, extra map[string]interface{}) (int, error) {
+func (a *Analog) Read(ctx context.Context, extra map[string]interface{}) (int, board.AnalogRange, error) {
 	a.Mu.RLock()
 	defer a.Mu.RUnlock()
 	if a.pin != analogTestPin {
 		a.Value = a.fakeValue
-		a.fakeValue++
+		if a.fakeValue == 1000 {
+			a.fakeValue = 0
+		} else {
+			a.fakeValue++
+		}
 	}
-	return a.Value, nil
+	return a.Value, board.AnalogRange{Min: 0, Max: 1000, StepSize: 1}, nil
 }
 
 func (a *Analog) Write(ctx context.Context, value int, extra map[string]interface{}) error {

components/board/genericlinux/board.go

@@ -351,11 +351,11 @@ func newWrappedAnalogReader(ctx context.Context, chipSelect string, reader *pinw
 	return &wrapped
 }
 
-func (a *wrappedAnalogReader) Read(ctx context.Context, extra map[string]interface{}) (int, error) {
+func (a *wrappedAnalogReader) Read(ctx context.Context, extra map[string]interface{}) (int, board.AnalogRange, error) {
 	a.mu.RLock()
 	defer a.mu.RUnlock()
 	if a.reader == nil {
-		return 0, errors.New("closed")
+		return 0, board.AnalogRange{}, errors.New("closed")
 	}
 	return a.reader.Read(ctx, extra)
 }

components/board/mcp3008helper/mcp3008.go

@@ -7,6 +7,7 @@ import (
 
 	"go.uber.org/multierr"
 
+	"go.viam.com/rdk/components/board"
 	"go.viam.com/rdk/components/board/genericlinux/buses"
 	"go.viam.com/rdk/grpc"
 	"go.viam.com/rdk/resource"
@@ -37,29 +38,32 @@ func (config *MCP3008AnalogConfig) Validate(path string) error {
 	return nil
 }
 
-func (mar *MCP3008AnalogReader) Read(ctx context.Context, extra map[string]interface{}) (value int, err error) {
+func (mar *MCP3008AnalogReader) Read(ctx context.Context, extra map[string]interface{}) (
+	value int, analogRange board.AnalogRange, err error,
+) {
 	var tx [3]byte
 	tx[0] = 1                            // start bit
 	tx[1] = byte((8 + mar.Channel) << 4) // single-ended
 	tx[2] = 0                            // extra clocks to receive full 10 bits of data
 
 	bus, err := mar.Bus.OpenHandle()
 	if err != nil {
-		return 0, err
+		return 0, board.AnalogRange{}, err
 	}
 	defer func() {
 		err = multierr.Combine(err, bus.Close())
 	}()
 
 	rx, err := bus.Xfer(ctx, 1000000, mar.Chip, 0, tx[:])
 	if err != nil {
-		return 0, err
+		return 0, board.AnalogRange{}, err
 	}
 	// Reassemble the 10-bit value. Do not include bits before the final 10, because they contain
 	// garbage and might be non-zero.
 	val := 0x03FF & ((int(rx[1]) << 8) | int(rx[2]))
 
-	return val, nil
+	// returning blank analog range since mcp3008 will be removed soon.
+	return val, board.AnalogRange{}, nil
 }
 
 // Close does nothing.

components/board/numato/board.go

@@ -117,6 +117,8 @@ type numatoBoard struct {
 	sent    map[string]bool
 	sentMu  sync.Mutex
 	workers rdkutils.StoppableWorkers
+
+	productID int
 }
 
 func (b *numatoBoard) addToSent(msg string) {
@@ -354,12 +356,44 @@ type analog struct {
 	pin string
 }
 
-func (a *analog) Read(ctx context.Context, extra map[string]interface{}) (int, error) {
+// analog Read returns the analog value with the range and step size in mV/bit.
+func (a *analog) Read(ctx context.Context, extra map[string]interface{}) (int, board.AnalogRange, error) {
 	res, err := a.b.doSendReceive(ctx, fmt.Sprintf("adc read %s", a.pin))
 	if err != nil {
-		return 0, err
+		return 0, board.AnalogRange{}, err
+	}
+	reading, err := strconv.Atoi(res)
+	if err != nil {
+		return 0, board.AnalogRange{}, err
 	}
-	return strconv.Atoi(res)
+	var max float32
+	var stepSize float32
+	switch a.b.productID {
+	case 0x805:
+		// 128 channel usb numato has 12 bit resolution
+		max = 3.3
+		stepSize = max / 4096
+	case 0x802:
+		// 32 channel usb numato has 10 bit resolution
+		max = 3.3
+		stepSize = max / 1024
+	case 0x800:
+		// 8 and 16 pin usb versions have the same product ID but different voltage ranges
+		// both have 10 bit resolution
+		if a.b.pins == 8 {
+			max = 5.0
+		} else if a.b.pins == 16 {
+			max = 3.3
+		}
+		stepSize = max / 1024
+	case 0xC05:
+		// 1 channel usb relay module numato - 10 bit resolution
+		max = 5.0
+		stepSize = max / 1024
+	default:
+	}
+	stepSize *= 1000
+	return reading, board.AnalogRange{Min: 0, Max: max, StepSize: stepSize}, nil
 }
 
 func (a *analog) Write(ctx context.Context, value int, extra map[string]interface{}) error {
@@ -384,6 +418,21 @@ func connect(ctx context.Context, name resource.Name, conf *Config, logger loggi
 		path = devs[0].Path
 	}
 
+	// Find the numato board's productid
+	products := getSerialDevices()
+
+	var productID int
+	for _, product := range products {
+		if product.ID.Vendor != 0x2a19 {
+			continue
+		}
+		productID = product.ID.Product
+	}
+
+	if productID != 0x805|0x802|0x800|0x0C05 {
+		logger.Warnf("analog range and step size is not supported for numato with product id %d", productID)
+	}
+
 	options := goserial.OpenOptions{
 		PortName:        path,
 		BaudRate:        19200,
@@ -396,12 +445,12 @@ func connect(ctx context.Context, name resource.Name, conf *Config, logger loggi
 	if err != nil {
 		return nil, err
 	}
-
 	b := &numatoBoard{
-		Named:  name.AsNamed(),
-		pins:   pins,
-		port:   device,
-		logger: logger,
+		Named:     name.AsNamed(),
+		pins:      pins,
+		port:      device,
+		logger:    logger,
+		productID: productID,
 	}
 
 	b.analogs = map[string]*pinwrappers.AnalogSmoother{}
@@ -419,6 +468,5 @@ func connect(ctx context.Context, name resource.Name, conf *Config, logger loggi
 		return nil, multierr.Combine(b.Close(ctx), err)
 	}
 	b.logger.CDebugw(ctx, "numato startup", "version", ver)
-
 	return b, nil
 }

components/board/numato/board_test.go

@@ -91,21 +91,25 @@ func TestNumato1(t *testing.T) {
 	ar, err := b.AnalogByName("foo")
 	test.That(t, err, test.ShouldBeNil, true)
 
-	res2, err := ar.Read(ctx, nil)
+	res2, analogRange, err := ar.Read(ctx, nil)
 	test.That(t, err, test.ShouldBeNil)
 	test.That(t, res2, test.ShouldBeLessThan, 100)
 
+	test.That(t, analogRange.Min, test.ShouldEqual, 0)
+	test.That(t, analogRange.Max, test.ShouldEqual, 5)
+	test.That(t, analogRange.StepSize, test.ShouldEqual, 4.88)
+
 	err = zeroPin.Set(context.Background(), true, nil)
 	test.That(t, err, test.ShouldBeNil)
 
-	res2, err = ar.Read(ctx, nil)
+	res2, _, err = ar.Read(ctx, nil)
 	test.That(t, err, test.ShouldBeNil)
 	test.That(t, res2, test.ShouldBeGreaterThan, 1000)
 
 	err = zeroPin.Set(context.Background(), false, nil)
 	test.That(t, err, test.ShouldBeNil)
 
-	res2, err = ar.Read(ctx, nil)
+	res2, _, err = ar.Read(ctx, nil)
 	test.That(t, err, test.ShouldBeNil)
 	test.That(t, res2, test.ShouldBeLessThan, 100)
 }

components/board/numato/darwin_utils.go

@@ -0,0 +1,11 @@
+//go:build darwin
+
+package numato
+
+import "go.viam.com/utils/usb"
+
+func getSerialDevices() []usb.Description {
+	return usb.Search(usb.NewSearchFilter("AppleUSBACMData", "usbmodem"), func(vendorID, productID int) bool {
+		return true
+	})
+}

components/board/numato/linux_utils.go

@@ -0,0 +1,11 @@
+//go:build linux
+
+package numato
+
+import "go.viam.com/utils/usb"
+
+func getSerialDevices() []usb.Description {
+	return usb.Search(usb.SearchFilter{}, func(vendorID, productID int) bool {
+		return true
+	})
+}

components/board/pi/impl/external_hardware_test.go

@@ -65,23 +65,23 @@ func TestPiHardware(t *testing.T) {
 		err = p.SetGPIOBcom(26, false)
 		test.That(t, err, test.ShouldBeNil)
 
-		v, err := reader.Read(ctx, nil)
+		v, _, err := reader.Read(ctx, nil)
 		test.That(t, err, test.ShouldBeNil)
 		test.That(t, v, test.ShouldAlmostEqual, 0, 150)
 
 		// try to set high
 		err = p.SetGPIOBcom(26, true)
 		test.That(t, err, test.ShouldBeNil)
 
-		v, err = reader.Read(ctx, nil)
+		v, _, err = reader.Read(ctx, nil)
 		test.That(t, err, test.ShouldBeNil)
 		test.That(t, v, test.ShouldAlmostEqual, 1023, 150)
 
 		// back to low
 		err = p.SetGPIOBcom(26, false)
 		test.That(t, err, test.ShouldBeNil)
 
-		v, err = reader.Read(ctx, nil)
+		v, _, err = reader.Read(ctx, nil)
 		test.That(t, err, test.ShouldBeNil)
 		test.That(t, v, test.ShouldAlmostEqual, 0, 150)
 	})