A bigger picture

A bigger picture for device documentation

Over the last years I've been talking every now and then with @tmomas and other OpenWrt members about "user experiences" when handling firmware. After I suggested some radical changes in device documentation and firmware selection he asked me for a bigger picture. Here we go

This document tries to offer a status report on the user facing resources when
interacting with OpenWrt. It should be seen as a work in progress and suggestion
for extension and clarification are very welcome! Parts may be written in a mean sounding way, this is with no intention and will be changed once I'm aware of it. I highly value the work of the Wiki team!

Motivation is to improve things as both new and long-time users complained about
parts of the current implementation. The ideal outcome of a reworked
documentation and user experience would be:

Non tech-savvy router users feel confident in flashing OpenWrt on their devices,
resulting in a more secure Internet.

It then tries to determine requirements needed for this goal eventually propose
solutions, resulting in concrete To-dos.

Status

The following tries to summarize important user facing resources.

Downloading an image

Finding the router specific firmware is difficult for new and inconvenient for long-term users. The Downloads page first link clicked by a user forwards to the releases overview, which is confusing to say the least. If the user figures out that 19.07.3 is the latest release, which is not stated on the previous Downloads page, they end up at a the target overview. Again, confusing for someone new.

At this point whoever likely uses a search engine to end up at a device specific page.

As a random example, searching for a Archer C7 brings one to this page, which stores the link in one of multiple tables, combines with other similar devices. Overall are the information on the website likely overwhelming for non developers. The specific SoC or WLAN Hardware or CPU MHz are unlikely of direct interest for a common user.

As the page contains information for multiple devices at one, it is not trivial to parse which information is important for which device. Important information are likely missed due to the amount of information.

When choosing a random other device page, the article structure is likely different, either in amount of devices covered in the page or amount of in-depth information.

Keeping software up to date

OpenWrt tries to, but does not yet fully follow a 6 month upgrade cycle. This means, unlike for other distributions like Ubuntu, there is unlikely a feel for there must be a upgrade soon. Due to the lack of a announcement mailing list, regular users may miss new (service) releases and keep running outdated (and probably vulnerable) software on an Internet facing device.

The upgrade process itself involves again the identification of the correct image. Which means a X-Mas flashed router isn't trivially updated by its later users.

Software overview

OpenWrt offers a package overview both within the Wiki as well via CSV files. It show the package version within the latest release, no snapshot versions are covered.

Hardware suggestions

The table of hardware suggest to avoid devices with only 4MB of storage and 32MB of RAM. Consumer relevant information like dual-band, USB ports or WiFi standard (ac, ax, etc) are not easily visible. Looking at the per device overview gives a lot of information which is partly relevant for developers only, empty or wrong.

While there is a list of recommended device no complex search masks are available. The table size requires a lot vertical scrolling.

Device specifications

As mentioned before a per device view exists while a more complete overview exists at wikidevi.com or it's mirror/clone wikidevi.wi-cat.ru/Main_Page. These information are valuable but not embed-able in our views due to a lack of API. If all wikidevi clones die, all these information are lost.

Requirements

This sections tries to write requirements for a better user experience.

Data availability in machine readable formats

All stored data should be available in machine readable formats to allow downstream projects to develop their own tooling. This includes device information, package information as well as image/artifact information.

The data should be available in JSON and CSV if applicable.

Community edit and reviewable

All data shouldn't be maintained by a small group of people with privileged access, but everyone in the community. To allow a transparent process changes should be reviewable like Git Pull Requests on GitHub/GitLab.

Solution proposals

Here is a list of possible solutions, none of them is complete. Also the combination of the solution is point of discussion.

Firmware wizard


@mwarning is currently building a firmware wizards with a clean interface to easily find firmware images. Additional information could be shown, either hardware specs or installation steps.

OpenWrt JSON

The openwrt-json repository downloads available packages and stores them in JSON format, allowing tools like the firmware wizard to load package lists. The files manifest.json contains all information as provided by the current OpenWrt package overview. These JSON information could therefore also be rendered to a static website.

OpenWrt devices

