Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Address minor issues in README.md #22

Merged
merged 4 commits into from
Apr 7, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 27 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
@@ -2,13 +2,25 @@

A simple Air Quality Index monitor, designed to work on the Raspberry Pi with the SDS011 Nova PM Sensor.

## Installation
- [AQIMON](#aqimon)
- [Installation](#installation)
- [Pre-Requisites](#pre-requisites)
- [Install](#install)
- [Running Aqimon](#running-aqimon)
- [Configure With Systemd](#configure-with-systemd)
- [Configuration](#configuration)
- [Contributing](#contributing)
- [Toolset](#toolset)
- [Quickstart](#quickstart)
- [Using the Mock Reader](#using-the-mock-reader)
- [Submitting a PR](#submitting-a-pr)

## Installation

### Pre-Requisites

* Python 3.9+
* [uhubctl](https://github.com/mvp/uhubctl) must be installed and on your PATH.
- Python 3.9+
- [uhubctl](https://github.com/mvp/uhubctl) must be installed and on your PATH.

### Install

@@ -18,21 +30,23 @@ pip install aqimon

## Running Aqimon

Aqimon is a simple web server. To start with all the defaults, you can just run:
Aqimon is a simple web server. To start with all the defaults (assuming available SDS011 hardware on `/dev/ttyUSB0`), you can just run:

```commandline
aqimon
```

And then go to your browser at `http://{serveraddress}:8000/` to view the UI.

If you don't have the requisite SDS011 hardware, you can use a mock data source via a [mock reader](#using-the-mock-reader).

### Configure With Systemd

Generally, you'd want to run `Aqimon` as an always-on service, using `systemd`.

To do so, create a file at `/etc/systemd/system/aqimin.service` with the following contents:

```
```text
[Unit]
Description=AQIMON
After=multi-user.target
@@ -59,7 +73,7 @@ Aqimon uses environment variables for configuration, but all values should ship

| Variable | Default | Description |
|----------------------------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| **AQIMON_DB_PATH** | ~/.aqimon/db.sqlite | The path to the database file, where read information is stored. It should be an absolute path; user home expansion is supported. |
| **AQIMON_DB_PATH** | ~/.aqimon/db.sqlite | The path to the database file, where read information is stored. It should be an absolute path; user home expansion is supported. |
| **AQIMON_POLL_FREQUENCY_SEC** | 900 (15 minutes) | Sets how frequently to read from the device, in seconds. |
| **AQIMON_RETENTION_MINUTES** | 10080 (1 week) | Sets how long data will be kept in the database, in minutes. |
| **AQIMON_READER_TYPE** | NOVAPM | The reader type to use, either NOVAPM or MOCK. |
@@ -68,19 +82,18 @@ Aqimon uses environment variables for configuration, but all values should ship
| **AQIMON_SAMPLE_COUNT_PER_READ** | 5 | The number of reads to take with each sample. |
| **AQIMON_SERVER_PORT** | 8000 | The port to run the server on. |
| **AQIMON_SERVER_HOST** | 0.0.0.0 | The host to run the server on. |


## Contributing

### Toolset

To start developing, you'll need to install the following tools:

* [Python 3.9+](https://www.python.org/) - For API Code
* [Elm 0.19](https://elm-lang.org/) - For client code
* [poetry](https://python-poetry.org/) - For python package management
* [justfile](https://github.com/casey/just) - For builds
* [elm-format](https://github.com/avh4/elm-format) - For auto-formatting elm code.
- [Python 3.9+](https://www.python.org/) - For API Code
- [Elm 0.19](https://elm-lang.org/) - For client code
- [poetry](https://python-poetry.org/) - For python package management
- [justfile](https://github.com/casey/just) - For builds
- [elm-format](https://github.com/avh4/elm-format) - For auto-formatting elm code.

Optionally, we have [pre-commit](https://pre-commit.com/) hooks available as well. To install hooks, just run
`pre-commit install` and then linters and autoformatting will be applied automatically on commit.
@@ -119,7 +132,7 @@ just format

### Using the Mock Reader

Aqimon ships with a mock reader class that you can use in the event that you don't have a reader available on your
Aqimon ships with a mock reader class that you can use in the event that you don't have a reader available on your
development computer. The mock reader just returns randomized reads. To use it, you can start the server like:

```commandline
@@ -128,6 +141,5 @@ AQIMON_READER_TYPE=MOCK poetry run aqimon

### Submitting a PR

Master branch is locked, but you can open a PR on the repo. Build checks must pass, and changes approved by a code
Master branch is locked, but you can open a PR on the repo. Build checks must pass, and changes approved by a code
owner, before merging.