Docs updates, small changes

config_templates/base/mate_template_with_rpi_cpu_temperature.json

@@ -7,7 +7,7 @@
     "config/couchdb.json"
   ],
   "io": "../../config_templates/io/default_linux_serial.json",
-  "extra_option_flags": [
-    "rpi_cpu_temp"
+  "request": [
+    { "type": "rpi-cpu-temp" }
   ]
 }

config_templates/base/pvoutput_upload_template.json

@@ -2,6 +2,6 @@
   "type": "pvoutput-upload",
   "system_id": 100,
   "api_key": "<YOUR API KEY>",
-  "database": "config/couchdb.json",
+  "database": "../config/couchdb.json",
   "source": "default"
 }

config_templates/base/pvoutput_upload_template_advanced.json

@@ -1,10 +1,10 @@
 {
   "type": "pvoutput-upload",
-  "database": "../config/couchdb.json",
   "system_id": 100,
   "api_key": "<API KEY>",
-  "time_zone": "US/Mountain",
+  "database": "../config/couchdb.json",
   "source": "default",
+  "time_zone": "US/Mountain",
   "default_fragment": 1,
   "include_undefined_sources": true,
   "required": {
@@ -14,5 +14,8 @@
   "voltage_identifier": {
     "fragment": 1,
     "identifier": "OutbackIdentifier(address=3)"
+  },
+  "temperature_identifier": {
+    "fragment": 3, "identifier": "DataIdentifier(dataId=1)"
   }
 }

config_templates/base/request_template.json

@@ -1,7 +1,7 @@
 {
   "type": "request",
   "source": "default",
-  "fragment": 2,
+  "fragment": 3,
   "unique": 30,
   "databases": [
     "config/couchdb.json"

config_templates/graphql/application.properties

@@ -1,3 +1 @@
 solarthing.config.database=../config/couchdb/couchdb.json
-solarthing.config.default_source=default
-solarthing.config.default_fragment=1

config_templates/graphql/application_advanced.properties

@@ -0,0 +1,3 @@
+solarthing.config.database=../config/couchdb/couchdb.json
+solarthing.config.default_source=default
+solarthing.config.default_fragment=1

core/src/main/java/me/retrodaredevil/solarthing/packets/collection/DefaultInstanceOptions.java

@@ -11,7 +11,7 @@ public final class DefaultInstanceOptions {
 	private final String defaultSourceId;
 	private final int defaultFragmentId;
 
-	public DefaultInstanceOptions(String defaultSourceId, int defaultFragmentId) {
+	public DefaultInstanceOptions(@NotNull String defaultSourceId, int defaultFragmentId) {
 		requireNonNull(this.defaultSourceId = defaultSourceId);
 		this.defaultFragmentId = defaultFragmentId;
 	}

graphql/grafana_datasource_setup.md

@@ -4,8 +4,10 @@ You can install https://github.com/fifemon/graphql-datasource by cloning it in `
 You will need to be a member of the `grafana` group to access that directory.
 
 ```shell script
-sudo usermod -a -G grafana josh
+sudo usermod -a -G grafana $USER
+# Now log out and log back in, or
 exec su -l $USER # if you're too lazy to log out and back in
+
 cd /var/lib/grafana/plugins
 git clone https://github.com/fifemon/graphql-datasource
 ```

graphql/src/main/java/me/retrodaredevil/solarthing/graphql/GraphQLProvider.java

@@ -11,10 +11,12 @@
 import me.retrodaredevil.couchdb.CouchProperties;
 import me.retrodaredevil.solarthing.SolarThingConstants;
 import me.retrodaredevil.solarthing.annotations.NotNull;
+import me.retrodaredevil.solarthing.annotations.Nullable;
 import me.retrodaredevil.solarthing.config.databases.DatabaseSettings;
 import me.retrodaredevil.solarthing.config.databases.implementations.CouchDbDatabaseSettings;
 import me.retrodaredevil.solarthing.meta.DefaultMetaDatabase;
 import me.retrodaredevil.solarthing.packets.collection.DefaultInstanceOptions;
+import me.retrodaredevil.solarthing.packets.instance.InstanceSourcePacket;
 import me.retrodaredevil.solarthing.program.DatabaseConfig;
 import me.retrodaredevil.solarthing.util.JacksonUtil;
 import org.ektorp.impl.StdCouchDbConnector;
@@ -36,13 +38,21 @@ public class GraphQLProvider {
 
 	@Value("${solarthing.config.database}")
 	private File databaseFile;
-	@Value("${solarthing.config.default_source:default}")
-	private String defaultSourceId;
+	@Value("${solarthing.config.default_source:#{null}}")
+	private @Nullable String defaultSourceId;
 	@Value("${solarthing.config.default_fragment:#{null}}")
-	private Integer defaultFragmentId;
+	private @Nullable Integer defaultFragmentId;
 
 	private GraphQL graphQL;
 
+	private String getDefaultSourceId() {
+		String r = defaultSourceId;
+		if (r == null) {
+			return InstanceSourcePacket.UNUSED_SOURCE_ID;
+		}
+		return r;
+	}
+
 	private int getDefaultFragmentId() {
 		Integer r = defaultFragmentId;
 		if (r == null) {
@@ -97,7 +107,7 @@ public void init() {
 		}
 		CouchDbDatabaseSettings couchDbDatabaseSettings = (CouchDbDatabaseSettings) databaseSettings;
 
-		DefaultInstanceOptions defaultInstanceOptions = new DefaultInstanceOptions(defaultSourceId, getDefaultFragmentId());
+		DefaultInstanceOptions defaultInstanceOptions = new DefaultInstanceOptions(getDefaultSourceId(), getDefaultFragmentId());
 		System.out.println("Using defaultInstanceOptions=" + defaultInstanceOptions);
 		GraphQLSchema schema = createGraphQLSchemaGenerator(objectMapper, couchDbDatabaseSettings.getCouchProperties(), defaultInstanceOptions).generate();
 

other/docs/quickstart_graphql.md

@@ -1,2 +1,27 @@
 # GraphQL Quickstart
-Documentation to come
+If you haven't already, [click here](quickstart.md) to view how to clone this repo and install the service.
+
+Note that you must have set up either the `mate`, `rover`, or `request` program for this to be useful.
+This program is used to expose CouchDB as a GraphQL API, which is commonly used with Grafana and [the GraphQL Datasource](https://github.com/fifemon/graphql-datasource).
+
+Once everything is installed, you're ready to edit the configs. You will cd to the `program/mate` directory.
+```
+cd /opt/solarthing/program/graphql
+```
+
+Now copy the `application.properties` to the config directory:
+```shell script
+cp ../../config_templates/graphql/application.properties config/
+```
+
+Edit `application.properties`:
+```
+solarthing.config.database=../config/couchdb/couchdb.json
+```
+Make sure the path to your `couchdb.json` is correct.
+
+### Run for the first time
+Run `./run.sh`.
+
+### [Set up with Grafana](../../graphql/grafana_datasource_setup.md)
+

other/docs/quickstart_pvoutput.md

@@ -29,6 +29,40 @@ up your output at https://pvoutput.org. `source` is the source id of the data an
 
 This requires that you set up an account on https://pvoutput.org. This also requires you to set up a CouchDB database.
 
+#### Advanced Configuration
+You can view an advanced configuration [here](../../config_templates/base/pvoutput_upload_template_advanced.json).
+
+```json5
+{
+  // ...
+  "time_zone": "US/Mountain",
+  "default_fragment": 1,
+  "include_undefined_sources": true,
+  "required": {
+    "1": ["OutbackIdentifier(address=3)", "OutbackIdentifier(address=4)"]
+  },
+  "analytics_enabled": true,
+  "voltage_identifier": {
+    "fragment": 1,
+    "identifier": "OutbackIdentifier(address=3)"
+  },
+  "temperature_identifier": {
+    "fragment": 3, "identifier": "DataIdentifier(dataId=1)"
+  }
+}
+```
+* `time_zone` can be used to set the time zone if you want to use a different time zone than the current system time zone.
+* `default_fragment` usually should never be defined. It's only for users who've been using SolarThing since before 2020.
+* `include_undefined_sources` usually should never be defined. It's only for users who've been using SolarThing since before 2020.
+* `required` can be used to make sure that certain data is present before uploading to PVOutput
+  * In this case, two outback devices with addresses of 3 and 4 must be present. Both of these devices are being monitored by
+  a device with a fragment ID of 1.
+* `analytics_enabled` can be set to false to disable Google Analytics
+* `voltage_identifier` can be used to upload voltage data to PVOutput.
+  * In this case, an MX device with an address of 3 on fragment 1 will be used for its `inputVoltage` (pv voltage).
+* `temperature_identifier` can be used to upload temperature data to PVOutput.
+  * In this case, a DS18B20 sensor on fragment 3 with a data ID of 1 is used
+
 
 ### I'm ready to use this for real!
 Once your configuration is how you want it, you can go back to the [quickstart](quickstart.md#configuration-continued) to enable and start the service.
@@ -40,4 +74,5 @@ This project is set up this way because it makes future changes easier. If you w
 this project such as fragmented packets, the only way to upload all of your data to pvoutput would be to do it
 in one program instead of two.
 
-
+This means that you can have multiple instances of SolarThing running and compile data from
+each program and upload to PVOutput all at once.

other/docs/quickstart_request.md

@@ -1,2 +1,44 @@
 # Quick start with Request program
-Documentation to come
+If you haven't already, [click here](quickstart.md) to view how to clone this repo and install the service.
+
+The request program can be used for uploading temperature sensor data and Raspberry Pi
+CPU Temperature.
+
+This supports DS18B20 temperature sensors.
+
+Once everything is installed, you're ready to edit the configs. You will cd to the `program/mate` directory.
+```
+cd /opt/solarthing/program/request
+```
+
+Copy the request template:
+```shell script
+cp ../../config_templates/base/request_template.json config/base.json
+```
+
+Now edit `config/base.json`.
+```json
+{
+  "type": "request",
+  "source": "default",
+  "fragment": 3,
+  "unique": 30,
+  "databases": [
+    "../config/couchdb.json"
+  ],
+  "request": [
+    {
+      "type": "rpi-cpu-temp"
+    },
+    {
+      "type": "w1-temperature",
+      "directory": "/sys/bus/w1/devices/28-000006470bec",
+      "data_id": 1
+    }
+  ]
+}
+```
+The objects in the `request` field represent what values are uploaded.
+
+If you are monitoring a DS18B20 temperature sensor, you can change the `directory` field to point to
+the correct device in `/sys/bus/w1/devices`. Also learn [how to set up a DS18B20 sensor](DS18B20_sensor_setup.md).

other/docs/raspberry_pi_cpu_temperature.md

@@ -10,6 +10,8 @@ as a packet. You just have to add this json to your `base.json`:
 }
 ```
 
+Learn more about the `request` field [here](request_field.md).
+
 This works by using the `vcgencmd measure_temp` that is only available on Raspberry Pis
 
 You can see an example [here](../../config_templates/base/mate_template_with_rpi_cpu_temperature.json)

other/docs/request_field.md

@@ -0,0 +1,37 @@
+# Request Field
+The `request` field is an array of objects that *can* be present in configurations for the
+`mate`, `rover`, or `request` programs.
+
+This is a common way to define what to upload to the database. In the `mate` and `rover` program case, it supplements
+the data they already provide.
+
+
+Here's an example of requesting the Raspberry Pi CPU Temperature
+```json5
+{
+  // ...
+  "request": [
+    {
+      "type": "rpi-cpu-temp"
+    }
+  ]
+}
+```
+
+You can also request data from a DS18B20 temperature sensor:
+```json5
+{
+  // ...
+  "request": [
+    {
+      "type": "rpi-cpu-temp"
+    },
+    {
+      "type": "w1-temperature",
+      "directory": "/sys/bus/w1/devices/28-000006470bec",
+      "data_id": 1
+    }
+  ]
+}
+```
+If you are interesting in learning more about the DS18B20 sensor, [click here](DS18B20_sensor_setup.md).