diff --git a/readme b/README.md similarity index 65% rename from readme rename to README.md index 653c1fb..77f0143 100644 --- a/readme +++ b/README.md @@ -2,46 +2,39 @@ influx - weewx extension that sends data to an influx data server Copyright 2016-2021 Matthew Wall Distributed under terms of the GPLv3 -=============================================================================== -Installation +# Installation -1) download +1. Download: + `wget -O weewx-influx.zip https://github.com/matthewwall/weewx-influx/archive/master.zip` -wget -O weewx-influx.zip https://github.com/matthewwall/weewx-influx/archive/master.zip +2. Run the installer: + `wee_extension --install weewx-influx.zip` -2) run the installer: +3. Enter parameters in `weewx.conf`: + ``` + [StdRESTful] + [[Influx]] + host = HOSTNAME + database = DATABASE + ``` +4. Restart weewx: + ```bash + sudo /etc/init.d/weewx stop + sudo /etc/init.d/weewx start + ``` -wee_extension --install weewx-influx.zip +# Configuration -3) enter parameters in weewx.conf: +A minimal configuration requires only a host and database. +Use `host` and `port`, or `server_url` to specify the influx server. +A username and password are required if authentication is enabled on the influx server. -[StdRESTful] - [[Influx]] - host = HOSTNAME - database = DATABASE - -4) restart weewx: - -sudo /etc/init.d/weewx stop -sudo /etc/init.d/weewx start - - -=============================================================================== -Configuration +When it starts up, this extension will attempt to create the influx database. If credentials for a database administrator were provided, it will use those credentials. +Otherwise, it will use the username/password credentials. -A minimal configuration requires only a host and database. - -Use host and port, or server_url to specify the influx server. - -A username and password are required if authentication is enabled on the -influx server. - -When it starts up, this extension will attempt to create the influx database. -If credentials for a database administrator were provided, it will use those -credentials. Otherwise, it will use the username/password credentials. - -Here is a complete enumeration of options. Specify only those that you need. +Here is a complete enumeration of options. Specify only those that you need. +``` [StdRESTful] [[Influx]] database = DATABASE @@ -69,61 +62,76 @@ Here is a complete enumeration of options. Specify only those that you need. units = degree_F # optional for each obs name = label # optional for each obs format = %.2f # optional for each obs +``` +# Line formats -=============================================================================== -Line formats - -Influx defines two line formats, multi-line and single-line. This extension -defines the following formats: single-line, multi-line, and multi-line-dotted. -These correspond to the influx line formats. The 'measurement' parameter is -used to identify the values sent to influx. +Influx defines two line formats, multi-line and single-line. +This extension defines the following formats: `single-line`, `multi-line`, and `multi-line-dotted`. +These correspond to the influx line formats. +The `measurement` parameter is used to identify the values sent to influx. +``` [StdRESTful] [[Influx]] measurement = weewx line_format = multi-line +``` + +The `single-line` format results in the following: -The single-line format results in the following: +``` +weewx[tags] name0=x,name1=y,name2=z ts +``` - weewx[tags] name0=x,name1=y,name2=z ts +The `multi-line` format results in the following: -The multi-line format results in the following: +``` +name0[tags] value=x ts +name1[tags] value=y ts +name2[tags] value=z ts +``` - name0[tags] value=x ts - name1[tags] value=y ts - name2[tags] value=z ts +The `multi-line-dotted` format results in the following: -The multi-line-dotted format results in the following: +``` +weewx.name0[tags] value=x ts +weewx.name1[tags] value=x ts +weewx.name2[tags] value=x ts +``` - weewx.name0[tags] value=x ts - weewx.name1[tags] value=x ts - weewx.name2[tags] value=x ts +## Which format should you use? -Which format should you use? It depends on how you want the data to end up in -influx. For influx, think of measurement name as table, tags as column names, +It depends on how you want the data to end up in +influx. +For influx, think of measurement name as table, tags as column names, and fields as unindexed columns. For example, consider these data points: +```json {'H19': 528, 'VPV': 63.68, 'I': 600, 'H21': 115, 'H20': 19, 'H23': 93, 'H22': 23, 'V': 13.41, 'CS': 5, 'PPV': 9} {'H19': 528, 'VPV': 63.68, 'I': 600, 'H21': 115, 'H20': 19, 'H23': 93, 'H22': 23, 'V': 14.43, 'CS': 5, 'PPV': 9} {'H19': 528, 'VPV': 63.71, 'I': 600, 'H21': 115, 'H20': 19, 'H23': 93, 'H22': 23, 'V': 13.43, 'CS': 5, 'PPV': 9} {'H19': 528, 'VPV': 63.74, 'I': 600, 'H21': 115, 'H20': 19, 'H23': 93, 'H22': 23, 'V': 13.43, 'CS': 5, 'PPV': 9} +``` A single-line configuration results in this: +``` > select * from value name: value time CS H19 H20 H21 H22 H23 I PPV V VPV binding ---- -- --- --- --- --- --- - --- - --- ------- -1536086335000000000 5 528 19 115 23 93 0.6 9 13.41 63.68 loop -1536086337000000000 5 528 19 115 23 93 0.6 9 13.43 63.68 loop -1536086339000000000 5 528 19 115 23 93 0.6 9 13.43 63.71 loop -1536086341000000000 5 528 19 115 23 93 0.6 9 13.43 63.74 loop +1536086335000000000 5 528 19 115 23 93 0.6 9 13.41 63.68 loop +1536086337000000000 5 528 19 115 23 93 0.6 9 13.43 63.68 loop +1536086339000000000 5 528 19 115 23 93 0.6 9 13.43 63.71 loop +1536086341000000000 5 528 19 115 23 93 0.6 9 13.43 63.74 loop +``` A multi-line configuration results in this: +``` > select * from VPV name: value time VPV @@ -132,15 +140,14 @@ time VPV 1536086337000000000 63.68 1536086339000000000 63.71 1536086341000000000 63.74 +``` +# Input map -=============================================================================== -Input map - -When an input map is specified, only variables in that map will be uploaded. -The 'units' parameter can be used to specify which units should be used for -the input, independent of the local weewx units. +When an input map is specified, only variables in that map will be uploaded. +The `units` parameter can be used to specify which units should be used for the input, independent of the local weewx units. +``` [StdRESTful] [[Influx]] database = DATABASE @@ -165,3 +172,4 @@ the input, independent of the local weewx units. format = %.2f [[[[windDir]]]] format = %03.0f +```