The openwrt-devices repository converted the OpenWrt table of hardware to YAML files. These files are both human and machine readble and could be rendered to a Wiki like device overview. By using templates we can be DRY (don't repeat yourself), meaning we don't write 50 times the same 5 steps for installing TP-Link devices, but put it into a template. The page could look like the following screenshot, which is a recycling of the LineageOS website. We would obviously use something else, but it should give the idea.

Automatic upgrade selection

A proof of concept script automatically downloads multiple JSON files containing information to existing upgrades and images. This would allow a LuCI integrate where the user installs an upgrade via a single click.

To-do

Please share your thoughts. I'll update this post with a changelog.

13 Likes

Since we are proposing new feature something to get official announcement based on the firmware (affected vulnerability, new update, improvement of the device in the new version) would be very useful since the router would be connected to internet anyway.

1 Like

@aparcar, @mwarning -- Loving the download wizard, it does look very much LineageOS-like! I'd make a suggestion to display "What's a snapshot" explanation if the Snapshot is selected from the left drop-down.

I also support @Ansuel's suggestion, I understand some people would prefer to turn off the "phone home for update" feature, but would be nice to have new release notification integrated into SSH banner and WebUI. Maybe make it a separate package because it would most likely require SSL support. I don't know enough about the backend, but the client side would probably be trivial.

1 Like

We all so need a news ticker on the OpenWrt home page to highlight packages or mager changes to OpenWrt like the jump from ar71xx to ath79. Or in bed the OpenWrt twitter feed.

1 Like

There is a new announcement list here which contains updates. It will be promoted during the next release cycle.

1 Like

Do I read this correctly, that this solution is meant to replace the complete toh and packages namespaces in the wiki?

The current packages/toh view could be a) replaced as it seems fully auto generated or b) extended to an machine readable format.

That does not include the wiki. I'm in favor of using more templates and have single pages per device instead of merging them, but that's another thing to discuss.

There are 2 different places to report issues:

I know that the former is for OpenWrt core and the latter is for LuCI+Packages.
But, this is still confusing.
Perhaps we should use a single place like GitHub for both?

A similar problem with Git repositories:

Some of the repositories are mirrored to GitHub, and some not.
Some use GitHub as a primary location, others don't.
This doesn't look intuitive at all.

3 Likes

I'm afraid, I can not follow...

  • packages namespace: script generated
    • replace?
    • keep as is?
    • extend to machine readable format?
  • toh namespace (devicepages + dataentries): nothing script generated
    • replace?
    • keep as is?
    • extend to machine readable format?

Keeping both (on top of your new system) would mean double work, because two systems need to be filled with data.

And seeing vgaeteras posting I think it would make sense to clarify the in-scope/out-scope of this change in the first posting.

Hi @vgaetera, yes it's confusing and we try to find a better way for that. Some time ago a vote decided to move on to a self hosted gitlab. We're working since (slowly) on ways to migrate. There are also concerns parts of the community would be cut of by removing the GitHub repositories, so very much work in progress. A compromise of usability (as in GitHub) and in independence (as in self hosted) is not trivial.

1 Like

Hi @tmomas, I'm mixing up the words which is confusing, I'll try to clear it up:

packages overview: I see the following additional requirements:

  • machine readable via a JSON API
  • support multiple releases (incl. snapshots)

If that's possible with the current Wiki, great! If not, we could consider creating something similar to Alpines Package overview. Before doing any additional steps I'd like to hear @bobafetthotmail opinion on that.

toh: I understand the toh as both the table of hardware as well as the techdata per device. That could be beautified and rendered based on community maintained YAML files. Combined with information which whatever wikidevi mirror is up by that time.

device pages: The trickiest part. My suggestion would be to create a pretty table of hardware + techdata pages (see above) and remove such information from the current wiki. Only keep information on installation, PCB pictures, special tips and tricks, boot logs, etc. just everything which is not reasonable put into a YAML files.

1 Like

The indexing and machine-generated pages for each package are all done by a shell script running in the wiki server that was originally designed to index multiple releases, so it can index snapshot too.

But I see you have your own python script, and I'm assuming it is much better than my shell script is, so it's probably better to migrate the system to use yours instead, although it's probably not a priority right now.

The harder part has always been actually showing the information with a decent table interface, so far we are using Dokuwiki's data table plugin, but it's really less than optimal, and lags every time you open a package table page, and its interface is weird with bars only on the bottom while it cuts stuff on the side, and so on. It's the same thing as the ToH really.

If you have a decent frontend page for that, like the Alpine page you linked, I'm ok with migrating to it.

Smells like you have already a usefull application in mind?

Yes please! It's ffffreaking fast, which the current solution in the wiki isn't. Not at all.

New task: Create new packages table

Create new packages table

  1. Create frontend for the packages JSON data
  2. Integrate new packages table into the wiki

Who can take care of #1?

Take a look how LineageOS implements per device documentation in git using static files:

1 Like

