DOCS-3498: Add Bluetooth provisioning docs for viam-agent #4372
Conversation
![promptless[bot]](https://avatars.githubusercontent.com/in/979718?s=60&v=4){kind=small}
✅ Deploy Preview for viam-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
👋 Thanks for contributing! A reviewer will look at it on the next working day! |
|
Just a reminder: If you'd like me to act on any feedback you have via Github comments, just type @Promptless in your suggestion and I'll get right on it! (I won't show up in the user dropdown, but I'll process any request that has @Promptless in the comment body.) |
npentrel
force-pushed
the
docs-update-e68716ac-6be7-45c4-a6cf-67c928da318a-20250602-115258
branch
2 times, most recently
from
92d5028 to
d7c4135
Compare
npentrel
changed the title
npentrel
changed the title
| @@ -74,100 +77,10 @@ If you do not yet have a fragment, follow the steps to [Create a configuration f | |||
| If you are not using Flutter or TypeScript and would like to use provisioning, please [contact us](mailto:[email protected]). | |||
| {{< /alert >}} | |||
|
|
|||
| If you choose to use the captive web portal, you can optionally create a machine in advance and provide its machine cloud credentials file at <FILE>/etc/viam.json</FILE>. | |||
npentrel
force-pushed
the
docs-update-e68716ac-6be7-45c4-a6cf-67c928da318a-20250602-115258
branch
2 times, most recently
from
ed4f6a1 to
70564c6
Compare
npentrel
force-pushed
the
docs-update-e68716ac-6be7-45c4-a6cf-67c928da318a-20250602-115258
branch
from
70564c6 to
7befc24
Compare
|
It looks like the following files may have been renamed. Please ensure you set all needed aliases: |
npentrel
force-pushed
the
docs-update-e68716ac-6be7-45c4-a6cf-67c928da318a-20250602-115258
branch
from
7befc24 to
61b7005
Compare
npentrel
force-pushed
the
docs-update-e68716ac-6be7-45c4-a6cf-67c928da318a-20250602-115258
branch
from
61b7005 to
44c5986
Compare
| | `disable_captive_portal_redirect` | boolean | Optional | By default, ALL DNS lookups using the provisioning hotspot will redirect to the device. This causes most phones/mobile devices to automatically redirect the user to the captive portal as a "sign in" screen. When disabled, only domains ending in .setup (ex: viam.setup) will be redirected. This generally avoids displaying the portal to users and is mainly used in conjunction with a mobile provisioning application workflow. Default: `false`. | | ||
| | `fragment_id` | string | Optional | The `fragment_id` of the fragment to configure machines with. Required when using the Viam mobile app for provisioning. The Viam mobile app uses the fragment to configure the machine. | | ||
| | `disable_wifi_provisioning` | boolean | Optional | When set to true, disables WiFi hotspot provisioning. The machine will not create a WiFi hotspot for provisioning. Both WiFi hotspot and Bluetooth provisioning can be enabled simultaneously. Default: `false`. | | ||
| | `bluetooth_trust_all` | boolean | Optional | When true, the machine accepts all Bluetooth pairing requests for sharing the internet from a mobile device (tethering) without requiring devices to be added during provisioning first. Default: `false`. | |
There was a problem hiding this comment.
@Otterverse Is this an accurate description? Is there a succinct reason why someone would want to do this? Aside from not having to go through the trust dialogue once? I suppose rather - is this because the trust dialogue would happen on the machine that is being provisioned which may have no screen so adding this here means headless provisioning will work?
There was a problem hiding this comment.
may have no screen so adding this here means headless provisioning will work?
i believe this is accurate
There was a problem hiding this comment.
| | `bluetooth_trust_all` | boolean | Optional | When true, the machine accepts all Bluetooth pairing requests for sharing the internet from a mobile device (tethering) without requiring devices to be added during provisioning first. Default: `false`. | | |
| | `bluetooth_trust_all` | boolean | Optional | Set to true to accept all Bluetooth pairing requests (which is only needed for bluetooth tethering) without requiring an unlock command from a mobile app. Default: `false`. | |
Suggestion is the same as comment in the json template earlier in this file.
|
|
||
| The [Flutter Provisioning package](https://github.com/viamrobotics/viam_flutter_provisioning/) shows an example for Bluetooth provisioning. | ||
|
|
||
| When developing your own application, if you support both Bluetooth and WiFi Hotspot provisioning, make the app choose the best available method. |
There was a problem hiding this comment.
This makes it sounds like the app should automatically figure out which method to use which this should be a decision made by the developer
|
|
||
| 1. Verify the device supports Bluetooth Low Energy (BLE) | ||
|
|
||
| 1. **Check Bluetooth permissions**: Ensure the Viam mobile app has Bluetooth permissions enabled on your device. |
There was a problem hiding this comment.
are the specific permissions document it in the flutter package?
| | `disable_captive_portal_redirect` | boolean | Optional | By default, ALL DNS lookups using the provisioning hotspot will redirect to the device. This causes most phones/mobile devices to automatically redirect the user to the captive portal as a "sign in" screen. When disabled, only domains ending in .setup (ex: viam.setup) will be redirected. This generally avoids displaying the portal to users and is mainly used in conjunction with a mobile provisioning application workflow. Default: `false`. | | ||
| | `fragment_id` | string | Optional | The `fragment_id` of the fragment to configure machines with. Required when using the Viam mobile app for provisioning. The Viam mobile app uses the fragment to configure the machine. | | ||
| | `disable_wifi_provisioning` | boolean | Optional | When set to true, disables WiFi hotspot provisioning. The machine will not create a WiFi hotspot for provisioning. Both WiFi hotspot and Bluetooth provisioning can be enabled simultaneously. Default: `false`. | | ||
| | `bluetooth_trust_all` | boolean | Optional | When true, the machine accepts all Bluetooth pairing requests for sharing the internet from a mobile device (tethering) without requiring devices to be added during provisioning first. Default: `false`. | |
There was a problem hiding this comment.
may have no screen so adding this here means headless provisioning will work?
i believe this is accurate
| We recommend using Bluetooth by default for a smoother setup experience. | ||
|
|
||
| The Flutter Provisioning package supports bluetooth tethering, that is sharing your mobile devices's internet connection with the machine that will be provisioned. | ||
| Bluetooth tethering is slow and we recommend you use WiFi where possible. |
There was a problem hiding this comment.
I'm not sure why we mention BT tethering here. It's not intricately related to provisioning. Is so the user discovers BT tethering? I guess my concern would be that if someone is confused about provisoning maybe this will add more confusion
There was a problem hiding this comment.
I think what I should probably do is list the permissions of the provisioning package. I'll make that change
| ## Set up your machine using a custom Flutter app | ||
|
|
||
| The [Flutter Provisioning package](https://github.com/viamrobotics/viam_flutter_provisioning/) shows an example for Bluetooth provisioning. | ||
|
|
||
| When developing your own application, if you support both Bluetooth and WiFi Hotspot provisioning and both are available, we recommend using Bluetooth by default for a smoother setup experience. | ||
| We recommend using Bluetooth by default for a smoother setup experience. | ||
|
|
||
| The Flutter Provisioning package supports bluetooth tethering, that is sharing your mobile devices's internet connection with the machine that will be provisioned. | ||
| Bluetooth tethering is slow and we recommend you use WiFi where possible. |
There was a problem hiding this comment.
| ## Set up your machine using a custom Flutter app | |
| The [Flutter Provisioning package](https://github.com/viamrobotics/viam_flutter_provisioning/) shows an example for Bluetooth provisioning. | |
| When developing your own application, if you support both Bluetooth and WiFi Hotspot provisioning and both are available, we recommend using Bluetooth by default for a smoother setup experience. | |
| We recommend using Bluetooth by default for a smoother setup experience. | |
| The Flutter Provisioning package supports bluetooth tethering, that is sharing your mobile devices's internet connection with the machine that will be provisioned. | |
| Bluetooth tethering is slow and we recommend you use WiFi where possible. | |
| ## Set up your machine using a custom Flutter app | |
| The [Flutter Provisioning package](https://github.com/viamrobotics/viam_flutter_provisioning/) shows an example for Bluetooth provisioning. | |
| Features: | |
| - **Bluetooth provisioning**: We recommend using Bluetooth over WiFi hotspot provisioning for a smoother setup experience. | |
| - **WiFi Hotspot provisioning** | |
| - **Bluetooth tethering**: Bluetooth tethering (sharing your mobile devices's internet connection with the machine that will be provisioned) is slow and we recommend you use WiFi where possible. |
| Once you are connected to your machine's WiFi hotspot return to the Viam mobile app. | ||
| Return to the Viam mobile app once connected | ||
|
|
||
| You may need to wait a short time for your machine to boot and start its provisioning services. |
There was a problem hiding this comment.
Isn't this basically duplicating the instructions in line 62 above?
| When developing your own application, if you support both Bluetooth and WiFi Hotspot provisioning and both are available, we recommend using Bluetooth by default for a smoother setup experience. | ||
| We recommend using Bluetooth by default for a smoother setup experience. |
There was a problem hiding this comment.
Duplicated text on the second line.
|
|
||
| ### App Development Considerations | ||
|
|
||
| When developing mobile apps with Bluetooth provisioning, ensure your app requests appropriate Bluetooth permissions. |
There was a problem hiding this comment.
Should explicitly say what permissions these are or maybe link to that elsewhere (is it mentioned in the readme/docs for the flutter repo?)
|
|
||
| If you're having trouble with Bluetooth provisioning: | ||
|
|
||
| 1. Verify the device supports Bluetooth Low Energy (BLE) |
There was a problem hiding this comment.
What's the actual action a user should take here?
I'm not asking that rhetorically... I don't have a full answer to this myself, as it's complicated, and we've really only tested on a few devices. But it feels wrong to tell people "verify this is supported" when we're the ones that should be saying what is or is not supported.
|
|
||
| 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). |
There was a problem hiding this comment.
Similar to above comment. Exactly how/what is a user supposed to check here?
Two other issues.
First, this says "check device compatibility" but a couple lines up we have "verify the device supports BLE". That feels very confusing to me. I think terminology needs to much more clearly separate "mobile phone (device)" and "smart machine (device)"
Lastly, this COULD probably just be removed entirely. The installation of the mobile app itself should be able to report when it cannot work because of missing hardware... and I don't think there's any phone from the past 10 years that doesn't have BLE, so this would only apply to some weird, one-off android devices (like a kiosk or something) at best.
| | `priority` | int | Priority to choose the network with. Values between -999 and 999. Default: `0`. | | ||
|
|
||
| {{% /tablestep %}} | ||
| {{< /table >}} | ||
|
|
||
| ## (Optional) Create a machine in advance | ||
|
|
||
| If you provision devices using a captive web portal, you can optionally create a machine in advance and provide its machine cloud credentials file at <FILE>/etc/viam.json</FILE>. |
There was a problem hiding this comment.
| If you provision devices using a captive web portal, you can optionally create a machine in advance and provide its machine cloud credentials file at <FILE>/etc/viam.json</FILE>. | |
| If you provision devices using a captive web portal (instead of a mobile app), you'll need to create a machine in advance and provide its machine cloud credentials in the portal. Alternately, you may directly write them to the file <FILE>/etc/viam.json</FILE>. |
| WiFi provisioning may be less reliable in environments with many WiFi networks. | ||
| If possible, use Bluetooth provisioning or move to an area with fewer WiFi networks in range. |
There was a problem hiding this comment.
Bluetooth is just as likely to have interference from nearby sources as wifi is, so I don't think this suggestion is useful. Have we actually seen cases of this? If not, I'm wondering where this advice came from.
|
|
||
| ### Bluetooth provisioning not working | ||
|
|
||
| If Bluetooth provisioning is not working, check the following: |
There was a problem hiding this comment.
Isn't this section duplicating the same info that is in end-user-setup.md? Feels like one of these troubleshooting sections should just link to the other, rather than be duplicated.
Also, the same comments I had on the other apply here is well.
| | `disable_captive_portal_redirect` | boolean | Optional | By default, ALL DNS lookups using the provisioning hotspot will redirect to the device. This causes most phones/mobile devices to automatically redirect the user to the captive portal as a "sign in" screen. When disabled, only domains ending in .setup (ex: viam.setup) will be redirected. This generally avoids displaying the portal to users and is mainly used in conjunction with a mobile provisioning application workflow. Default: `false`. | | ||
| | `fragment_id` | string | Optional | The `fragment_id` of the fragment to configure machines with. Required when using the Viam mobile app for provisioning. The Viam mobile app uses the fragment to configure the machine. | | ||
| | `disable_wifi_provisioning` | boolean | Optional | When set to true, disables WiFi hotspot provisioning. The machine will not create a WiFi hotspot for provisioning. Both WiFi hotspot and Bluetooth provisioning can be enabled simultaneously. Default: `false`. | | ||
| | `bluetooth_trust_all` | boolean | Optional | When true, the machine accepts all Bluetooth pairing requests for sharing the internet from a mobile device (tethering) without requiring devices to be added during provisioning first. Default: `false`. | |
There was a problem hiding this comment.
| | `bluetooth_trust_all` | boolean | Optional | When true, the machine accepts all Bluetooth pairing requests for sharing the internet from a mobile device (tethering) without requiring devices to be added during provisioning first. Default: `false`. | | |
| | `bluetooth_trust_all` | boolean | Optional | Set to true to accept all Bluetooth pairing requests (which is only needed for bluetooth tethering) without requiring an unlock command from a mobile app. Default: `false`. | |
Suggestion is the same as comment in the json template earlier in this file.
| | `fragment_id` | string | Optional | The `fragment_id` of the fragment to configure machines with. Required when using the Viam mobile app for provisioning. The Viam mobile app uses the fragment to configure the machine. | | ||
| | `disable_wifi_provisioning` | boolean | Optional | When set to true, disables WiFi hotspot provisioning. The machine will not create a WiFi hotspot for provisioning. Both WiFi hotspot and Bluetooth provisioning can be enabled simultaneously. Default: `false`. | | ||
| | `bluetooth_trust_all` | boolean | Optional | When true, the machine accepts all Bluetooth pairing requests for sharing the internet from a mobile device (tethering) without requiring devices to be added during provisioning first. Default: `false`. | | ||
| | `fragment_id` | string | Optional | The `fragment_id` of the fragment to configure machines with. Required when using Bluetooth or the Viam mobile app for provisioning. The Viam mobile app uses the fragment to configure the machine. | |
There was a problem hiding this comment.
Should check with the mobile team on this. AFAIK, this CAN be used by a mobile app, but current implementations aren't using it.
It is definitely in no way bluetooth specific though, so not sure why or where that idea came from.
| | `fragment_id` | string | Optional | The `fragment_id` of the fragment to configure machines with. Required when using Bluetooth or the Viam mobile app for provisioning. The Viam mobile app uses the fragment to configure the machine. | | |
| | `fragment_id` | string | Optional | The `fragment_id` of the fragment to configure machines with. Can be used by a mobile app (during provisioning) to automatically configure a newly created machine. | |
See:
Note: these do not go in detail through the flutter provisioning widget. I think currently providing that is enough but if you think differently let me know.