Skip to content
Snippets Groups Projects
Commit c31a5c27 authored by David Heinrich Bailey's avatar David Heinrich Bailey :speech_balloon:
Browse files

Merge branch 'docs/README' into 'master'

docs: :sparkles: add README and Grafana Panel backups

See merge request !2
parents 6de9656a cf7577e9
Branches master
No related tags found
1 merge request!2docs: :sparkles: add README and Grafana Panel backups
Pipeline #6803744 passed
# Hardware Testing++
# Smoothware Testbench
This repository holds the Smoothware Testbench python code package. This code is used to perform hardware testing and verification, mainly for the uQDS Channel testing system.
It has two main purposes:
- To provide an easy and abstracted interface to hardware devices and test bench setups, in a reusable and repeatable fashion.
- Testbench device access is abstracted behind simple key/value pairs, testbenches can be set up and reset in repeatable fashion
- To provide an interface to configure test executions of hardware
- Test executions can be configured to run measurements with varying parameters, such as linearly varying a DC voltage source, or logarithmically going through a frequency range.
## Getting started
It also has a second folder (bin), which is configured specifically for the uQDS Testbench. It can serve as an example for how to set up the connection to devices
and test setups.
To make it easy for you to get started with GitLab, here's a list of recommended next steps.
## Doxygen source docs
Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!
There are automatic [Doxygen source docs available here](http://smoothware-testbench.docs.cern.ch/), and as such, this README won't go into detail on such.
## Add your files
## Looking for an owner!
- [ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files
- [ ] [Add files using the command line](https://docs.gitlab.com/ee/gitlab-basics/add-file.html#add-a-file-using-the-command-line) or push an existing Git repository with the following command:
This project was made by David Bailey during his temporary internship. Although it is functional, it would be nice to have someone there to maintain and understand it.
```
cd existing_repo
git remote add origin https://gitlab.cern.ch/qps/hardware-testing.git
git branch -M master
git push -uf origin master
```
All I ask is that you treat it carefully, and use proper pull-requests to merge code, honouring the CI pipelines. We do clean code here.
## Table of contents
1. [Config File Reference](#config-file-quick-reference) to describe the config file options
2. [Installation](#installation)
3. [Database Setup](#database-setup)
4. [Grafana Setup](#grafana-setup)
## Integrate with your tools
## Installation
- [ ] [Set up project integrations](https://gitlab.cern.ch/qps/hardware-testing/-/settings/integrations)
The code itself has not fully been configured as python package, but can be added to the include path of your python env.
It only needs two prerequisites:
## Collaborate with your team
- Numpy
- Pandas
- [ ] [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/)
- [ ] [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)
- [ ] [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically)
- [ ] [Enable merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/)
- [ ] [Automatically merge when pipeline succeeds](https://docs.gitlab.com/ee/user/project/merge_requests/merge_when_pipeline_succeeds.html)
Should be fairly simple. *However*, device drivers, uQDS connections or similar *are not handled by this* and must be added separately.
This library contains wrappers for common systems such as DC sources, function generators, switching matrices etc., and it's encouraged to hook
into these wrappers or write your own following their style.
## Test and Deploy
### uQDS Testbench
Use the built-in continuous integration in GitLab.
The uQDS testbench has a few extra needs, as it requires a lot of drivers for the actual measurement hardware.
Sadly, these systems were not necessarily properly cleaned up, and the setup relies on a rather specific PyCharm instance that has multiple include paths.
- [ ] [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/index.html)
- [ ] [Analyze your code for known vulnerabilities with Static Application Security Testing(SAST)](https://docs.gitlab.com/ee/user/application_security/sast/)
- [ ] [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html)
- [ ] [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/ee/user/clusters/agent/)
- [ ] [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html)
The basics are, however:
***
1. Instantiating all the device drivers as needed
2. Instantiating the SmoothwareTB Testbench and configuring device drivers there.
3. Configuring a database as according to the setup section
4. Configuring the actual test setups with the Test Sweep system
5. Running them
# Editing this README
Check out the `bin` folder of this directory. It contains all the test setups for the uQDS channel testbench.
When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thank you to [makeareadme.com](https://www.makeareadme.com/) for this template.
## Database Setup
## Suggestions for a good README
Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.
This code uses a simple PostgreSQL database as backend. You will need to set it up a little before being able to use this script.
## Name
Choose a self-explaining name for your project.
### Initial setup
## Description
Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.
For users at CERN, this can be done by following the [DBOD setup guide for PostgreSQL](https://dbod-user-guide.web.cern.ch/getting_started/PostgreSQL/postgresql/).
## Badges
On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
You will also need to tweak the `pg_hba.conf` file to allow connection of your users. In the DBOD panel, File Editor again, `pg_hba.conf`.
Make sure your own database user can get access, e.g.:
`host all admin 0.0.0.0/0 md5`
## Visuals
Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.
Then, to set up a minimal database:
- Connect to the DB with your admin credentials.
- Create a new user+database for the testbench
- If needed, create a Grafana read-only user to plot data with.
## Installation
Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.
```SQL
CREATE USER [username] PASSWORD [password];
CREATE DATABASE [db_name] WITH OWNER [username];
## Usage
Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.
\c [db_name]
## Support
Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
CREATE USER [grafana-username] PASSWORD [grafana-password];
GRANT USAGE ON SCHEMA public TO [grafana-username];
GRANT SELECT ON ALL TABLES IN SCHEMA public TO [grafana-username];
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO [grafana-username];
```
You now need to go back to the `pg_hba.conf` file to add the testbench and Grafana users. Add the lines:
```
host [db_name] [japc_user] 0.0.0.0/0 md5
host [db_name] [grafana-user] 0.0.0.0/0 md5
```
Check if you can connect to them via `psql` now, after the database was reloaded.
## Roadmap
If you have ideas for releases in the future, it is a good idea to list them in the README.
Once you configured the testbench, it will create the necessary tables for you - no further table setup is needed for this!
Also, check the Doxygen documentation, which [describes the Table Schema](https://smoothware-testbench.docs.cern.ch/classsmoothwaretb_1_1database_1_1testbench__db__handler_1_1TestbenchDBHandler.html#a8034b17210ce4e031ea93c3fe3f28954) a bit more.
## Contributing
State if you are open to contributions and what your requirements are for accepting them.
For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.
You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.
## Grafana Setup
[Grafana](https://grafana.com/) is the recommended observability platform to use alongside this adapter to plot and monitor data. CERN already has some instances appropriately set up, the recommended one being [the MONIT instance](https://monit-grafana.cern.ch/). Your section should be able to request access to it and receive its own organization within it.
You can easily add the DBOD PostgreSQL instance as standard Postgres instance data source in Grafana. Use the username+password combination supplied during [the database setup](#database-setup) - using the readonly Grafana user, NOT the Testbench-user!
From here, it is recommended to use the [getting started guides](https://grafana.com/docs/grafana/latest/getting-started/build-first-dashboard/) to plot your data.
There are backups for the uQDS Channel grafana panels available in the `grafana-panels` folder.
Also, for plots such as heatmaps or non-timeseries data, the [Plotly.JS Grafana panel](https://github.com/nline/nline-plotlyjs-panel) works great, if you know Plotly and some very simple Javascript. Much better for high-point-count plots (>2k and above), as well as heatmap plots or similar.
## Support
Originally this script was created by David Bailey, who is most likely no longer at CERN (unless you get lucky and I'm back ;) )
His E-Mail is davidbailey.2889@gmail.com
Otherwise, Magnus Christensen had a hand in setting up some Grafana items as well.
## Authors and acknowledgment
Show your appreciation to those who have contributed to the project.
## License
For open source projects, say how it is licensed.
Primary Author: David Bailey (davidbailey.2889@gmail.com)
With thanks to: Magnus Christensen for giving Grafana a footing here,
Jens Steckert for letting me work on this next to his precious uQDS Channels.
Some personal thanks also go to my friends Neira and Mesh, for providing experience with database setups and flexible schema layout.
## Project status
If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.
## License
MIT, baby. Take it, use it, enjoy it, make it.
\ No newline at end of file
This diff is collapsed.
# Grafana panel backups
These JSON files are backups of the Grafana panels used in the CERN uQDS Channel Testbench.
They can be imported into a Grafana instance such as MonIT, and should be connected to the same PostgreSQL database that the Testbench itself is writing to!
This diff is collapsed.
This diff is collapsed.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment