frugal-iot-server 2.0.8 → 2.0.10

package/README.md

@@ -3,7 +3,7 @@
 ## Installation
 
 For a self-contained server on a Raspberry Pi - including the MQTT broker, and starting from a
-blank SD card - see [INSTALLATION.md](INSTALLATION.md), which also has a script that does the whole
+blank SD card - see [docs/INSTALLATION.md](docs/INSTALLATION.md), which also has a script that does the whole
 thing in one go once you can ssh in.
 
 On a unix box that is already running ...
@@ -91,7 +91,7 @@ verbose: true
 and each message reappears as `Received dev/lotus/esp8266-85ea2b/humidity   71.8`. `morgan: true`
 in `config.d/server.yaml` does the same for web requests. Turn both off again afterwards.
 There is more on what gets written, and how to see how much, under
-[Wear and tear on the SD card](INSTALLATION.md#wear-and-tear-on-the-sd-card).
+[Wear and tear on the SD card](docs/INSTALLATION.md#wear-and-tear-on-the-sd-card).
 
 Open a browser pointing at for example `localhost:8080` and you should see the UI.
 
@@ -161,7 +161,7 @@ expensive on an SD card.
 To set it up as a service that runs at startup (and instructions vary between flavors of Linux)
 
 copy and edit `extras/frugaliot.service` to `/etc/systemd/system/frugaliot.service`. As shipped it
-matches the Raspberry Pi install in [INSTALLATION.md](INSTALLATION.md) - user `pi`, installed in
+matches the Raspberry Pi install in [docs/INSTALLATION.md](docs/INSTALLATION.md) - user `pi`, installed in
 `/home/pi/frugal-iot` - so on any other machine change `User`, `WorkingDirectory` and `ExecStart`
 to the account and directory you installed into.
 ```

package/config.d/email.yaml

@@ -3,7 +3,7 @@
 #
 # Leave it commented out on a server that should not send mail.
 #
-# For Gmail - the common case, written out step by step in INSTALLATION.md section 9a:
+# For Gmail - the common case, written out step by step in docs/INSTALLATION.md section 9a:
 #   1. Turn on 2-Step Verification: https://myaccount.google.com/signinoptions/twosv
 #      App passwords do not exist until you do, which is where most people get stuck.
 #   2. Create an app password:      https://myaccount.google.com/apppasswords

package/config.d/opensearch.yaml

@@ -1,23 +1,27 @@
-# This server's own OpenSearch - the one INSTALL-OPENSEARCH.md sets up on the server itself.
+# This server's own OpenSearch - the one docs/INSTALL-OPENSEARCH.md sets up on the server itself.
 #
 # Leave it all commented out on a server without one. With it filled in, an organization's
 # administrator can choose "OpenSearch on this server" on the dashboard's Forwarders card, and make a
 # login for OpenSearch Dashboards on the Dashboards access card. Neither shows an address or a password:
 # they come from here, and never leave this machine.
 #
-# opensearch:
-#   node: http://localhost:9200          # where this server reaches OpenSearch - on this machine
-#   username: frugaliot_logger           # what the forwarder writes readings as
-#   password: change-me
-#   # insecure: true                     # only for OpenSearch's demo certificate, which no one can check
+# Write the lines at the top level, as below: the file's name already says they are about opensearch.
+#
+# node: https://localhost:9200         # where this server reaches OpenSearch - on this machine.
+#                                      # https on a Linux install (it has a login); http://localhost:9200
+#                                      # only for Homebrew's OpenSearch on a Mac, which has neither
+# username: admin                      # what the forwarder writes readings as
+# password: change-me
+# insecure: true                       # OpenSearch's own certificate is self-signed, which can't be checked.
+#                                      # Needed with https://localhost; leave it out for http
 #
-#   # The account that makes and removes the per-organization logins on the Dashboards access card.
-#   # It must be allowed to change security settings, which is much more than the logger needs - so it
-#   # is separate, and you can leave it out if you would rather make those logins by hand.
-#   admin:
-#     username: admin
-#     password: change-me
+# # The account that makes and removes the per-organization logins on the Dashboards access card.
+# # It must be allowed to change security settings, which is much more than the logger needs - so it
+# # is separate, and you can leave it out if you would rather make those logins by hand.
+# admin:
+#   username: admin
+#   password: change-me
 #
-#   # The address Dashboards on someone's own computer uses to reach OpenSearch: https, through
-#   # Apache (INSTALL-OPENSEARCH.md), never the port 9200 above.
-#   public: https://search.example.org
+# # The address Dashboards on someone's own computer uses to reach OpenSearch: https, through
+# # Apache (docs/INSTALL-OPENSEARCH.md), never the port 9200 above.
+# public: https://search.example.org

package/config.d/schema/modules.yaml

@@ -383,6 +383,13 @@ heatsink:
       name: Heatsink Temperature
       min: 0
       max: 120
+# Seeed HM3301 particulate sensor ("Grove - Laser PM2.5 Sensor") - Sensor_HM3301.
+hm3301:
+  name: "HM3301"
+  topics:
+    - leaf: pm1
+    - leaf: pm25
+    - leaf: pm10
 ht:
   name: HT
   topics:
@@ -617,6 +624,12 @@ sector:
     - leaf: valve
       leaf_from: controlouttoggle
       name: Valve
+# Nova Fitness SDS011 particulate sensor, as in sensor.community's airRohr - Sensor_SDS011.
+sds011:
+  name: "SDS011"
+  topics:
+    - leaf: pm25
+    - leaf: pm10
 sht:
   name: SHT
   topics:

package/config.d/schema/topics.yaml

@@ -549,6 +549,56 @@ percent:
     significantvalue: 1
   graphable:  true
   units:    "%"
+# Particulate matter, from the SDS011 or HM3301 - see sensor/pm.h in Frugal-IoT. Both are noisy,
+# and unreliable above ~70% humidity (they count droplets as particles). Only the HM3301 has pm1.
+pm1:
+  leaf:     pm1
+  name:     PM1.0
+  type:     float
+  display:  bar
+  min:      0
+  max:      100
+  width:    5
+  color:    "#d2691e"
+  units:    ug/m3
+  rw:       r
+  graphable:  true
+  log:      true
+  duplicates:
+    significantdate: 900000
+    significantvalue: 1
+pm10:
+  leaf:     pm10
+  name:     PM10
+  type:     float
+  display:  bar
+  min:      0
+  max:      200
+  width:    5
+  color:    "#696969"
+  units:    ug/m3
+  rw:       r
+  graphable:  true
+  log:      true
+  duplicates:
+    significantdate: 900000
+    significantvalue: 1
+pm25:
+  leaf:     pm25
+  name:     PM2.5
+  type:     float
+  display:  bar
+  min:      0
+  max:      100
+  width:    5
+  color:    "#a0522d"
+  units:    ug/m3
+  rw:       r
+  graphable:  true
+  log:      true
+  duplicates:
+    significantdate: 900000
+    significantvalue: 1
 position:
   leaf:     position
   name:     Position

package/{GRAFANA.md → docs/GRAFANA.md}

@@ -17,7 +17,31 @@ Grafana reads the server with its free **Infinity** plugin, which can call any U
 > Grafana's API), and the Grafana card on the dashboard clicked through by hand. Correct this page
 > where they differ.
 
+## Installing
+
+#### On a Mac, 
+
+```sh
+brew install grafana
+brew services start grafana
+```
+
+Open <http://localhost:3000>. Grafana's default login is `admin` / `admin`, and it asks you to change it.
+Then add the Infinity plugin - in Grafana, Administration → Plugins → "Infinity" - or from the shell:
+
+```sh
+/opt/homebrew/opt/grafana/bin/grafana cli --homepath /opt/homebrew/opt/grafana/share/grafana \
+  --pluginsDir /opt/homebrew/var/lib/grafana/plugins plugins install yesoreyeram-infinity-datasource
+brew services restart grafana
+```
+To stop it: `brew services stop grafana` (Homebrew restarts it at login until you do).
+
+#### On Windows, Linux and other systems
+
+For other systems, Grafana's own download page has installers for [Windows, Linux and others](https://grafana.com/grafana/download).
+
 ## Setting it up
+Access Grafana from your browser at [localhost:3000](http://localhost:3000)
 
 Anyone who can **read** the organization can make a token for themselves - you do not need to be an
 administrator. A token is yours: Grafana sees what *you* can see, so a token made by someone who can
@@ -26,22 +50,29 @@ read only one project shows that project only.
 1. **Install the Infinity plugin in Grafana.** In Grafana: Administration → Plugins, search for
    "Infinity", install it, and restart Grafana if it asks. (Installing Grafana itself is in
    [INSTALL-OPENSEARCH.md](INSTALL-OPENSEARCH.md).)
-2. **Make a token.** In the dashboard, open the project's back, then the **Grafana** card. Type a name
+2. **Make a token.** In the Frugal IoT dashboard, open the project's back, then the **Grafana** card. Type a name
    for this Grafana (so it can be revoked on its own later) and press *Make a token*. The token is shown
    **once** - only a hash is kept, so it cannot be looked up again. If you lose it, make one with the
    same name, which replaces it.
-3. **Give Grafana the data source.** Either press *Download the data source file* in the same place and
-   put it in Grafana's `provisioning/datasources` folder, then restart Grafana; or add it by hand in
+3. **Give Grafana the data source.** Either:
+   a: press *Download the data source file* in the same place and
+   put it in Grafana's `provisioning/datasources` folder (On a Mac typically in /opt/homebrew/Cellar/grafana/13.3.0/share/grafana/conf/provisioning),
+   then restart Grafana:
+   - On Mac: `brew services restart grafana`;
+   
+   or add it by hand in
    Grafana under Connections → Data sources → Add → **Infinity**:
    - Authentication: **Bearer Token**, with the token
    - Allowed hosts: the address you reached this dashboard at, e.g. `https://frugaliot.naturalinnovation.org`
-4. **Import the dashboard.** In the Grafana card press *Download the dashboard*. In Grafana choose
-   Dashboards → New → Import, upload the file, and pick the data source from step 3 when it asks.
+4. **Import the dashboard.** 
+  * On FrugalIoT: In the Grafana card press *Download the dashboard*. 
+  * Then in Grafana choose
+    Dashboards → New → Import, upload the file, and pick the data source from step 3 when it asks.
 
 The dashboard has a list of every topic at the top to choose from, and the time range at the top right.
 The file already has this server and organization filled in.
 
-A token lets one Grafana read **one organization**, read-only, and nothing else - and only the
+A token lets one Grafana read **one organization**, read-only - and only the
 projects of it that the person who made the token may read. For another
 organization, make its own token, data source and import - the dashboard file is separate for each, so
 importing a second does not replace the first. *Revoke* on the card cuts off a Grafana at once.