Web page design

[dkerr64]

As we get close to feature complete, I think we could do a much nicer job for the web page. But rather than dive in and try code something I thought best to document requirements / design ideas and ask for comment. Then maybe we can divide tasks among ourselves. Here are my initial thoughts...

Design:

• As lightweight as possible (no loading of 3rd party UI helpers, all self-contained)
• Looks just as good on phone/tablet/desktop portrait and landscape
• Both http and https (self signed cert only?)
• Password protected with default "admin" that user can change
• Password protect and/or require confirmation for potentially destructive actions

Content:

• Basic system information (IP address, firmware version, free memory, etc)
• QR code (which should display/hide without different page formatting)
• Garage door/light/obstruction status
• Copyright/Trademark/Contributor attribution

Available actions:

• Upload new firmware
• Reboot
• Unpair/re-pair
• Manually set IP/netmask/gateway/DNS
• Update/change SSID/password (maybe too risky?)
• Update/change web page password
• View logs / set syslog server address?
• Control the door (open/close/etc) -- going too far maybe?

API

• Should we provide a basic http/https API that returns say a JSON with door/light/obstruction status?
• Protect potentially destructive URLs with basic authentication (right now nothing stops you from going to http://<ipAddr>/reset)

Thoughts? Reactions?

[edrikk]

This is a very great list. I love that mobile is right there at the top because realistically, after initial setup most activities should/would happen via a mobile device; Including OTA updates when that roles out.

My only 2 suggestions:

1. Avoid clutter. Lots of whitespace is better than lots of crammed text. I believe a really good UI to emulate is AdvancedTomato (Tomato router OS theme). Responsive design, sufficient spacing between data elements/not cramped, nice background colors to add to visual cues, pleasant card like boxes to group related items on a page together, etc.
2. Start with an MVP and polish it before adding functions :)

If it helps in any way at all, the source is on github, with the UI layer being here.

[thenewwazoo]

My strong preference is to adhere to two basic principles:

• avoid any configurable, unless it is impossible to avoid it
• all actions should be obviously useful to an unsophisticated user

I'm fine with attractive UIs, but if a user wants to be the knob-twiddling type, there's the ESPHome firmware. If they want to get even lower level and consume APIs and the like, there's the MQTT firmware.

[dkerr64]

I'm fine with attractive UIs, but if a user wants to be the knob-twiddling type, there's the ESPHome firmware. If they want to get even lower level and consume APIs and the like, there's the MQTT firmware.

I only mentioned API because like it or not, we have one right now... for example http://<ipAddr>/reset, and its dangerous to have even that without any protections. I totally support having no API.

[dkerr64]

• avoid any configurable, unless it is impossible to avoid it

I would restate this... avoid the need to connect USB for any configuration after initial setup, unless it is impossible to avoid it. Therefore some basic capability must be offered over IP.

[dkerr64]

Having looked at this there are a number of challenges...

• HTTPS... I have come across multiple comments in my research that suggests that the ESP8266 is not powerful enough to handle encryption. Generating self-signed certificate is slow, and encrypting/decrypting adds latency to every request. We may want to abandon this.
• The current ESP8266WebServer package is lightweight, but supports only a single connection. This may be okay for our use case but I feel it is not ideal. There is a async version of this which would be better... I tried it and it works, but it adds significantly to the size of the firmware which we maybe can't afford.
• Filesystem... right now our html is embedded into the C++ source/firmware. Ideally it should be in separate html/css/etc files in the filesystem. But this introduces a whole new set of problems(1). There is a technique used in this example where we could keep these files separate "in the filesystem" for dev/test purposes, but actually embed them into the source/firmware as well/instead.

Thoughts?

Footnotes: (1) Looks like firmware and filesystem are separate uploads from either serial or OTA. This complicates updates which would become a two-step process. In addition, when you upload a filesystem, I assume it overwrites anything already in the filesystem. That would be bad as we already store the rolling code there, and may want to store other data too (web page password?).

[dkerr64]

I have made a start on this. Please see #63 and review/comment.

[dkerr64]

With #63 merged, we could close this issue and open a new one to track desired updates. Recapping the original goals...