Finally I found some more time to go into the details.

I'm sometimes having difficulties in understanding your argumentation.

Regarding this case, the solution is just one section below:

Click the link to Table of Hardware, enter your Model and that's it. Perhaps filter further for specific version.
Not that difficult.

Maybe we should pull the second section ahead, in order not to confuse users with the overwhelming downloads.openwrt.org?

Alternative way:

Easy enough, isn't it?

Alternative way: Use the wiki search to find a devicepage (I just picked a random one that came to my mind)
grafik

Easy enough, isn't it?

You see why I'm having difficulties with your argumentation?

As we have seen above, identification of the OpenWrt image to flash is not that hard.
But if you want to say "Wouldn't it be much nicer and easier, if I could just click a button in LuCI Upgrade to new OpenWrt release now?", then I'm fully with you.

Good point and a very good example of how it should not be.
Slight improvement: Separate page for the Archer C7, without the other devices. And still, a single page for a single device would be the clearest possible solution, no doubt.

Solution: Use the right tool for the job.

  • Use https://openwrt.org/toh/views/toh_fwdownload if you know already for which device you are searching firmware images for. Why would you need the USB ports and Wifi standards and whatnot if all you want to do is search for a firmware image?
  • Use other views https://openwrt.org/toh/views/start if you are searching for information which device to buy. Why waste precious space with download links when you don't even know which device to buy?

Assuming that you mean scrolling in horizontal direction (left-right), not vertical:
Since the table size is dependant on the amount of data, any table that has lots of columns will have that problem, and require more or less scrolling in horizontal direction, IMHO.

Regarding complex search masks: I agree, and I'd like to have filter capabilities like geizhals.de, backed by a database that is built for exactly this purpose (unlike the current data-plugin solution, which is of general purppose nature, and hence not performing well with big amounts of data)

As I understand, current YAML information has been extracted from the ToH.
Where does the future YAML information come from? How exactly are those YAML files generated? Manually via text editor?

(Remark: The above describes in principle also the current situation in the wiki.)

What does that mean in terms of

  1. initial entering of information into YAML files
  2. continuous updates of any kind to YAML files?

What is your expectation regarding the work to be done by the community? And who is the community?

reviewable by who? Wouldn't the reviewers be "a small group of people with privileged access"? Isn't that a contradiction to what you said above?
Who are the reviewers? Do we have the people on board to do the job and do those people have enough time? Just asking, because often users hear that there is not enough manpower available to do $this and $that. Adding more workload in this situation might be counterproductive.

Already in the current wiki we do not need to write the same instructions multiple times.
Examples:
https://openwrt.org/toh/mikrotik/common
https://openwrt.org/toh/gl.inet/installation

All it needs is a link to these instructions placed on the devicepage.
If it is deemed already too complicated for a user to click a link, there is also the possibility to include complete pages or sections thereof in other pages. The Linksys WRT AC pages (and others) make use of this. Write once, use many times.

1 Like

Yes, it is clearly easy if you know the positions of the links and the overall flow. I think my main problem with the OpenWrt wiki is that it's very noisy. A lot of information are provided, a lot of links to click, a lot of sub pages.

My intention here is that someone using OpenWrt for the first time isn't stopped by crawling through a complex website. It's complex because it's complex, sure, but to get a stock device to OpenWrt it usually just requires the following steps:

  • Find you device in a list
  • Download the factory image
  • Upload it to your running router and wait 2 minutes
  • Connect to it
    • via WLAN do this
    • via Ethernet to that
  • Change Wifi Key
  • Enjoy

Sure that doesn't cut it for many many people with complex setups, but literally all my none OpenWrt related acquaintances /friends are happy with that setup.

So I want to create/design/build a flow that brings you through the list in a pleasant way.

I think Freifunk is a good example for people having a similar motivation and therefore simplify the tooling to get routers flashed.

So let's make it a policy to have one page per device?

To do that we need data easily accessible in a machine readable format to put it into a database. YAML maybe :slight_smile:?

Ideally the people maintaining the current data migrate to the YAML system. It could become a policy, as discussed in Hamburg, that developers adding a new device to openwrt.git also add a YAML file to devices.git containing meta data.

I'm in contact with the maintaner of the current wikidevi instance (clone), I'll ask if we can do some parsing to automatically create YAML files for devices.git.

We can also design a schema with a simple web interface to create such YAML files. I'm all up to learn about existing standards :grin:

