[APP-7635]: Define type for managing bluetooth WiFi provisioning.

go.mod

@@ -11,6 +11,7 @@ require (
 	github.com/pkg/errors v0.9.1
 	github.com/sergeymakinen/go-systemdconf/v2 v2.0.2
 	github.com/ulikunitz/xz v0.5.12
+	go.uber.org/multierr v1.11.0
 	go.uber.org/zap v1.27.0
 	go.viam.com/api v0.1.357
 	go.viam.com/rdk v0.51.0
@@ -79,7 +80,6 @@ require (
 	go.mongodb.org/mongo-driver v1.17.1 // indirect
 	go.opencensus.io v0.24.0 // indirect
 	go.uber.org/goleak v1.3.0 // indirect
-	go.uber.org/multierr v1.11.0 // indirect
 	golang.org/x/crypto v0.28.0 // indirect
 	golang.org/x/mod v0.21.0 // indirect
 	golang.org/x/net v0.30.0 // indirect

subsystems/provisioning/bluetooth/bluetooth_wifi_provisioner.go

@@ -0,0 +1,169 @@
+// Package ble contains an interface for using bluetooth-low-energy to retrieve WiFi and robot part credentials for an unprovisioned Agent.
+package ble
+
+import (
+	"context"
+	"encoding/json"
+	"runtime"
+	"sync"
+
+	"errors"
+
+	errw "github.com/pkg/errors"
+	"go.uber.org/multierr"
+	"go.viam.com/rdk/logging"
+	"go.viam.com/utils"
+)
+
+// Credentials represent the minimum required information needed to provision a Viam Agent.
+type Credentials struct {
+	Ssid           string
+	Psk            string
+	RobotPartKeyID string
+	RobotPartKey   string
+}
+
+// AvailableWiFiNetworks represent the networks that the device has detected (and which may be available for connection).
+type AvailableWiFiNetworks struct {
+	Networks []*struct {
+		Ssid        string  `json:"ssid"`
+		Strength    float64 `json:"strength"` // Inclusive range [0.0, 1.0], represents the % strength of a WiFi network.
+		RequiresPsk bool    `json:"requires_psk"`
+	} `json:"networks"`
+}
+
+func (awns *AvailableWiFiNetworks) ToBytes() ([]byte, error) {
+	return json.Marshal(awns)
+}
+
+// bluetoothWiFiProvisioner provides an interface for managing BLE (bluetooth-low-energy) peripheral advertisement on Linux.
+type BluetoothWiFiProvisioner struct{}
+
+// Start begins advertising a bluetooth service that acccepts WiFi and Viam cloud config credentials.
+func (bwp *BluetoothWiFiProvisioner) Start(ctx context.Context) error {
+	if err := bwp.startAdvertisingBLE(ctx); err != nil {
+		return err
+	}
+	bwp.enableAutoAcceptPairRequest() // Async goroutine (hence no error check) which auto-accepts pair requests on this device.
+	return nil
+}
+
+// Stop stops advertising a bluetooth service which (when enabled) accepts WiFi and Viam cloud config credentials.
+func (bwp *BluetoothWiFiProvisioner) Stop() error {
+	return bwp.stopAdvertisingBLE()
+}
+
+// Update updates the list of networks that are advertised via bluetooth as available.
+func (bwp *BluetoothWiFiProvisioner) RefreshAvailableNetworks(ctx context.Context, awns *AvailableWiFiNetworks) error {
+	return bwp.writeAvailableNetworks(ctx, awns)
+}
+
+// WaitForCredentials returns credentials, the minimum required information to provision a robot and/or its WiFi.
+func (bwp *BluetoothWiFiProvisioner) WaitForCredentials(ctx context.Context, requiresCloudCredentials bool, requiresWiFiCredentials bool) (*Credentials, error) {
+	ctx, cancel := context.WithCancel(ctx)
+	defer cancel()
+
+	if !requiresWiFiCredentials && !requiresCloudCredentials {
+		return nil, errors.New("should be waiting for either cloud credentials or WiFi credentials")
+	}
+	var ssid, psk, robotPartKeyID, robotPartKey string
+	var ssidErr, pskErr, robotPartKeyIDErr, robotPartKeyErr error
+	wg := &sync.WaitGroup{}
+	if requiresWiFiCredentials {
+		wg.Add(2)
+		utils.ManagedGo(
+			func() {
+				if ssid, ssidErr = retryCallbackOnEmptyCharacteristicError(
+					ctx, bwp.readSsid, "ssid",
+				); ssidErr != nil {
+					cancel()
+				}
+			},
+			wg.Done,
+		)
+		utils.ManagedGo(
+			func() {
+				if psk, pskErr = retryCallbackOnEmptyCharacteristicError(
+					ctx, bwp.readPsk, "psk",
+				); pskErr != nil {
+					cancel()
+				}
+
+			},
+			wg.Done,
+		)
+	}
+	if requiresCloudCredentials {
+		wg.Add(2)
+		utils.ManagedGo(
+			func() {
+				if robotPartKeyID, robotPartKeyIDErr = retryCallbackOnEmptyCharacteristicError(
+					ctx, bwp.readRobotPartKeyID, "robot part key ID",
+				); robotPartKeyIDErr != nil {
+					cancel()
+				}
+			},
+			wg.Done,
+		)
+		utils.ManagedGo(
+			func() {
+				if robotPartKey, robotPartKeyErr = retryCallbackOnEmptyCharacteristicError(
+					ctx, bwp.readRobotPartKey, "robot part key",
+				); robotPartKeyErr != nil {
+					cancel()
+				}
+			},
+			wg.Done,
+		)
+	}
+	wg.Wait()
+	return &Credentials{
+		Ssid: ssid, Psk: psk, RobotPartKeyID: robotPartKeyID, RobotPartKey: robotPartKey,
+	}, multierr.Combine(ssidErr, pskErr, robotPartKeyIDErr, robotPartKeyErr)
+}
+
+/** Unexported helper methods for low-level system calls and read/write requests to/from bluetooth characteristics **/
+
+func (bwp *BluetoothWiFiProvisioner) startAdvertisingBLE(ctx context.Context) error {
+	return errors.New("TODO APP-7644: Add Linux-specific bluetooth calls for automatic pairing and read/write to BLE characteristics")
+}
+
+func (bwp *BluetoothWiFiProvisioner) stopAdvertisingBLE() error {
+	return errors.New("TODO APP-7644: Add Linux-specific bluetooth calls for automatic pairing and read/write to BLE characteristics")
+}
+
+func (bwp *BluetoothWiFiProvisioner) enableAutoAcceptPairRequest() {}
+
+func (bwp *BluetoothWiFiProvisioner) writeAvailableNetworks(ctx context.Context, networks *AvailableWiFiNetworks) error {
+	return errors.New("TODO APP-7644: Add Linux-specific bluetooth calls for automatic pairing and read/write to BLE characteristics")
+}
+
+func (bwp *BluetoothWiFiProvisioner) readSsid() (string, error) {
+	return "", errors.New("TODO APP-7644: Add Linux-specific bluetooth calls for automatic pairing and read/write to BLE characteristics")
+}
+
+func (bwp *BluetoothWiFiProvisioner) readPsk() (string, error) {
+	return "", errors.New("TODO APP-7644: Add Linux-specific bluetooth calls for automatic pairing and read/write to BLE characteristics")
+}
+
+func (bwp *BluetoothWiFiProvisioner) readRobotPartKeyID() (string, error) {
+	return "", errors.New("TODO APP-7644: Add Linux-specific bluetooth calls for automatic pairing and read/write to BLE characteristics")
+}
+
+func (bwp *BluetoothWiFiProvisioner) readRobotPartKey() (string, error) {
+	return "", errors.New("TODO APP-7644: Add Linux-specific bluetooth calls for automatic pairing and read/write to BLE characteristics")
+}
+
+// NewBluetoothWiFiProvisioner returns a service which accepts credentials over bluetooth to provision a robot and its WiFi connection.
+func NewBluetoothWiFiProvisioner(ctx context.Context, logger logging.Logger, name string) (*BluetoothWiFiProvisioner, error) {
+	switch os := runtime.GOOS; os {
+	case "linux":
+		fallthrough
+	case "windows":
+		fallthrough
+	case "darwin":
+		fallthrough
+	default:
+		return nil, errw.Errorf("failed to set up bluetooth-low-energy peripheral, %s is not yet supported", os)
+	}
+}

subsystems/provisioning/bluetooth/bluetooth_wifi_provisioner_utils.go

@@ -0,0 +1,44 @@
+package ble
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/pkg/errors"
+)
+
+// emptyBluetoothCharacteristicError represents the error which is raised when we attempt to read from an empty BLE characteristic.
+type emptyBluetoothCharacteristicError struct {
+	missingValue string
+}
+
+func (e *emptyBluetoothCharacteristicError) Error() string {
+	return fmt.Sprintf("no value has been written to BLE characteristic for %s", e.missingValue)
+}
+
+// waitForBLE is used to check for the existence of a new value in a BLE characteristic.
+func retryCallbackOnEmptyCharacteristicError(
+	ctx context.Context, fn func() (string, error), description string,
+) (string, error) {
+	for {
+		if ctx.Err() != nil {
+			return "", ctx.Err()
+		}
+		select {
+		case <-ctx.Done():
+			return "", ctx.Err()
+		default:
+			time.Sleep(time.Second)
+		}
+		v, err := fn()
+		if err != nil {
+			var errBLECharNoValue *emptyBluetoothCharacteristicError
+			if errors.As(err, &errBLECharNoValue) {
+				continue
+			}
+			return "", errors.WithMessagef(err, "failed to read %s", description)
+		}
+		return v, nil
+	}
+}