Design:

• As lightweight as possible (no loading of 3rd party UI helpers, all self-contained) accomplished
• Looks just as good on phone/tablet/desktop portrait and landscape done.
• Both http and https (self signed cert only?) probably won't get done
• Password protected with default "admin" that user can change not yet implemented
• Password protect and/or require confirmation for potentially destructive actions pop-up confirmation done

Content:

• Basic system information (IP address, firmware version, free memory, etc) done (but not free memory)
• QR code (which should display/hide without different page formatting) done
• Garage door/light/obstruction status done
• Copyright/Trademark/Contributor attribution done

Available actions:

• Upload new firmware done (but we could do better GUI)
• Reboot done
• Unpair/re-pair done
• Manually set IP/netmask/gateway/DNS not yet implemented
• Update/change SSID/password (maybe too risky?) not yet implemented
• Update/change web page password not yet implemented
• View logs / set syslog server address? not yet implemented
• Control the door (open/close/etc) -- going too far maybe? not yet implemented

API

• Should we provide a basic http/https API that returns say a JSON with door/light/obstruction status? done
• Protect potentially destructive URLs with basic authentication (right now nothing stops you from going to http://<ipAddr>/reset) not yet implemented

Thoughts? Reactions?

[edrikk]

Great job! Wish to use this once v1 security is implemented.

Only feedback is on this: “ Manually set IP/netmask/gateway/DNS not yet implemented Update/change SSID/password (maybe too risky?) not yet implemented “

I would suggest anything that would allow a device to go into a state that would require a reset is needed.

Imagine a use cases where the person changes SSID and has to jump through hoops (or reset?) for this device to get back to functioning state.

Or the user WANTS to change SSIDs and can’t…. Because the project has stopped being supported or whatever and they can’t reload firmware.

For a local device, the user should always be able to get to/recover/update it locally…

[jgstroud]

@dkerr64 looking back at this, I maybe merged it a little prematurely. The ratgdo_logo.png consumes a large amount of RAM. We should be mindful of this. I think this is an icon to be used if the user puts this on their IOS Home Screen? Can this logo just be pulled from the internet?

[dkerr64]

@jgstroud if space becomes an issue I think we just remove it completely... we could use the same image as favicon (which is only 3KB). In fact, thinking about it, I don't know why I didn't just do that in the first place.

[lttlrck]

this is really nice. I spotted a typo: exiting -> existing

If you wish to pair to another HomeKit home, you must first un-pair from exiting home.

[dkerr64]

@jgstroud if space becomes an issue I think we just remove it completely... we could use the same image as favicon (which is only 3KB). In fact, thinking about it, I don't know why I didn't just do that in the first place.

It won't be as straight forward as using the same icon... The favorites icon has transparent background. That results in black image on black background, and therefore invisible. So I am looking into what (if anything) I can do about that.

But, I did want to point out that none of the web content, including the icons, use up any RAM space. As constants declared with PROGMEM keyword, the data remains in flash and never read into RAM.

[dkerr64]

this is really nice. I spotted a typo: exiting -> existing

If you wish to pair to another HomeKit home, you must first un-pair from exiting home.

Thanks, I have fixed that in my local copy, so it will get fixed whenever we're ready to push updates to the webpage.

[jgstroud]

@dkerr64 I'm new to this platformio environment and toolchain. I had expected those files to go in flash and be read directly from flash as well, but the tools report an increase in ram utilization. Removing the icon drops the ram utilization by the size of the file.

[dkerr64]

@dkerr64 I'm new to this platformio environment and toolchain. I had expected those files to go in flash and be read directly from flash as well, but the tools report an increase in ram utilization. Removing the icon drops the ram utilization by the size of the file.

I wonder if we need to #include <pgmspace.h> per this discussion. In the meantime I have significantly reduced the PNG sizes thanks to ImageOptim.

I think we should close this issue. And I will open a new one to track "part 2" web page fixes/enhancements. I have created a new branch for this.

[dkerr64]

Closing this out as PR merged. Tracking "part 2" in issue #87

Thank you to everyone that assisted.