Documentation updates from Promptless

Author: npentrel

docs/manage/fleet/provision/bluetooth-provisioning.md

@@ -0,0 +1,282 @@
+---
+title: "Bluetooth provisioning with viam-agent"
+linkTitle: "Bluetooth provisioning"
+weight: 70
+type: "docs"
+description: "Learn how to use Bluetooth Low Energy (BLE) for machine provisioning as an alternative to WiFi hotspot provisioning."
+tags: ["fleet management", "viam-server", "viam-agent", "bluetooth", "provisioning"]
+images: ["/installation/thumbnails/install.png"]
+imageAlt: "Bluetooth provisioning"
+languages: []
+viamresources: []
+platformarea: ["fleet"]
+level: "Advanced"
+date: "2025-06-02"
+prev: "/manage/fleet/provision/end-user-setup/"
+# updated: ""  # When the tutorial was last entirely checked
+# SMEs: James, Ale
+cost: "0"
+---
+
+Bluetooth provisioning enables machine setup using Bluetooth Low Energy (BLE) as an alternative to WiFi hotspot provisioning. This method is particularly useful in environments with many WiFi networks, where hotspot provisioning may be less reliable, or when you want to avoid creating an open WiFi hotspot.
+
+## Overview
+
+When Bluetooth provisioning is enabled, `viam-agent` advertises a BLE service that mobile applications can connect to directly. This allows users to provision machines without needing to join a WiFi hotspot, providing a more streamlined setup experience on mobile devices.
+
+### Key Features
+
+- **Direct BLE connection**: Mobile apps connect directly to the machine via Bluetooth
+- **Encrypted communication**: All credential exchanges use RSA OAEP encryption
+- **Parallel operation**: Can work alongside WiFi hotspot provisioning
+- **Mobile-optimized**: Designed for optimal mobile app user experience
+- **Automatic adapter selection**: Automatically selects the first available Bluetooth adapter
+
+## How Bluetooth Provisioning Works
+
+1. **Service Advertisement**: When provisioning mode starts, `viam-agent` advertises a BLE service with a name beginning with `viam-setup-`
+1. **Mobile App Discovery**: Compatible mobile apps scan for and connect to the advertised BLE service
+1. **Secure Handshake**: The machine generates an RSA key pair and shares the public key with the mobile app
+1. **Credential Exchange**: The mobile app encrypts and sends WiFi credentials and/or machine credentials
+1. **Network Connection**: The machine attempts to connect using the provided credentials
+1. **Service Installation**: Once connected, `viam-agent` installs and starts `viam-server`
+
+## Configuration
+
+### Basic Configuration
+
+To enable Bluetooth provisioning, ensure `disable_bt_provisioning` is set to `false` (the default) in your `viam-defaults.json`:
+
+```json {class="line-numbers linkable-line-numbers"}
+{
+  "network_configuration": {
+    "disable_bt_provisioning": false,
+    "disable_wifi_provisioning": false
+  }
+}
+```
+
+### Advanced Configuration
+
+For machines with multiple Bluetooth adapters, specify which adapter to use:
+
+```json {class="line-numbers linkable-line-numbers"}
+{
+  "network_configuration": {
+    "disable_bt_provisioning": false,
+    "bluetooth_adapter_name": "hci0"
+  }
+}
+```
+
+### Bluetooth-Only Provisioning
+
+To use only Bluetooth provisioning and disable WiFi hotspot provisioning:
+
+```json {class="line-numbers linkable-line-numbers"}
+{
+  "network_configuration": {
+    "disable_bt_provisioning": false,
+    "disable_wifi_provisioning": true,
+    "fragment_id": "your-fragment-id"
+  }
+}
+```
+
+{{< alert title="Note" color="note" >}}
+When using Bluetooth-only provisioning, you must provide a `fragment_id` for mobile app configuration.
+{{< /alert >}}
+
+## Security
+
+Bluetooth provisioning implements several security measures:
+
+### Encryption
+
+- **RSA OAEP Encryption**: All credential data is encrypted using RSA OAEP with SHA-256
+- **2048-bit Keys**: Uses 2048-bit RSA keys for strong encryption
+- **Per-Session Keys**: New key pairs are generated for each provisioning session
+- **Public Key Exchange**: Public keys are shared using x509 PKIX encoding
+
+### Communication Protocol
+
+The BLE service uses predefined UUIDs for different characteristics:
+
+- **Service UUID**: Generated from namespace `74a942f4-0f45-43f4-88ca-f87021ae36ea`
+- **Write Characteristics**: For receiving encrypted credentials (SSID, PSK, machine credentials)
+- **Read Characteristics**: For sharing status, network lists, and public keys
+- **Encrypted Payloads**: All sensitive data is encrypted before transmission
+
+## Bluetooth Service Characteristics
+
+The Bluetooth service exposes several characteristics for different functions:
+
+### Write-Only Characteristics
+
+- **SSID**: Receives encrypted WiFi network name
+- **PSK**: Receives encrypted WiFi password
+- **Robot Part ID**: Receives encrypted machine part identifier
+- **Robot Part Secret**: Receives encrypted machine secret
+- **App Address**: Receives encrypted cloud app address
+
+### Read-Only Characteristics
+
+- **Status**: Provides machine configuration and connection status
+- **Networks**: Lists available WiFi networks with signal strength and security info
+- **Public Key**: Shares the RSA public key for encryption
+- **Errors**: Reports any provisioning errors
+
+## Mobile App Integration
+
+### Supported Platforms
+
+Bluetooth provisioning is designed for mobile applications using:
+
+- **Flutter SDK**: Full BLE provisioning support
+- **TypeScript SDK**: BLE provisioning capabilities
+- **Viam Mobile App**: Native Bluetooth provisioning support
+
+### App Development Considerations
+
+When developing mobile apps with Bluetooth provisioning:
+
+1. **BLE Permissions**: Ensure your app requests appropriate Bluetooth permissions
+1. **Service Discovery**: Scan for services with the `viam-setup-` prefix
+1. **Encryption Handling**: Implement RSA OAEP encryption for credential transmission
+1. **Error Handling**: Monitor the errors characteristic for provisioning feedback
+1. **Status Monitoring**: Check the status characteristic to track provisioning progress
+
+## Troubleshooting
+
+### Bluetooth Adapter Issues
+
+**Problem**: Bluetooth provisioning not starting
+
+**Solutions**:
+1. Check if Bluetooth is available:
+   ```sh {class="command-line" data-prompt="$"}
+   bluetoothctl list
+   ```
+
+1. Verify Bluetooth service status:
+   ```sh {class="command-line" data-prompt="$"}
+   sudo systemctl status bluetooth
+   ```
+
+1. For multiple adapters, specify the correct one:
+   ```json
+   {
+     "network_configuration": {
+       "bluetooth_adapter_name": "hci0"
+     }
+   }
+   ```
+
+### Mobile Device Connection Issues
+
+**Problem**: Mobile app cannot discover the machine
+
+**Solutions**:
+1. Ensure Bluetooth is enabled on the mobile device
+1. Check that the mobile app has Bluetooth permissions
+1. Verify the device supports Bluetooth Low Energy (BLE)
+1. Try restarting Bluetooth on the mobile device
+
+### Encryption Errors
+
+**Problem**: Credential transmission fails
+
+**Solutions**:
+1. Check `viam-agent` logs for encryption errors:
+   ```sh {class="command-line" data-prompt="$"}
+   sudo journalctl -u viam-agent -f
+   ```
+
+1. Ensure the mobile app is using the correct public key
+1. Verify RSA OAEP implementation in the mobile app
+
+### Configuration Issues
+
+**Problem**: Bluetooth provisioning not enabled
+
+**Solutions**:
+1. Verify `disable_bt_provisioning` is set to `false`
+1. Check that `disable_network_configuration` is not set to `true`
+1. Ensure the system has a working Bluetooth adapter
+
+## Testing and Development
+
+### CLI Testing Tool
+
+The `viam-agent` repository includes a CLI tool for testing Bluetooth provisioning:
+
+```sh {class="command-line" data-prompt="$"}
+# Clone the agent repository
+git clone https://github.com/viamrobotics/agent.git
+cd agent
+
+# Scan for Bluetooth devices
+go run ./cmd/provisioning-client/ --scan
+
+# Test Bluetooth provisioning
+go run ./cmd/provisioning-client/ --bluetooth --status
+
+# Set WiFi credentials via Bluetooth
+go run ./cmd/provisioning-client/ --bluetooth --ssid="MyNetwork" --psk="MyPassword"
+
+# Set machine credentials via Bluetooth
+go run ./cmd/provisioning-client/ --bluetooth --partID="part-id" --secret="secret" --appaddr="https://app.viam.com:443"
+```
+
+### Development Environment
+
+For development and testing:
+
+1. **Filter Devices**: Use the `--filter` option to find specific devices:
+   ```sh {class="command-line" data-prompt="$"}
+   go run ./cmd/provisioning-client/ --scan --filter="viam-setup"
+   ```
+
+1. **Monitor Status**: Check provisioning status:
+   ```sh {class="command-line" data-prompt="$"}
+   go run ./cmd/provisioning-client/ --bluetooth --status
+   ```
+
+1. **List Networks**: View available WiFi networks:
+   ```sh {class="command-line" data-prompt="$"}
+   go run ./cmd/provisioning-client/ --bluetooth --networks
+   ```
+
+## Best Practices
+
+### Configuration
+
+- **Enable Both Methods**: Keep both Bluetooth and WiFi provisioning enabled for maximum compatibility
+- **Fragment Configuration**: Always provide a `fragment_id` when using mobile apps
+- **Adapter Selection**: Specify `bluetooth_adapter_name` for machines with multiple Bluetooth adapters
+
+### Security
+
+- **Key Management**: RSA keys are automatically generated per session - no manual key management required
+- **Credential Handling**: All sensitive data is encrypted before transmission
+- **Network Security**: Consider the security of the WiFi networks being configured
+
+### User Experience
+
+- **Clear Instructions**: Provide clear setup instructions for end users
+- **Fallback Options**: Ensure WiFi hotspot provisioning is available as a fallback
+- **Error Reporting**: Monitor the errors characteristic for user feedback
+
+## Limitations
+
+- **BLE Requirement**: Both the machine and mobile device must support Bluetooth Low Energy
+- **Mobile Focus**: Optimized for mobile app workflows rather than web browsers
+- **Linux Support**: Currently supported on Linux systems with Bluetooth adapters
+- **Range Limitation**: Bluetooth has a shorter range than WiFi hotspots
+
+## Next Steps
+
+- [Set up machine provisioning](/manage/fleet/provision/setup/)
+- [Configure viam-agent](/manage/reference/viam-agent/)
+- [End-user setup guide](/manage/fleet/provision/end-user-setup/)
+- [Mobile app development with Flutter SDK](https://flutter.viam.dev/)

docs/manage/fleet/provision/end-user-setup.md

@@ -29,6 +29,13 @@ Unless you have been told to use the captive portal, we recommend you use the Vi
 
 ## Set up your machine using the Viam mobile app
 
+The Viam mobile app supports two connection methods for machine setup:
+
+- **Bluetooth provisioning**: The app connects directly to your machine via Bluetooth Low Energy (BLE) without needing to join a WiFi network
+- **WiFi hotspot provisioning**: The app connects to your machine through a temporary WiFi hotspot
+
+The app will automatically choose the best available method. If your machine supports Bluetooth provisioning, the app will prefer that method for a smoother setup experience.
+
 {{<video webm_src="/platform/provisioning-demo.webm" mp4_src="/platform/provisioning-demo.mp4" alt="Using the Viam mobile app to provision a new machine with viam-agent." poster="/platform/provisioning-demo.jpg" max-width="300px" class="">}}
 
 {{< table >}}
@@ -55,23 +62,32 @@ If you have already created a machine, select it.
 If you have not yet created a machine, click on **Add new smart machine** and give your machine a name.
 {{% /tablestep %}}
 {{% tablestep number=3 %}}
-**Follow the instructions in the app**
+**Turn on your machine and follow the app instructions**
 
 Turn on the smart machine you are attempting to connect to.
-Then leave the app and navigate to your mobile device's WiFi settings and connect to the WiFi hotspot your machine has created.
-You may need to wait a short time for your machine to boot and create its WiFi hotspot.
+The app will guide you through the connection process.
+
+**If using Bluetooth provisioning:**
+- Ensure Bluetooth is enabled on your mobile device
+- The app will automatically scan for and connect to your machine's Bluetooth service
+- Your machine will advertise a Bluetooth service with a name beginning with `viam-setup-`
+
+**If using WiFi hotspot provisioning:**
+- Leave the app and navigate to your mobile device's WiFi settings
+- Connect to the WiFi hotspot your machine has created
 Your machine's WiFi hotspot name will begin with `viam-setup-`.
 Unless you have been given other instructions, the WiFi password for this hotspot network is `viamsetup`.
+- Return to the Viam mobile app once connected
 
-Once you are connected to your machine's WiFi hotspot return to the Viam mobile app.
+You may need to wait a short time for your machine to boot and start its provisioning services.
 {{% /tablestep %}}
 {{% tablestep number=4 %}}
 **Provide the network information for the machine**
 
 In the mobile app, you will be prompted to provide the network information for the machine.
 
-The machine will now disable the hotspot network and attempt to connect using the provided network information.
-If the machine cannot establish a connection using the provided network information, the machine will create the hotspot again and prompt you to re-enter the network information until a connection is successfully established.
+The machine will now attempt to connect using the provided network information.
+If the machine cannot establish a connection using the provided network information, it will continue to be available for provisioning and prompt you to re-enter the network information until a connection is successfully established.
 {{% /tablestep %}}
 {{% tablestep number=5 %}}
 **Wait for machine to complete setup**
@@ -135,6 +151,34 @@ Note that any features that require internet access will not function if the con
 {{% /tablestep %}}
 {{< /table >}}
 
+## Troubleshooting
+
+### Bluetooth connection issues
+
+If you're having trouble with Bluetooth provisioning:
+
+1. **Check Bluetooth permissions**: Ensure the Viam mobile app has Bluetooth permissions enabled on your device.
+
+1. **Verify Bluetooth is enabled**: Make sure Bluetooth is turned on in your mobile device settings.
+
+1. **Check device compatibility**: Ensure your mobile device supports Bluetooth Low Energy (BLE).
+
+1. **Restart Bluetooth**: Try turning Bluetooth off and on again on your mobile device.
+
+1. **Try WiFi hotspot method**: If Bluetooth provisioning continues to have issues, you can fall back to connecting to your machine's WiFi hotspot and using that method instead.
+
+### WiFi connection issues
+
+If your machine cannot connect to your WiFi network:
+
+1. **Check network credentials**: Verify that the WiFi network name (SSID) and password are correct.
+
+1. **Check network compatibility**: Ensure your WiFi network is compatible with your machine's WiFi adapter.
+
+1. **Check signal strength**: Make sure your machine is within range of your WiFi router.
+
+1. **Try a different network**: If possible, try connecting to a different WiFi network to isolate the issue.
+
 ## Next Steps
 
 You can now use your machine.