Open!Next D2.5 process faciliation dashboard frontend demo

Example demonstrator frontend for an open source development status dashboard

This repository contains code for an online frontend that visualises various metrics about open source hardware (OSH) projects hosted on GitHub. The underlying data used here is retrieved with the backend REST application programming interface (API) implemented in the Open!Next D2.5 backend repository.

This software is not for general consumers to just "double click" on and install on their devices.

Background

Today’s industrial product creation is expensive, risky and unsustainable. At the same time, the process is highly inaccessible to consumers who have very little input in the design and distribution of the finished product. Presently, SMEs and maker communities across Europe are coming together to fundamentally change the way we create, produce, and distribute products.

OPENNEXT is a collaboration between 19 industry and academic partners across Europe. Funded by the European Union's Horizon 2020 programme, this project seeks to enable small and medium enterprises (SMEs) to work with consumers, makers, and other communities in rethinking how products are designed and produced. Open source hardware is a key enabler of this goal where the design of a physical product is released with the freedoms for anyone to study, modify, share, and redistribute copies. These essential freedoms are based on those of open source software, which is itself derived from free software where the word free refers to freedom, not free-of-charge. When put in practice, these freedoms could potentially not only reduce proprietary vendor lock-in, planned obsolescence, or waste but also stimulate novel – even disruptive – business models. The SME partners in OPENNEXT are experimenting with producing open source hardware and even opening up the development process to wider community participation. They produce diverse products ranging from desks, cargo bike modules, to a digital scientific instrument platform (and more).

Work package 2 (WP2) of OPENNEXT is gathering theoretical and practical insights on best practices for company-community collaboration when developing open source hardware. This includes running Delphi studies to develop a maturity model to describe the collaboration and developing a precise definition for what the "source" is in open source hardware. In particular, task 2.2 in this work package is developing a demonstration project status dashboard with "health" indicators showing the evolution of a project within the maturity model; design activities; or progress towards success based on project goals. Details of the dashboard's technical architecture are described in the deliverable 2.5 (D2.5) report.

This repository contains the example frontend code for D2.5 and to be clear, this deliverable is: Designed to be deployed on a web server server. This deliverable is not: For general end-users to install on consumer devices and "double click" to open.

The visualisations for this demo frontend is achieved via a JupyterLab notebook using the Plotly plotting library. Interactivity for these visualisations, such as choosing from a list of GitHub repositories to show data for, is done via the Mercury library.

In addition, this repository aims to follow international standards and good practices in open source development such as, but not limited to:

• SDPX 3 compliance with a LICENSE file (also see License section)
• REUSE 3.0 compliance with appropriate machine-readable SPDX metadata for all files and license texts in LICENSES directory
• README file (this document) conforming to the Standard Readme Specification
• Naming the primary branch of this repository main instead of master following modern best practices

Install

This section assumes knowledge of Python, Git, and using a GNU/Linux-based server including installing software from package managers and running a terminal session.

In addition, familiarity with JupyterLab and the Plotly plotting library are helpful when making modifications to the code.

Note: This software is designed to be deployed on a server by system administrators or developers, not on generic consumer devices.

This project requires Python version 3.10 or later on your server and running it in a Python virtual environment is optional but recommended. Detailed external library dependencies are listed in the standard-conformant requirements.txt file and also here:

• jupyterlab>=3.4.5
• mljar-mercury>=1.1.5
• pandas>=1.4.3
• plotly>=5.10

In addition to Python and the dependencies listed above, the following programs must be installed and accessible from the command line:

• git (version 2.7.4 or later)
• pip (version 19.3.1 or later)

Running locally from source

The code can be run from source and has been tested on updated versions of GNU/Linux server operating systems including Red Hat Enterprise Linux 8.7. While effort has been made to keep the Python scripts and JupyterLab notebook platform-agnostic, they have not been tested under other operating systems such as BSD-derivatives, Apple macOS or Microsoft Windows as they - especially the latter two - are rarely used for hosting code such as this.

On your server, with the tools git and pip installed, run the following commands in a terminal session to retrieve the latest version of this repository and prepare it for development and running locally (usually for testing):

git clone https://github.com/OPEN-NEXT/wp2.2_frontend_dev.git
pip install --user -r requirements.txt

The git command will download the files in this repository onto your server into a directory named wp2.2_frontend_dev, and pip will install the Python dependencies listed in requirements.txt.

In a terminal window at the root directory of this repository, start the server with the mercury command like this:

mercury run ./repos.ipynb