It's a long shot but the Lineage team has per device maintaines. Ideally we'd had a community of router users which test new features on their devices and can give their approval. Candidates are people within this forum providing custom firmwares or developers/companies interested in keeping their devices up to date. Say I like my Linksys wrt3200acm, so I'd test each RC and set in some machine readable file that I approve the device as tested (or broken).

So, the same people doing the testing could also have an eye on the device descriptions.

I'm working on that in parallel :slight_smile:

Regarding the designed installation flow. Say I want to run Lineage OS on my Android phone. Go to lineage.org

Find a very prominent Download button.

Next I see all supported devices on the left, say I got a Fairphone 2

One arrives at a overview which contains the firmware images. Now Lineage got a somewhat questionable just update your device every week approach, but we wouldn't have to apply that to OpenWrt of course.

To understand what to do with the firmware image, the prominent Installation instructions show what to do.

This manual looks the same for every device, only varying in key combinations and partly special notes. The manual is extremely short and helps even a new user to quickly get things up and running.

The "Device info" page looks again the same for each device, so it's easy to compare multiple devices. It also links to in-depth guides which are however beyond scope of many regular users.

So, I want that but with routers.

3 Likes

While on Dokuwiki it won't look nearly as good as that website, it is relatively easy to do.

it requires A LOT of man hours if made by hand since OpenWrt supports (or supported) A LOT of devices.

This kind of pages lend themselves a lot to be auto-generated by a script that looks at the ToH's database to extract the relevant information.

This is technically possible on OpenWrt wiki too, I did create some "summary" or "cheatsheet" pages that are just fetching most of their content from other pages using the wiki's functionality (or a plugin, don't remember). https://openwrt.org/docs/guide-user/network/ucicheatsheet

The main reason we decided against strong automation like that and went with templates instead is that we wanted to rely on contributors to add most of the information and/or keep it updated.

But I don't know how much that worked out or how much is still required, given that now we have installation instruction and most device data in the commit that added the device.

I think it should be OK to mostly automated if we leave some places where people can just edit the page to add notes between the automatically generated blocks

That's fine and all, but it's a lot of work and I would really like to get something better for the ToH or package tables

Devices

So I got a scraper which works for the OpenWrt wiki, it could also work for wikidevi. Within some 10 minutes we have 1500 yaml files containing the current state of knowledge. Next thing we design something pretty, or ask our friend at lineageos if we can recycle parts of their device info templates. Within a week we have a page running containing 1500 devices. These yaml files should contain a wiki link to the single page device wiki pages, containing much more in depth information. At this point we could remove the device hardware highlight tables and download links from the wiki entries.

Regarding maintenance, for new devices we can make it a requirement so developers have to provide that. The Kernel requires YAML specifications of device-tree files, I think we can do something similar. For existing devices, either the existing data maintainer learn YAML and slightly change their workflow (meaning to use Git) or the scraper scripts runs every X hours.

Fresh information on built firmware is provided via generated JSON files directly from the buildbots. (@jow ping), so we can have a firmware wizard or lineage like download overview, pointing to wiki pages and hardware overview.

At the same time, all yaml information is read into a database, allowing a search mask based on features. That's possibly doable via a some Flask + Peewee scripting.

Packages

What exactly do we want? Something like Alpines solution seems very doable. Do we need any special bells and whistles?

I wasn't clear in my question before. I'm not a web developer, doing anything beyond basic static HTML with css styling is beyond me, and afaik this applies also for tmomas.

The main thing that I'm asking is, do we have someone or something that can generate these pages (not just the data backend), and also the actual page with the tables or not?
It seems the repos you linked do have a website structure, is that an actual website+ backend ready to be hosted?

Because just hosting these new pages and the indexing backend scripts/databases on the same wiki server is doable and probably much lighter than the current system for both packages and hardware table (that are using mysql as a key-value storage and run like complete garbage as a result).
I'm not the owner so you probably need to ask jow or other team members for permission too.

While also possible, I'm really NOT a fan of using the wiki's own "embed HTML/PHP" feature to serve the webpages from inside the wiki itself, which is disabled afaik, as that is going to open doors to exploits and haxxoring. So I'd like to veto that if possible.

Packages
What exactly do we want? Something like Alpines solution seems very doable. Do we need any special bells and whistles?

Afaik no, that's as good as it gets for the package table.

I would like to get an equivalent to the "package indexes" https://openwrt.org/packages/index/start too, which was inspired from Debian's package lists and can give a different look into things. https://packages.debian.org/stable/

But it really isn't a requirement, as long as the package table does not suck it's good for me.