First time setup over bluetooth/wifi (or similar)

[lightsofapollo]

As a user I want to set up the gateway using WiFi or Bluetooth so I don't have to plug it into an Ethernet port to get it working.

[hobinjk]

Potentially useful documentation: https://www.raspberrypi.org/documentation/configuration/wireless/access-point.md

[dhylands]

Also: https://github.com/atilag/ProximityBLEClient and https://github.com/atilag/ProximityBLEService

It requires a native app, but otherwise works quite well.

[andrenatal]

For Vaani we used this approach and worked well: https://github.com/mozilla/vaani.setup

[benfrancis]

Personally my preference would be to start with the WiFi access point method because as Dave mentioned Bluetooth may require a completely new native app, whereas any smartphone/tablet/desktop computer can already connect to a WiFi access point and load a web page to carry out setup.

[kgiori]

A poor UX would be to ask the user to connect to a specific SSID and then type an IP address into their browser, such as http://192.168.0.1 or localhost. We should create a more intuitive approach. For Wi-Fi, the RPi can be setup to act like a public hotspot. That means redirecting any port 80 or port 443 traffic to a page hosted by the RPi. It is known in wi-fi hotspot lingo as a "captive portal" page. For example:
https://raspberrypi.stackexchange.com/questions/41369/wifi-hotspot-with-redirect-to-html
Other open source "project names" I recall from the past were "NoCatAuth" or "NoCatSplash", but I don't know if they are up to date.
If we want serious help for this feature, I can ask for sample source code from a previous employer of mine, or we can do a more detailed search for related open source projects that have a nice UX around them. The best (basic) implementations roughly go like this:

• connect to the unconfigured/new RPi/gateway as an AP (which will redirect your browser to a captive portal page)
• walk you through setup and config pages that let you point it to some other Wi-Fi router that you want it to connect to as a client
• the RPi/gateway tests acting like a client, using the connection credentials you entered
• if it works, it will respond to your device that it was a success and drop your client connection as it converts to being a client of the local wireless LAN
• if it fails, it takes you back to the setup page so you can try again.

More elegant solutions are possible if the user installs a custom app or we do some sort of out-of-band key exchange method.

[andrenatal]

Hi Kathy. This is exactly the UX we have on vaani.setup that I'll be integrating in the gateway.

[benfrancis]

@andrenatal was there a UX spec for that? It might help in creating the UX spec for this feature for the gateway.

[andrenatal]

AFAIR, it doesn't.

[andrenatal]

Fixed by: 4b653a2

[benfrancis]

@andrenatal Where is the implementation of the user interface in the UX specification? (slides 3-8 https://docs.google.com/presentation/d/1rMeg6hep8JQflqwbiNIbhSoK9StCeVZ2npphmQHKda4/edit#slide=id.g221d7d7c9f_0_0).

Who reviewed this code?

The only code review I can see is #439 which provides a script to download a separate un-reviewed software repo and insert it into the gateway's build. #440 has no code review.

It seems like you've just forked the vaani repository into the mozilla-iot GitHub org and hacked it to run on the gateway, without any effort to implement the UI in the specification or even bothering to rename it.

This clearly doesn't meet the requirements. I can only suggest backing out these changes, implementing it as per the specification and getting a proper code review for this code.

[andrenatal]

I reverted #440 and asked dave to review it #442 (review)

Regarding UX for the wifi setup, I wanted to first implement the changes to make the captive portal work along the wifi setup and the integration into the gateway building system, to then modify the UI to meet the specification you mentioned and also change the docs and Vaani naming (#439 (comment)), things that I'm doing now.

Regarding using Vaani's wifi setup method, I mentioned that I'd be using it on last two meetings and nobody objected.

[benfrancis]

Thanks @andrenatal.

Regarding using Vaani's wifi setup method, I mentioned that I'd be using it on last two meetings and nobody objected.

I see no problem re-using code, that's great, let's just make sure we integrate it cleanly, make sure it follows the UX spec, is properly reviewed and remove all the redundant and obsolete code (and audio files!) so that it isn't just an old project tacked on the side of the gateway. We don't want to be shipping legacy code and increasing the gateway image size unnecessarily.

I'd suggest this should really be part of the gateway repo and feel like part of that codebase rather than something completely separate.

[andrenatal]

I cleaned it and removed the references to vaani and the obsolete files. I also implemented the UX mockups (except for an icon that I don't have as mentioned here and here ).

Regarding reviewing, could you please do it @dhylands (https://github.com/mozilla-iot/gateway-wifi-setup)?

Regarding being part of the gateway repo or not, we decided not do it when we shipped Vaani to improve modularity since this method is linux and wifi only, and we also could use other setup methods (like bluetooth, sound and etc..), but if you want to merge that here is fine for me.

[benfrancis]

@andrenatal Saw your note on the UX spec about the missing icons, sorry about that. I've uploaded exported SVG files to the icons folder on Google Drive.

• WiFi (note this is different to the old "adapter" icon
• Secure WiFi

[benfrancis]

I cleaned it and removed the references to vaani and the obsolete files. I also implemented the UX mockups

Thank you for doing that. A quick grep reveals some mentions of vaani still remaining:

• /platforms/default.js
• /templates/oauthSetup.hbs
• /templates/status.hbs
• /README.md
• /package.json
• /platform.js

I notice that the gateway-wifi-setup repo is using Handlebars, but the gateway repo is using Moustache as a template engine (decision documented on the wiki by Mike). It would be good if we could remove this redundancy and pick a single templating engine, but I don't mind if you want to file a follow-up for that.

Regarding being part of the gateway repo or not, we decided not do it when we shipped Vaani to improve modularity since this method is linux and wifi only, and we also could use other setup methods (like bluetooth, sound and etc..), but if you want to merge that here is fine for me.

I'm OK with keeping WiFi setup as a separate repo if you and Dave agree that's the best approach. It certainly seems to make sense for the back end parts given how platform specific they are. However, given this is the first UI people will see when they use the gateway it's important that we get the UI right, how can I test this? Do I need to build my own OS image? I see that you've added some messages into the UI which is a good idea but I'd like to see how it looks in action. The setup process is also getting quite complex, passing between three separate NodeJS web servers so we need to make sure it's tested thoroughly, especially as there are currently no automated tests for this part.

There still seems to be some redundant code like the un-used audio code in EdisonYocto.js and default.js and some of the template files like status.hbs and oauthSetup.hbs. connecting.hbs seems to point to a missing stylesheet style.css ? .gitignore mentions lots of files which have presumably been removed.

The fonts used in the UI should be Zilla Slab and Open Sans. Otherwise the font change will be quite obvious when moving through First Time Setup.

Thanks for sticking at this and cleaning it up. I'll let Dave review all the WiFi stuff!

[benfrancis]

I just tried the image Dave created and this is looking very cool!

Some issues I've noticed:

• If I type the wrong password it doesn't display an error message as shown in the mockups, it tries to connect, fails, and then I'm locked out of the gateway because the AP disappears. Is there any way to detect a failed connection and report it back to the UI or is that a limitation of the WiFi chip on the Raspberry Pi? We need to figure out a way to recover from entering the wrong password
• Is there a technical reason that the captive portal can't use the gateway.local domain instead of an IP address? I notice that the WiFi setup is still available via the gateway.local domain over Ethernet. Having two separate web addresses for first time setup complicates things in the setup instructions. (I guess the IP address approach is more reliable cross-platform though...)
• Small nit: the /wifiSetup path of the setup URL is in camelCase which we're not using anywhere else. /wifi-setup might be better for consistency.

Some comments on the visual design implementation (these may seem like small details, but this is literally the first UI users will see so it's important for the setup process to feel smooth):

• The font of the "Welcome" heading should be Zilla Slab and all other text Open Sans, to match the rest of first time setup
• The list items showing WiFi network names should be less spaced out (gaps of about 10px) to match other lists in the UI
• WiFi network names and input fields like the WiFi password field should be left aligned as per the mockup
• Border radius of menu items and buttons should be 0.5rem (5px). (Note the rest of the gateway UI uses 10px as a base font size on body and rem for sizes everywhere else to make it possible to scale for different pixel densities).
• The password entry UI should be vertically center aligned as per other similar UI, not just part way down the page.
• The Mozilla IoT wordmark should ideally be removed from the enter password screen because it can overlap the input field when a keyboard comes up on mobile
• The background-color of input fields should not match the background-color of buttons because that's confusing, it should be #c7d0d6 as per the mockup with #666666 for the placeholder text
• The :hover and :active style on input fields etc. with a CSS transition is cute but it's inconsistent with the rest of the first time setup so I suggest removing it
• The default tick box is very small to use on mobile, it would be better if the "Show password" tick box matched the ones in Settings, as per the mockups. Note this is implemented with a sprite (a bit of hack but necessary for touch interfaces)
• I like the addition of the message which tells the user to re-connect to their own WiFi network. Can we make that 1.6rem (16px), Open Sans, and horizontally and vertically center aligned to match other similar messages in the UI? I've added a mockup (slide 7) to show this, with a new message (note that we can't assume that setup is taking place via the built-in access point):

Connecting...

The gateway is now connecting to your WiFi network.

Please ensure you are connected to that network and navigate to gateway.local in your web browser to continue setup.

Thanks for being patient in getting these details right.