Commit 8be919fec42b4ff5e2f7f36d1f76cc197ef97c2f
1 parent
d70a53f181
Exists in
main
update readme with configuration info, swappiness tip, and instructions for alar…
…mist and slackbot service installation
Showing 1 changed file with 24 additions and 4 deletions Inline Diff
README.md
View file @
8be919f
| # SOARS status and alerting system | 1 | 1 | # SOARS status and alerting system | |
| This codebase contains software components for the SOARS status and alerting system. This system collects data from numerous sensors to monitor the health and safe operation of the paddle and other SOARS subsystems. Data from the system can be displayed in a dashboard, and status lights and buzzer convey system state and whether any parameters are outside normal. The majority of this software is written in python, requiring python 3.10 or newer. Most of this software runs on a Raspberry Pi Zero 2 W embedded computer, with sensors connected via USB. | 2 | 2 | This codebase contains software components for the SOARS status and alerting system. This system collects data from numerous sensors to monitor the health and safe operation of the paddle and other SOARS subsystems. Data from the system can be displayed in a dashboard, and status lights and buzzer convey system state and whether any parameters are outside normal. The majority of this software is written in python, requiring python 3.10 or newer. Most of this software runs on a Raspberry Pi Zero 2 W embedded computer, with sensors connected via USB. | |
|  | 3 | 3 |  | |
| 4 | 4 | |||
| 5 | 5 | |||
| --- | 6 | 6 | --- | |
| 7 | 7 | |||
| 8 | 8 | |||
| # software components | 9 | 9 | # software components | |
| ## Influxdb OSS v1.8 | 10 | 10 | ## Influxdb OSS v1.8 | |
| Influxdb is an opensource timeseries database. Timestamped measurements are written into the database and can be visualized with the included Chronograf web application, or queried using a SQL-like query language, InfluxQL. The SOARS labview control program has been modified to report motor torque, and the various monitor programs below report their respective measurements (temperature, strain, flow, etc) | 11 | 11 | Influxdb is an opensource timeseries database. Timestamped measurements are written into the database and can be visualized with the included Chronograf web application, or queried using a SQL-like query language, InfluxQL. The SOARS labview control program has been modified to report motor torque, and the various monitor programs below report their respective measurements (temperature, strain, flow, etc) | |
| ## tc08-monitor.py | 12 | 12 | ## tc08-monitor.py | |
| This python program communicates over usb with the tc-08 8-channel thermocouple interface card to report temperature data to the influxdb database. It uses the manufacturer-supplied python bindings for their C SDK, `libusbtc08`. See more information at their website: https://www.picotech.com/downloads/linux. Currently paddle bearing temperatures and air piston temperatures are reported by this program. | 13 | 13 | This python program communicates over usb with the tc-08 8-channel thermocouple interface card to report temperature data to the influxdb database. It uses the manufacturer-supplied python bindings for their C SDK, `libusbtc08`. See more information at their website: https://www.picotech.com/downloads/linux. Currently paddle bearing temperatures and air piston temperatures are reported by this program. | |
| ## DI-1000U-monitor.py | 14 | 14 | ## DI-1000U-monitor.py | |
| This python program communicates over usb with the DI-1000U strain gauges. These gauges have a very simple protocal, where new values are polled at will. Data is written to influxdb. | 15 | 15 | This python program communicates over usb with the DI-1000U strain gauges. These gauges have a very simple protocal, where new values are polled at will. Data is written to influxdb. | |
| ## flow-meter-monitor.py | 16 | 16 | ## flow-meter-monitor.py | |
| This python program communicates over usb with an arduino nano every running the `flow-meter-arduino` project. It listens for updates and writes them to influxdb. | 17 | 17 | This python program communicates over usb with an arduino nano every running the `flow-meter-arduino` project. It listens for updates and writes them to influxdb. | |
| ## flow-meter-arduino | 18 | 18 | ## flow-meter-arduino | |
| This arudino program serves as a totalizer for digital flow meters, as well as a usb bridge to send data to the `flow-meter-monitor` program running on the RaspberryPi. See comments in arduino program for details on protocol and flow coefficient. | 19 | 19 | This arudino program serves as a totalizer for digital flow meters, as well as a usb bridge to send data to the `flow-meter-monitor` program running on the RaspberryPi. See comments in arduino program for details on protocol and flow coefficient. | |
|  | 20 | 20 |  | |
| ## alarmist.py | 21 | 21 | ## alarmist.py | |
| This python program polls temperature, torque, and other measurements from influxdb and uses them to set status lights or alarms. These checks are done in the `check_state` method for the Alarmist class, and get run every time a measurement gets updated. | 22 | 22 | This python program polls temperature, torque, and other measurements from influxdb and uses them to set status lights or alarms. These checks are done in the `check_state` method for the Alarmist class, and get run every time a measurement gets updated. | |
| ### Lights | 23 | 23 | ### Lights | |
| The "christmas tree" lightstacks are controlled by `alarmist` via a relay board, which converts digital i/o signals from the raspberry pi into a 24V supply voltage for each light or buzzer channel. | 24 | 24 | The "christmas tree" lightstacks are controlled by `alarmist` via a relay board, which converts digital i/o signals from the raspberry pi into a 24V supply voltage for each light or buzzer channel. | |
| 25 | 25 | |||
| 26 | 26 | |||
| | Channel name | Pi GPIO pin | Pi header pin | Relay channel | lighstack wire color | | 27 | 27 | | Channel name | Pi GPIO pin | Pi header pin | Relay channel | lighstack wire color | | |
| | ------------ | ----------- | ------------- | ------------- | -------------------- | | 28 | 28 | | ------------ | ----------- | ------------- | ------------- | -------------------- | | |
| | Buzzer | GPIO 17 | 11 | 1 | Purple | | 29 | 29 | | Buzzer | GPIO 17 | 11 | 1 | Purple | | |
| | White | GPIO 27 | 13 | 2 | White | | 30 | 30 | | White | GPIO 27 | 13 | 2 | White | | |
| | Blue | GPIO 22 | 15 | 3 | Blue | | 31 | 31 | | Blue | GPIO 22 | 15 | 3 | Blue | | |
| | Green | GPIO 23 | 16 | 4 | Green | | 32 | 32 | | Green | GPIO 23 | 16 | 4 | Green | | |
| | Yellow | GPIO 24 | 18 | 5 | Yellow | | 33 | 33 | | Yellow | GPIO 24 | 18 | 5 | Yellow | | |
| | Red | GPIO 25 | 22 | 6 | Red | | 34 | 34 | | Red | GPIO 25 | 22 | 6 | Red | | |
| 35 | 35 | |||
| 36 | 36 | |||
|  | 37 | 37 |  | |
| ## systemd .service definitions | 38 | 38 | ## systemd .service definitions | |
| Each python program (tc08-monitor, DI-1000U-monitor, flow-meter-monitor, alarmist) has a corresponding example service defintion file compatible with `systemd`, a linux service manager. Once installed and activated (see installation section), each service will be automatically run on startup, relaunched after a crash, or can be manually controlled using the `systemctl` command, for example `sudo systemctl stop tc08-monitor.service`. Some common commands are `stop`, `start`, and `restart`. Log files can be viewed with `journalctl`, for example `sudo journalctl -u tc08-monitor.service --since "1 hour ago"`. | 39 | 39 | Each python program (tc08-monitor, DI-1000U-monitor, flow-meter-monitor, alarmist) has a corresponding example service defintion file compatible with `systemd`, a linux service manager. Once installed and activated (see installation section), each service will be automatically run on startup, relaunched after a crash, or can be manually controlled using the `systemctl` command, for example `sudo systemctl stop tc08-monitor.service`. Some common commands are `stop`, `start`, and `restart`. Log files can be viewed with `journalctl`, for example `sudo journalctl -u tc08-monitor.service --since "1 hour ago"`. | |
| 40 | 40 | |||
| 41 | 41 | |||
| --- | 42 | 42 | --- | |
| 43 | 43 | |||
| 44 | 44 | |||
| # Requirements | 45 | 45 | # Requirements | |
| - Tested on Raspberry Pi running Raspbian Lite OS (32-bit) "Bullseye" (Debain 11) Kernel Version 5.15 | 46 | 46 | - Tested on Raspberry Pi running Raspbian Lite OS (32-bit) "Bullseye" (Debain 11) Kernel Version 5.15 | |
| - Python3.6 or later | 47 | 47 | - Python3.6 or later | |
| - [influxdb-python](https://github.com/influxdata/influxdb-python) | 48 | 48 | - [influxdb-python](https://github.com/influxdata/influxdb-python) | |
| - numpy (dependency of picosdk) | 49 | 49 | - numpy (dependency of picosdk) | |
| - [picosdk](https://www.picotech.com/downloads/linux) (installs [picosdk-python-wrappers](https://github.com/picotech/picosdk-python-wrappers/tree/master/usbtc08Examples)) | 50 | 50 | - [picosdk](https://www.picotech.com/downloads/linux) (installs [picosdk-python-wrappers](https://github.com/picotech/picosdk-python-wrappers/tree/master/usbtc08Examples)) | |
| - [InfluxDB](https://docs.influxdata.com/influxdb/v1.8/) 1.x (tested on 1.8.10) | 51 | 51 | - [InfluxDB](https://docs.influxdata.com/influxdb/v1.8/) 1.x (tested on 1.8.10) | |
| - [Chronograf](https://docs.influxdata.com/chronograf/v1.9/) (web ui and visualization for InfluxDB) | 52 | 52 | - [Chronograf](https://docs.influxdata.com/chronograf/v1.9/) (web ui and visualization for InfluxDB) | |
| 53 | 53 | |||
| 54 | 54 | |||
| --- | 55 | 55 | --- | |
| 56 | 56 | |||
| 57 | 57 | |||
| # Installation | 58 | 58 | # Installation | |
| 59 | 59 | |||
| ## Raspberry Pi setup | 60 | 60 | ## Raspberry Pi setup | |
| 1. [Raspberry Pi installation guide](https://www.raspberrypi.com/documentation/computers/getting-started.html#using-raspberry-pi-imager) | 61 | 61 | 1. [Raspberry Pi installation guide](https://www.raspberrypi.com/documentation/computers/getting-started.html#using-raspberry-pi-imager) | |
| 2. Run `apt update` | 62 | 62 | 2. Run `apt update` | |
| 63 | 63 | |||
| ### wifi | 64 | 64 | ### wifi | |
| 65 | 65 | |||
| Getting onto a WPA2 enterprise network takes some special setup. | 66 | 66 | Getting onto a WPA2 enterprise network takes some special setup. | |
| 67 | 67 | |||
| - Generate a hash of your password with the command `echo -n 'your_password_in_plaintext' | iconv -t utf16le | openssl md4` (might need to use `UTF-16LE` on mac for iconv parameter). This will generate a string like `(stdin)= d331672fc5c43a5db13c295458beeea1`. The hashed password is just the string `d331672fc5c43a5db13c295458beeea1`. | 68 | 68 | - Generate a hash of your password with the command `echo -n 'your_password_in_plaintext' | iconv -t utf16le | openssl md4` (might need to use `UTF-16LE` on mac for iconv parameter). This will generate a string like `(stdin)= d331672fc5c43a5db13c295458beeea1`. The hashed password is just the string `d331672fc5c43a5db13c295458beeea1`. | |
| - Add this block to `/etc/wpa_supplicant.conf`, replacing `NETWORK-NAME`, `USERNAME`, and `HASH` with the appropriate values (e.g. `campus-wifi`, `person@school.edu`, and `d331672fc5c43a5db13c295458beeea1` from above hash example) | 69 | 69 | - Add this block to `/etc/wpa_supplicant.conf`, replacing `NETWORK-NAME`, `USERNAME`, and `HASH` with the appropriate values (e.g. `campus-wifi`, `person@school.edu`, and `d331672fc5c43a5db13c295458beeea1` from above hash example) | |
| 70 | 70 | |||
| ``` | 71 | 71 | ``` | |
| network={ | 72 | 72 | network={ | |
| ssid="NETWORK-NAME" | 73 | 73 | ssid="NETWORK-NAME" | |
| proto=RSN | 74 | 74 | proto=RSN | |
| key_mgmt=WPA-EAP | 75 | 75 | key_mgmt=WPA-EAP | |
| auth_alg=OPEN | 76 | 76 | auth_alg=OPEN | |
| eap=PEAP | 77 | 77 | eap=PEAP | |
| identity="USERNAME" | 78 | 78 | identity="USERNAME" | |
| password=hash:HASH | 79 | 79 | password=hash:HASH | |
| phase1="peaplabel=0" | 80 | 80 | phase1="peaplabel=0" | |
| phase2="auth=MSCHAPV2" | 81 | 81 | phase2="auth=MSCHAPV2" | |
| priority=1 | 82 | 82 | priority=1 | |
| } | 83 | 83 | } | |
| ``` | 84 | 84 | ``` | |
| 85 | 85 | |||
| - Append the following to the end of `/etc/dhcpcd.conf` | 86 | 86 | - Append the following to the end of `/etc/dhcpcd.conf` | |
| 87 | 87 | |||
| ``` | 88 | 88 | ``` | |
| interface wlan0 | 89 | 89 | interface wlan0 | |
| env ifwireless = 1 | 90 | 90 | env ifwireless = 1 | |
| env wpa_supplicant_driver = wext , nl80211 | 91 | 91 | env wpa_supplicant_driver = wext , nl80211 | |
| ``` | 92 | 92 | ``` | |
| 93 | ### Swappiness | |||
| 94 | Raspbian defaults to high memory swapping threshold (60 on scale of 1-100), which can lead to high cpu usage. Change to 1: | |||
| 95 | - Edit or append the line `vm.swappiness = 1` to `/etc/sysctl.conf` | |||
| 96 | - Reload config with `sudo sysctl -p` | |||
| 97 | - Confirm setting with `cat /proc/sys/vm/swappiness` | |||
| 93 | 98 | |||
| ### python | 94 | 99 | ### python | |
| 95 | 100 | |||
| 1. Make sure pip is installed | 96 | 101 | 1. Make sure pip is installed | |
| `sudo apt install python3-pip` | 97 | 102 | `sudo apt install python3-pip` | |
| 2. install `influxdb` python module | 98 | 103 | 2. install `influxdb` python module | |
| `pip3 install influxdb` | 99 | 104 | `pip3 install influxdb` | |
| 100 | 105 | |||
| ## Install and run Influxdb OSS v1.8 | 101 | 106 | ## Install and run Influxdb OSS v1.8 | |
| 102 | 107 | |||
| Instructions for latest 1.x OSS influxdb build ([source](https://pimylifeup.com/raspberry-pi-influxdb/)): | 103 | 108 | Instructions for latest 1.x OSS influxdb build ([source](https://pimylifeup.com/raspberry-pi-influxdb/)): | |
| 104 | 109 | |||
| 1. Update apt and upgrade current packages | 105 | 110 | 1. Update apt and upgrade current packages | |
| - `sudo apt update` | 106 | 111 | - `sudo apt update` | |
| - `sudo apt upgrade` | 107 | 112 | - `sudo apt upgrade` | |
| 2. Import influxdb repository key | 108 | 113 | 2. Import influxdb repository key | |
| - `curl https://repos.influxdata.com/influxdata-archive.key | gpg --dearmor | sudo tee /usr/share/keyrings/influxdb-archive-keyring.gpg >/dev/null` | 109 | 114 | - `curl https://repos.influxdata.com/influxdata-archive.key | gpg --dearmor | sudo tee /usr/share/keyrings/influxdb-archive-keyring.gpg >/dev/null` | |
| 3. Add repository to apt sources list | 110 | 115 | 3. Add repository to apt sources list | |
| - `echo "deb [signed-by=/usr/share/keyrings/influxdb-archive-keyring.gpg] https://repos.influxdata.com/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/influxdb.list` | 111 | 116 | - `echo "deb [signed-by=/usr/share/keyrings/influxdb-archive-keyring.gpg] https://repos.influxdata.com/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/influxdb.list` | |
| 4. Update apt again | 112 | 117 | 4. Update apt again | |
| - `sudo apt update` | 113 | 118 | - `sudo apt update` | |
| 5. Install influxdb with apt | 114 | 119 | 5. Install influxdb with apt | |
| - `sudo apt install influxdb` | 115 | 120 | - `sudo apt install influxdb` | |
| 6. Enable influxdb service and run it | 116 | 121 | 6. Enable influxdb service and run it | |
| - `sudo systemctl unmask influxdb` | 117 | 122 | - `sudo systemctl unmask influxdb` | |
| - `sudo systemctl enable influxdb` | 118 | 123 | - `sudo systemctl enable influxdb` | |
| - `sudo systemctl start influxdb` | 119 | 124 | - `sudo systemctl start influxdb` | |
| 120 | 125 | |||
| ## Install and run Chronograf | 121 | 126 | ## Install and run Chronograf | |
| 1. Assuming influxdb is already installed, you can install chronograf with apt | 122 | 127 | 1. Assuming influxdb is already installed, you can install chronograf with apt | |
| - `sudo apt install chronograf` | 123 | 128 | - `sudo apt install chronograf` | |
| 2. Enable chronograf service and run it | 124 | 129 | 2. Enable chronograf service and run it | |
| - `sudo systemctl unmask chronograf` | 125 | 130 | - `sudo systemctl unmask chronograf` | |
| - `sudo systemctl enable chronograf` | 126 | 131 | - `sudo systemctl enable chronograf` | |
| - `sudo systemctl start chronograf` | 127 | 132 | - `sudo systemctl start chronograf` | |
| 3. Log in to `http://[rasperry-pi-hostname]:8888/` to configure dashboards. | 128 | 133 | 3. Log in to `http://[rasperry-pi-hostname]:8888/` to configure dashboards. | |
| 129 | 134 | |||
| ## picosdk installation (for tc-08 hardware) | 130 | 135 | ## picosdk installation (for tc-08 hardware) | |
| 131 | 136 | |||
| [picotech website](https://www.picotech.com/downloads/linux) | 132 | 137 | [picotech website](https://www.picotech.com/downloads/linux) | |
| 133 | 138 | |||
| On the raspberry pi: | 134 | 139 | On the raspberry pi: | |
| 135 | 140 | |||
| 1. Download and install libusbtc08 debian package | 136 | 141 | 1. Download and install libusbtc08 debian package | |
| - `wget https://labs.picotech.com/debian/pool/main/libu/libusbtc08/libusbtc08_2.0.17-1r1441_armhf.deb` | 137 | 142 | - `wget https://labs.picotech.com/debian/pool/main/libu/libusbtc08/libusbtc08_2.0.17-1r1441_armhf.deb` | |
| - `sudo apt install ./libusbtc08_2.0.17-1r1441_armhf.deb` | 138 | 143 | - `sudo apt install ./libusbtc08_2.0.17-1r1441_armhf.deb` | |
| 2. Clone python wrappers git repo and install from it | 139 | 144 | 2. Clone python wrappers git repo and install from it | |
| - `git clone https://github.com/picotech/picosdk-python-wrappers.git` | 140 | 145 | - `git clone https://github.com/picotech/picosdk-python-wrappers.git` | |
| - `cd picosdk-python-wrappers` | 141 | 146 | - `cd picosdk-python-wrappers` | |
| - `pip install .` | 142 | 147 | - `pip install .` | |
| 143 | 148 | |||
| ## Install monitors | 144 | 149 | ## Install monitors | |
| 145 | 150 | |||
| 1. Clone or copy this repository to the Raspberry Pi, probably in a folder called `soars-status-alerting` in the home directory. | 146 | 151 | 1. Clone or copy this repository to the Raspberry Pi, probably in a folder called `soars-status-alerting` in the home directory. | |
| 2. Install tc08 service | 147 | 152 | 2. Configure | |
| 153 | - Edit `ssa/influxdb/influxdb_bridge.py` with appropriate influxdb options (hostname and port, dbname). | |||
| 154 | - Edit `ssa/alarmist_config.ini` and populate influxdb details and adjust alarm thresholds. | |||
| 155 | - Edit `ssa/slackbot_config.ini` and populate influxdb details and slack credentials. | |||
| 156 | 3. Install tc08 service | |||
| - `sudo cp tc08/tc08-monitor.service /etc/systemd/system/.` | 148 | 157 | - `sudo cp tc08/tc08-monitor.service /etc/systemd/system/.` | |
| - edit `/etc/systemd/system/tc08-monitor.service` and replace all instances of `path/to/repo` with the directory where you cloned or copied `soars-status-alerting`. | 149 | 158 | - edit `/etc/systemd/system/tc08-monitor.service` and replace all instances of `path/to/repo` with the directory where you cloned or copied `soars-status-alerting`. | |
| - `sudo systemctl daemon-reload` | 150 | 159 | - `sudo systemctl daemon-reload` | |
| - `sudo systemctl enable tc08-monitor` | 151 | 160 | - `sudo systemctl enable tc08-monitor` | |
| - `sudo systemctl start tc08-monitor` | 152 | 161 | - `sudo systemctl start tc08-monitor` | |
| 3. Install DI-1000U-monitor | 153 | 162 | 4. Install DI-1000U-monitor | |
| - `sudo cp DI-1000U/DI-1000U-monitor.service /etc/systemd/system/.` | 154 | 163 | - `sudo cp DI-1000U/DI-1000U-monitor.service /etc/systemd/system/.` | |
| - edit `/etc/systemd/system/DI-1000U-monitor.service` and replace all instances of `path/to/repo` with the directory where you cloned or copied `soars-status-alerting`. | 155 | 164 | - edit `/etc/systemd/system/DI-1000U-monitor.service` and replace all instances of `path/to/repo` with the directory where you cloned or copied `soars-status-alerting`. | |
| - `sudo systemctl daemon-reload` | 156 | 165 | - `sudo systemctl daemon-reload` |