Merge pull request #28 from NeedleInAJayStack/doc/urls

Documentation Improvements

Author: NeedleInAJayStack

.gitignore

@@ -35,4 +35,7 @@ e2e-results/
 pkg/.env
 
 # Private plugin releases
-release/
+release/
+
+# MacOS artifacts
+.DS_Store

src/README.md

@@ -2,25 +2,40 @@
 
 This is a [Grafana](https://grafana.com/grafana/) data source plugin that supports direct communication with a
 [Project Haystack API Server](https://project-haystack.org/doc/docHaystack/HttpApi). It handles authentication
-and supports standard Haystack API operations as well as custom Axon execution, which is supported by
-[SkySpark](https://skyfoundry.com/product) and [Haxall](https://haxall.io/).
+and supports standard Haystack API operations as well as custom Axon execution.
+
+Some popular servers with Haystack APIs are:
+
+- [SkySpark](https://skyfoundry.com/product)
+- [Tridium Niagara](https://www.tridium.com/us/en/Products/niagara) (via [NHaystack](https://github.com/ci-richard-mcelhinney/nhaystack))
+- [Siemens Desigo Optic](https://www.siemens.com/us/en/products/buildingtechnologies/automation/desigo-optic.html)
+- [Fin Framework](https://www.j2inn.com/finframework)
+- [Haxall](https://haxall.io/)
+- [WideSky Cloud](https://widesky.cloud/products/widesky-cloud/)
 
 ## Usage
 
 ### Create a Data Source
 
-To create a new data source, select `Data Sources` from the Configuration menu represented by the gear icon on the left
-panel. Click `Add Data Source`, and then select `Haystack` from the list. Next, fill in the name of the data source,
-the API URL, and the credentials to use to access the data. It is typically a good idea to create a dedicated user
-to access the data. Once complete, select `Save & Test`. If you get a green check mark, the connection was successful!
+Follow the [Grafana instructions](https://grafana.com/docs/grafana/latest/administration/data-source-management/#add-a-data-source)
+to create a new Haystack datasource. Next, fill in the required information:
+
+- The name of the data source.
+- The root Haystack API URL. The URLs for some popular Haystack servers are listed below:
+  - SkySpark: `http://<host>/api/<proj>/`
+  - Haxall: `http://<host>/api/`
+  - NHaystack: `http://<host>/`
+- The username and password. It is best practice to create a dedicated user for the Grafana integration.
+
+Once complete, select `Save & Test`. If you get a green check mark, the connection was successful!
 
 ### Query Data
 
-To query data from the data source, create a new panel in a dashboard. If you do not have any dashboards yet, create
-one by selecting `+ New Dashboard` from the Dashboard menu in the left panel.
+To query data from the data source, [create a dashboard](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/create-dashboard/)
+and add a new panel.
 
-Once within the panel editor, select your Haystack data source in the Data Sources menu. Next, select the type of
-Haystack query that should be performed. The supported queries are:
+Select your Haystack data source in the Data Sources menu. Next, select the type of Haystack query that should be
+performed (only queries supported by your data source are shown):
 
 - Eval: Evaluate a free-form Axon expression. _Note: Not all Haystack servers support this functionality_
 - HisRead: Display the history of a single point over the selected time range.
@@ -30,9 +45,11 @@ Haystack query that should be performed. The supported queries are:
 
 #### Variable Usage
 
-Grafana template variables can be injected into queries using the ordinary syntax, e.g. `$varName`.
+[Grafana variables](https://grafana.com/docs/grafana/latest/dashboards/variables/) can be injected into Haystack queries
+using the [ordinary syntax](https://grafana.com/docs/grafana/latest/dashboards/variables/variable-syntax/),
+e.g. `$varName`.
 
-We also support injecting a few special variables from the time-range selector into the Eval and Read requests:
+We also support a few special variables from the selected time-range:
 
 - `$__timeRange_start`: DateTime start of the selected Grafana time range
 - `$__timeRange_end`: DateTime end of the selected Grafana time range
@@ -43,13 +60,13 @@ We also support injecting a few special variables from the time-range selector i
 To use them, simply enter the value in the input string. Below is an example of using the variables in an Eval query:
 
 ```
-> [{ts: $__timeRange_start, v0: 0}, {ts: $__timeRange_end, v0: 10}].toGrid
+> read(temp).hisRead($__timeRange_start..$__timeRange_end).hisInterpolate()
 ```
 
 ### Query Variables
 
-You can use the Haystack connector to source variables. Create a query and then enter the column that contains the
-variable values. If no column is specified, the first one is used.
+You can use the Haystack connector to source new variables. Create a query and then enter the name of the column that
+contains the variable values. If no column is specified, the first one is used.
 
 The value injected by the variable exactly matches the displayed value, with the exception of Ref types, where the
 injected value is only the ID portion (i.e. the dis name is not included in the interpolation). Multiple-select values

src/img/screenshot/dashboard.png

@@ -20,8 +20,12 @@
     "links": [],
     "screenshots": [
       {
-        "name": "Dashboard",
-        "path": "img/screenshot/dashboard.png"
+        "name": "Dashboard 1",
+        "path": "img/screenshot/dashboard_1.png"
+      },
+      {
+        "name": "Dashboard 2",
+        "path": "img/screenshot/dashboard_2.png"
       },
       {
         "name": "Query Editor",