There will be some output in the terminal. If there are no obvious error messages, this means the demo frontend is up an running, and should be accessible on your local machine on port 8000 at 127.0.0.1 (i.e. 127.0.0.1:8000).

A demo of this showing possible visualisations for some OSH projects is hosted here:

http://wp22-frontend.us.to

Note: By default, the JupyterLab notebook repos.ipynb will use data contained in contrib/GitHub_repos_data.json and visualise them. This JSON file contains data from various open source hardware repositories hosted on GitHub. It is the same information that the dashboard backend API will provide.

Deploy to web

The code in this repository can be directly deployed to a cloud web app hosting provider such as Fly.io or Heroku. Here is an example of deplying to Heroku (assuming you already have an Heroku account):

1. Make sure your terminal prompt is in the root directory of this repository. With the Heroku commandline interface installed, login with this comamnd:

heroku container:login

2. Create a new Heroku app where "your app name" can be a name of your choosing:

heroku create [your app name]

3. It may take a couple minutes for the app to come online. You can check your Heroku account dashboard for a status update. Once it is online, you can open the app in your web browser:

heroku open

Usage

Frontends showing project status metrics from the dashboard backend API could be implemented independently. Such a frontend could show aggregate information about open source hardware projects hosted on GitHub or Wikifactory.

A major component of Open!Next D2.5 is that Wikifactory has implemented various frontend dashboard features. Some of these features are in production an viewable on various Wikifactory projects. This will be gradually rolled out to all Wikifactory projects in the coming months.

In addition to that, this repository implements a demo frontend that shows information about open source hardware repositories hosted on GitHub. After deploying this demo per the installation steps above, open it in your web browser. You can also visit a demo instance at: http://wp22-frontend.us.to

The following are basic steps for interacting with the demo:

1. When first loaded, there will be an initial page like this:

2. Under the "Choose a repository" menu, you can choose from a pre-populated list of GitHub repositories, such as nasa-jpl/open-source-rover:

3. Click on the green "Run" button and wait several seconds for the code to run. You should then see a series of visualisations on the right:

4. You can scroll down to see graphs of "Commits history", "Issues opened/closed", a list of "Tags" for the repository, and pie chart breakdowns of "File type" and "File editability", followed by "License information". Some of these visualisations are interactive.

5. For graphs such as commit and issue histories, you can use your mouse to click and drag a box to zoom in to:

6. Or, when you hover your mouse cursor over a slice in a pie chart, it will display a tool tip. In this screenshot, it is showing that 11.2% of the files in the nasa-jpl/open-source-rover repository are "ECAD" (electronics CAD) files:

7. For each visualisation, you can hover your mouse cursor over the top right to reveal more controls, such as a "camera" button for downloading a PNG image of the current view:

8. An additional feature is the blue "Download" button. Clicking this will allow you to download the visualisations as a PDF or HTML file for local viewing.

Maintainers

Dr Pen-Yuan Hsing (@penyuan) of the OPENNEXT project is the current maintainer.

Acknowledgements

The maintainer would like to gratefully acknowledge:

• Dr Jérémy Bonvoisin (@jbon) not only for the initial contributions to this work, but also for continued practical and theoretical insight, generosity, and guidance.
• Dr Elies Dekoninck (@elies30) and Rafaella Antoniou (@rafaellaantoniou) for valuable feedback and support.
• Max Kampik (@mkampik), Diego Vaquero, and Andrés Barreiro from Wikifactory for close collaboration, design insights, and technical support throughout the project.
• OPENNEXT internal reviewers Sonika Gogineni (@GoSFhg) and Martin Häuer (@moedn) for constructive criticism.
• OPENNEXT project researchers Robert Mies (@MIE5R0) and Mehera Hassan (@meherrahassan) for useful feedback and extensive administrative support.
• The Linux Foundation CHAOSS group for insights on open source community health metrics.
• The following people for their valuable feedback via a survey (see D2.5 report for details) (in alphabetical order of last name): Jean-François Boujut (@boujut), Martin Häuer (@moedn), James Jones (CubeSpawn), Max Kampik (@mkampik), Johannes Střelka-Petz.

The work in this repository is supported by a European Union Horizon 2020 programme grant (agreement ID 869984).

License

The Python code in this repository is licensed under the GNU AGPLv3 or any later version © 2022 Pen-Yuan Hsing

This README is licensed under the Creative Commons Attribution-ShareAlike 4.0 International license (CC BY-SA 4.0) © 2022 Pen-Yuan Hsing

Details on other files are in the REUSE specification dep5 file.