[Config]
LOX_IP = # Loxone-IP or broadcast-address to send data to
LOX_PORT = 12340 # Loxone-Port - port to send data to
LB_IP = # Loxberry-IP
LINK_ADR = # use the specified IP address or a server name instead of the local IP address in links (when operating on a public server)
LBU_PORT = 12341 # Loxberry-Port - port to receive UDP-datagrams
LBH_PORT = # Loxberry-Port - port to receive HTML-in & out
LOX_TIME = True # adjust time base to 01.01.2009 (Loxone only)
USE_METRIC = True # use metric instead of imperial values
IGNORE_EMPTY = True # do not send -9999 or empty values
UDP_ENABLE = True # set to False to disable UDP-sending
UDP_IGNORE = # comma-separated list of fields to not send via UDP
UDP_MAXLEN = # defines the length of a UDP datagram before deviding to several datagrams (default 2000)
UDP_STATRESEND = 0 # cycle sending of warnings via UDP in seconds
LANGUAGE = DE # remove or adjust to EN to use english output for wprogtxt and wnowtxt (or NL/SK/FR/ES)
AUTH_PWD = # if set, only incoming & outgoing http-requests containing this passphrase will be accepted
DEF_SID = # override the default identifier for outgoing UDP datagrams (default: FOSHKweather)
REBOOT_ENABLE = False # enable remote reboot of weather station via UDP and http (default: False - danger!)
RESTART_ENABLE = False # enable restarting FOSHKplugin via UDP and http (default: False - danger!)
DT_FORMAT = %d.%m.%Y %H:%M:%S # global default for date/time format (default: %d.%m.%Y %H:%M:%S - dd.mm.yyyy hh:mm:ss)
RUN_DESC = # string is output as additional information in push notifications (behind the IP address) and for internal html pages help, banner, fwdstat, keyhelp, scanWS in the headline
[Weatherstation]
WS_IP = # IP-address of weather station
WS_PORT = # UDP-port of weather station
WS_INTERVAL = 60 # weather station will send data every n seconds (16..3600)
WS90_CONVERT = True # automatically convert WS90 rain data keys to conventional rain sensor keys if only these WS90 rain values are present (globally)
[Export]
EVAL_VALUES = True # calculate some extra values on base of current data (dew point, windchill, heatIndex, feelsliketemp, AQI, ...)
ADD_ITEMS = # additional fixed strings to append to every raw-data-line
ADD_DEWPT = False # enable/disable additional dew point calculation (indoor sensor, WH31, WH45) - default: False; set to True to enable
ADD_SPREAD = False # enable/disable additional spread calculation (indoor & outdoor sensor, WH31, WH45) - default: False; set to True to enable
ADD_VPD = False # enable/disable additional VPD calculation (indoor & outdoor sensor, WH31 and WH45/46 - default: False; set to True to enable
ADD_SIGNAL = False # enable/disable signal quality acquisition on supported consoles - default: False; set to True to enable
OUT_TEMP = # fake the temperature-value for outdoor-sensor with value of specific indoor-sensor e.g. temp1f
OUT_HUM = # fake the humidity-value for outdoor-sensor with value of specific indoor-sensor e.g. humidity1
OUT_TIME = False # exchange incoming time string with time of receiving
FIX_LIGHTNING = True # use last known lightning data as raw data in case of empty values
UDP_MINMAX = True # send min/max values and their occurence via UDP
URL_REPAIR = True # automatically inserts a missing but required "http://" into the FWD_URL (default: True)
LIMIT_WINDGUST = # limit from which windgustmph and maxdailygust are blocked for any further processing to prevent unrealistic values (e.g. WS80/WS90).
ADD_SCRIPT = # script to globally integrate data from third party devices - see https://foshkplugin.phantasoft.de/generic#script
[Forward]
FWD_ENABLE = True # to deactivate this forward temporarily just set to False instead of deleting the URL (default: True)
FWD_CMT = This is a permanent comment field for notes on this forward
FWD_URL = # URL of destination
FWD_INTERVAL = # interval in seconds in which lines will be forwarded
FWD_IGNORE = # comma-separated list of fields to not forward
FWD_TYPE = # WU/UDP/LD/RAW/EW/RAWEW/RAWUDP/AMB/RAWAMB/WC/MT/AWEKAS/WETTERCOM/WEATHER365/REALTIMETXT/CLIENTRAWTXT/CSVFILE/TXTFILE/WETTERSEKTOR/MQTTMET/MQTTIMP/WSWIN/RAWTEXT/EWUDP/APRS/INFLUXMET/INFLUXIMP/INFLUX2MET/INFLUX2IMP/MIYO/BANNER/TAGFILE
# WU: WU-format
# UDP: UDP-String will be forwarded (default)
# LD: PM2.5 luftdaten.info
# EW: Ecowitt-format
# RAWEW: Ecowitt untouched
# RAW: as input
# RAWUDP: RAW via UDP
# AMB: Ambient-format
# RAWAMB: Ambient untouched
# WC: Weathercloud-format
# MT: Meteotemplate-format
# AWEKAS: Awekas API format
# WETTERCOM: wetter.com API format
# WEATHER365: weather365.net API format
# REALTIMETXT: export as realtime.txt
# CLIENTRAWTXT: export as clientraw.txt
# CSVFILE: export every single record via http(s)/POST, ftp(s) or save as a file in the filesystem
# TXTFILE: export every single record via http(s)/POST, ftp(s) or save as a file in the filesystem
# WETTERSEKTOR: Wettersektor-format
# MQTTMET: metric values to MQTT
# MQTTIMP: imperial values to MQTT
# WSWIN: export as WSWin compatible CSV file
# RAWTEXT: export every single imperial record via http(s)/POST, ftp(s) or save as a file in the filesystem
# EWUDP: forward (converted) incoming data to Ecowitt and forward via UDP
# APRS: forward in APRS protocol
# INFLUXMET: forward metric values to InfluxDB
# INFLUXIMP: forward imperial values to InfluxDB
# INFLUX2MET: forward metric values to InfluxDB2
# INFLUX2IMP: forward imperial values to InfluxDB2
# MIYO: forward temperature, wind and rain state to a MIYO cube (irrigation system)
# BANNER: save banner/sticker image with embedded weather data in the filesystem (and upload via ftp(s) or http(s)/POST)
# TAGFILE: user-defined output format based on tags and templates
FWD_OPTION = # specific forward options - e.g. to define the file with the banner definition: bannerconfig=/path/to/configfile or blacklist=False to send the additional values for spread and signal quality also in Ecowitt format for this specific forward
FWD_SID = # username for forward if necessary (SensorID for luftdaten.info)
FWD_PWD = # password for this forward if necessary
FWD_REMAP = # comma-separated list of fields to remap with values (from other keys): @targetkey=@sourcekey or targetkey=static value
FWD_STATUS = False # FWD_TYPE=UDP only: if set to True attach current status on each outgoing datagram (default: False)
FWD_MQTTCYCLE = 0 # FWD_TYPE MQTTMET/MQTTIMP only: time in minutes to send the complete record while otherwise only the changes are sent (default: 0 - send everytime the complete record)
FWD_EXEC = # external script to be started immediately before sending, last line of the script's output is used as the new outstr for sending
FWD_WARNINT = 10 # threshold of unsuccessful forward attempts before warning
FWD_QUEUE = # type of file to save to if forward target can not be connected: NONE, INFLUX, AWEKAS, CMX, EW
FWD_QDIR = # dircetory to save the queued file(s)
# you additionally can use Forward-1..99
[Forward-1]
FWD_ENABLE = True # to deactivate this forward temporarily just set to False instead of deleting the URL (default: True)
FWD_CMT = This is a permanent comment field for notes on this forward
FWD_URL = # URL of destination
FWD_INTERVAL = # interval in seconds in which lines will be forwarded
FWD_IGNORE = # comma-separated list of fields to not forward
FWD_TYPE = # WU/UDP/LD/RAW/EW/RAWEW/RAWUDP/AMB/RAWAMB/WC/MT/AWEKAS/WETTERCOM/WEATHER365/REALTIMETXT/CLIENTRAWTXT/CSVFILE/TXTFILE/WETTERSEKTOR/MQTTMET/MQTTIMP/WSWIN/RAWTEXT/EWUDP/APRS/INFLUXMET/INFLUXIMP/INFLUX2MET/INFLUX2IMP/MIYO/BANNER/TAGFILE
FWD_OPTION = # specific forward options - e.g. to define the file with the banner definition: bannerconfig=/path/to/configfile or blacklist=False to send the additional values for spread and signal quality also in Ecowitt format for this specific forward
FWD_SID = # username for forward if necessary (SensorID for luftdaten.info)
FWD_PWD = # password for this forward if necessary
FWD_REMAP = # comma-separated list of fields to remap with values (from other keys): @targetkey=@sourcekey or targetkey=static value
FWD_STATUS = False # if set to True attach current status on each outgoing datagram if applicable (default: False)
FWD_MQTTCYCLE = 0 # FWD_TYPE MQTTMET/MQTTIMP only: time in minutes to send the complete record while otherwise only the changes are sent (default: 0 - send everytime the complete record)
FWD_EXEC = # external script to be started immediately before sending, last line of the script's output is used as the new outstr for sending
FWD_WARNINT = 10 # threshold of unsuccessful forward attempts before warning
FWD_QUEUE = # type of file to save to if forward target can not be connected: NONE, INFLUX, AWEKAS, CMX, EW
FWD_QDIR = # directory to save the queued file(s)
[CSV]
CSV_NAME = # file name for csv-file (always metric!)
CSV_FIELDS = # fields in desired order, separated with ; or ,
CSV_INTERVAL = # interval in seconds in which lines are written to the csv-file
CSV_DAYFILE = # file name for CSV-dayfile with min/max values of each last day (will be appended every day after midnight)
[Warning]
WSDOG_WARNING = True # warn if weather station did not report data within n send-intervals
WSDOG_INTERVAL = 3 # checking interval for WSDOG_WARNING
WSDOG_RESTART = 0 # automatically restart FOSHKplugin on n send-intervals without data from weatherstation
SENSOR_WARNING = False # warn on missing sensor data
SENSOR_MANDATORY = wh65batt # a comma-separated list of all mandatory sensors
BATTERY_WARNING = True # warn if battery level of known sensors is critical
BATTERY_WARNEXCLUDE = # comma-separated list of keys to exclude from battery warning e.g. wh90batt
STORM_WARNING = True # activate storm warning based on a change in air pressure
STORM_WARNDIFF = 1.75 # change of air pressure in hPa within one hour to get warning state
STORM_WARNDIFF3H = 3.75 # change of air pressure in hPa within three hours to get warning state
STORM_EXPIRE = 60 # minutes, warning will stay active since last over- and under-range indication
TSTORM_WARNING = True # enable thunderstorm warning (needs WH57 lightning sensor)
TSTORM_WARNCOUNT= 1 # warn if more than n lightnings were detected
TSTORM_WARNDIST = 30 # warn only if lightning is closer than n km
TSTORM_EXPIRE = 15 # minutes, warning will stay active since last lightning
LEAKAGE_WARNING = False # warn if leakage detected on any WH55
CO2_WARNING = False # warn if co2 ppm exceeds CO2_WARNLEVEL
CO2_WARNLEVEL = 1000 # ppm threshold to trigger the co2 warning
INTVL_WARNING = False # warn if receive interval not correspond to send interval
INTVL_PCT = 10 # percentage value of the max. permissible exceeding of the send interval (default: 10)
REBOOT_WARNING = True # check if current station runtime < last runtime and warn (log, pushover)
FWD_WARNING = True # warn after n (defined by FWD_WARNINT) consecutive failed forward attempts (default: true)
FWD_WARNINT = 10 # Number of failed forward attempts until a warning occurs (default: 10)
[Logging]
LOG_ENABLE = True # switch logging on and off globally (default: True)
LOG_LEVEL = ALL # with each log level fewer messages will be logged: ALL, INFO, WARNING, ERROR - a lower level includes the higher ones
IGNORE_LOG = # a comma-separated list of (sub)strings which will prevent logging a line containing these strings in standard-log
BUT_PRINT = True # respect IGNORE_LOG also for outputs on the console (default: True)
COLOR_PRINT = True # use colour highlighting of messages in the console window (ERROR = red, WARNING = yellow and after a warning has been cancelled = green; default: True - can be deactivated with COLOR_PRINT = False
logfile = REPLACEFOSHKPLUGINLOGDIR/log-foshkplugin.log # default log - all start/stop/warn/error messages
rawfile = REPLACEFOSHKPLUGINLOGDIR/raw-foshkplugin.log # logs raw messages coming from weather station only
sndfile = REPLACEFOSHKPLUGINLOGDIR/snd-foshkplugin.log # logs outgoing messages from plugin (CSV, UDP, FWD)
[Update]
UPD_CHECK = True # enable/disable firmware-update-check for weatherstation
UPD_INTERVAL = 86400 # interval in seconds of checking for firmware-updates
[Pushover]
PO_ENABLE = False # enable/disable push notification via Pushover (default: False)
PO_URL = # keep empty to use the standard API-URL
PO_TOKEN = # generated API-Token from "Your Applications" at Pushover-Dashboard
PO_USER = # the user key shown at "Your User Key" at Pushover-Dashboard
PO_CUSTOMWARNING = True # enable/disable user-defined push messages when values meet a definable condition (100 rules - default: True)
PO_CUSTOM = @tempc <= 2.5,Current temperature (@value°C) is equal or below 2.5°C!,False,3600
PO_CUSTOM1 = @tempf < 32,Current temperature (@value°F) is below 32°F!,False,3600
[Coordinates]
# coordinates are only needed for calculating cloudbase or export to Awekas-API, clientraw.txt, Weather365.net
ALT = # altitude in m e.g. 53
LAT = # latitude in dec. grad e.g. 52.668759; North of the equator has no sign. South of the equator has a - sign.
LON = # longitude in dec. grad e.g. 13.266274; for longitudes left of Greenwich a - sign is needed.
[Sunduration]
SUN_CALC = False # enable for better sunhours calculation (LAT, LON needed), disable to use static threshold of 120W/m²
SUN_MIN = 0 # from this value (W/m²) calculation starts
SUN_COEF = 0.92 # adjustment factor also depends on the location
SUNSHINE_HOLD = 0 # Hold time in seconds for value sunshine, this time continues to be output sunshine = True, even if there is no sunshine (default: 0)
#! /bin/bash
# several data formats available: CSV, UDP, RAW, STRING, JSON, WU
# metric/imperial and separator are selectable
FMT=STRING&crondaemon
IP=192.168.15.236
PORT=8080
URL=http://$IP:$PORT/$FMT
payload=`curl -s $URL`
# do what you want with station data
echo $payload
For example, to start this script every 30 seconds, simply set up two entries in cron:
* * * * * /opt/FOSHKplugin/cronjob.sh
* * * * * sleep 30; /opt/FOSHKplugin/cronjob.sh
\\
++++
----
{{anchor:mqtt}}
++++ Forwarding of the station data to an MQTT broker |
**Forwarding of the station data to an MQTT broker**
With v0.08, the script-controlled way to send the data is no longer necessary - FOSHKplugin can forward the data directly to an MQTT server.\\ Both the metric and the imperial values (and names) can be transferred in 2 separate forwards. The forward to different brokers - also in different formats is possible - you then have to set up separate forwards.\\ FWD_EXEC can be used to intercept the data to be sent to the MQTT broker by any script right BEFORE sending. If necessary, the output data could be modified there. The last output line of the script is then taken by FOSHKplugin as the data intended to forward.\\ Basically, all available values of the weather station, any values calculated by EVAL_VALUES as well as the status messages and the min/max values are transferred to the MQTT broker.\\ As usual with forwards, individual fields can be excluded from sending via the ignore list FWD_IGNORE.
Metric names and values are sent with FWD_TYPE = MQTTMET and imperial names/values with FWD_TYPE = MQTTIMP.\\ In FWD_URL the MQTT broker address, the port and the topic are in the format
FWD_URL = MQTTipaddress:port@topic-hierarchy%prefix
specified.\\ Port 1883 is set as the standard port. The default topic is FOSHKweather/Keyname. A prefix is optional and would be placed in front of the name of the key.\\ A possibly required user name and the specification of the password are made via FWD_SID (username) and FWD_PWD (password). FWD_INTERVAL defines how often the data is sent to the MQTT server. If this value remains free, every incoming data packet is sent from the weather station.
Examples:
[Forward-41]
FWD_CMT = MQTT-Forward of metric values to LoxBerry
FWD_TYPE = MQTTMET
FWD_ENABLE = True
FWD_URL = 192.168.15.236:1883%metric_
FWD_STATUS = True
FWD_SID = mqttUSERNAME
FWD_PWD = mqttPASSWORD
FWD_IGNORE =
FWD_MQTTCYCLE = 0
FWD_EXEC =
FWD_INTERVAL =
[Forward-42]
FWD_CMT = MQTT-Forward of imperial values to LoxBerry
FWD_TYPE = MQTTIMP
FWD_ENABLE = True
FWD_URL = 192.168.15.237@house/weatherstation/ecowitt/GW1000/%imperial_
FWD_STATUS = True
FWD_SID = mqttUSERNAME
FWD_PWD = mqttPASSWORD
FWD_IGNORE =
FWD_MQTTCYCLE = 0
FWD_EXEC =
FWD_INTERVAL = 60
In the standard setting, all fields are sent to the MQTT broker via MQTT each time data is received from the weather station.\\ FWD_MQTTCYCLE can be used to specify that only changed data is transmitted via MQTT. The complete data record of the weather station is only transferred in the cycle of the number of minutes specified here.\\ FWD_MQTTCYCLE = 10 therefore means that the data is completely sent to the MQTT server every 10 minutes. In the intervening period, only the topics whose value / content have changed are transmitted.\\ This serves to minimize traffic while at the same time ensuring that all data is available at the destination.
\\
++++
----
++++ Sending FOSHKplugin data to a MQTT-server (deprecated) |
**Sending FOSHKplugin data (weather station data) to a MQTT-server (deprecated)**
Because there was no native MQTT support up to version v0.08, the method described here was the only option of sending the data to an MQTT broker. This is still possible - but no longer necessary with v0.08 with its dedicated MQTT forward.
However, it is possible to publish on an MQTT server using a wrapper script. A cron job, a small bash script and the MQTT CLI are required.
== cronjob ==
* * * * * root /opt/FOSHKplugin/FOSHKplugin2mqtt.sh
* * * * * root sleep 30; /opt/FOSHKplugin/FOSHKplugin2mqtt.sh
The bash-script FOSHKplugin2mqtt.sh:
== FOSHKplugin2mqtt.sh ==
#! /bin/bash
# FOSHKplugin2mqtt.sh
# script to pull data from FOSHKplugin and send them via mqtt
# could be started through cron
# FOSHKplugin-stuff
IP=192.168.15.236 # address where FOSHKplugin is running
PORT=8080 # port on which FOSHKplugin is running
FMT=STRING?units=m&crondaemon # use units=e for imperial values
#FMT=RAW # or use RAW-data instead
# MQTT-stuff
MIP=192.168.15.236 # address of MQTT-server
MPORT=1883 # MQTT-port (usually 1883)
MUSR=loxberry # username for MQTT-server
MPWD=G3he1mesPassword # password for MQTT-user
# pull data from FOSHKplugin
URL=http://$IP:$PORT/$FMT # just create the URL
payload=`curl -s $URL|sed "s/ /%20/g"|sed "s/[&; ]/ /g"`
# parse and send over to MQTT
for record in $payload; do
set -- `echo $record | tr '=' ' '`
key=$1
value=`echo $2|sed "s/%20/ /g"|sed "s/\"//g"`
mosquitto_pub --topic FOSHKplugin/$key -u $MUSR -P $MPWD -h $MIP -p $MPORT -m "$value"
#echo "$key <-- $value"
done
mosquitto_pub is used to publish the data - so you have to make sure that this program is available:
sudo apt install mosquitto-clients
\\
++++
----
{{anchor:pwt}}
++++ Installation of FOSHKplugin generic version for several PWT instances |
**Installation of FOSHKplugin generic version for several PWT instances**
[[http://cba.today/personal-weather-tablet/|Personal Weather Tablet (PWT)]] on an Android tablet is a very nice alternative to a dedicated console.\\ This means that old, disused tablets can still be put to good use. In custom server mode, PWT expects the weather station to deliver the Ecowitt data to the tablet. Since there is only the possibility of defining a single destination on the weather station, FOSHKplugin instead can receive this data and forward it to any other destination.
Required: 24/7 computer system (e.g. Raspberry Pi) with ssh access or local console for installation \\ 1. Create a directory
sudo mkdir /opt/FOSHKplugin
2. Change to the directory
cd /opt/FOSHKplugin
3. Download the installation file
wget -N http://foshkplugin.phantasoft.de/files/generic-FOSHKplugin.zip
4. Extract the installation file
unzip generic-FOSHKplugin.zip
5. Start the installation script
sudo ./generic-FOSHKplugin-install.sh --install
6. Initial configuration\\ In the square brackets there should already be meaningful defaults that can be selected with ENTER. However, you can also enter your own value in order to overwrite these defaults:
**+ + + FOSHKplugin + + + ip address of target system to send UDP-messages to []:**\\ Leave blank if no UDP forwarding is required, otherwise enter the IP address of the destination of the UDP messages.\\
**+ + + FOSHKplugin + + + udp port on target system []:**\\ Leave blank if no UDP forwarding is required, otherwise enter the UDP port of the target system.\\
**+ + + FOSHKplugin + + + ip address of local system [192.168.15.237]:**\\ Enter the IP address of the local system, i.e. the device on which FOSHKplugin is to run (please do not use an IPv6 or localhost address).\\
**+ + + FOSHKplugin + + + http port on local system [8080]:**\\ The local port on which the internal http server is started by FOSHKplugin, the default can be accepted with ENTER.\\
**+ + + FOSHKplugin + + + ip address of weather station [192.168.15.215]:**\\ Please enter the IP address of the weather station here. This is generally found automatically.\\
**+ + + FOSHKplugin + + + command port of weather station [45000]:**\\ The command port of the weather station. Here, too, the default 45000 (the default port for FOSHK weather stations) can be accepted with ENTER.\\
**+ + + FOSHKplugin + + + message-interval of weather station [30]:**\\ Enter the desired interval in seconds at which the weather station sends the data to FOSHKplugin. The default of 30 seconds can be accepted - however, other time intervals can also be used. Note that this is also the minimum time interval for forwards.\\
**+ + + FOSHKplugin + + + are these settings ok? (Y/N)**\\ The settings made are accepted with Y. With N it can be configured again if an error is discovered.\\
**+ + + FOSHKplugin + + + do you want to write settings into the config-file? (Y/N)**\\ With Y these settings are written into the config file (foshkplugin.conf).\\
**+ + + FOSHKplugin + + + do you want to write settings into the weather station? (Y/N)**\\ With Y the required data (IP address and port of the target system from the perspective of the weather station, the interval and the data format Ecowitt) are written to the weather station.\\
**+ + + FOSHKplugin + + + do you want to enable and start the service? (Y/N)**\\ With Y, a service (foshkplugin) is installed and started, which is started automatically every time the computer is restarted and which leads to the restart of FOSHKplugin within a few seconds even if the program crashes.\\ \\
7. advanced configuration\\ The foshkplugin.conf file can be edited with any editor in order to make further settings. For forward operation, however, only the required forwards need to be entered.\\
vi foshkplugin.conf
The data received from the weather station are forwarded to other systems / programs via so-called forwards. A forward block is required for each desired forwarding, in which the target, format, interval and, if necessary, other forward-specific settings are specified.\\ A forward block is identified by [Forward-n] where n is a sequential number (1-99). This number must not be repeated within the config file.\\
Example of a forward to an installation of PWT on a device with the IP address 192.168.15.206:\\
[Forward-1]
FWD_CMT = forward for PWT@Pixel 4a
FWD_ENABLE = True
FWD_URL = http://192.168.15.206:8572/data/report/
FWD_INTERVAL = 30
FWD_TYPE = RAWEW
Further forwards according to this template are possible:\\
[Forward-2]
FWD_CMT = forward for PWT@Tablet bedroom
FWD_ENABLE = True
FWD_URL = http://192.168.15.216:8572/data/report/
FWD_INTERVAL = 30
FWD_TYPE = RAWEW
[Forward-3]
FWD_CMT = forward for PWT@Tablet next to the front door
FWD_ENABLE = True
FWD_URL = http://192.168.15.226:8572/data/report/
FWD_INTERVAL = 30
FWD_TYPE = RAWEW
++++
----
{{anchor:update}}
{{anchor:upgrade}}
++++ Updating a current FOSHKplugin generic installation |
**Updating a current FOSHKplugin generic installation**
sudo -u username ./generic-FOSHKplugin-install.sh -upgrade
sudo -u username ./generic-FOSHKplugin-install.sh -repair
The "repair" may be important this time, because FOSHKplugin has to install some packages via apt/pip. It doesn't do any harm - so you can always do it.
If you want to update to a specific (Beta) version you should append the corresponding filename:
sudo -u username ./generic-FOSHKplugin-install.sh --update generic-FOSHKplugin-0.0.10Beta.zip
If no file name is specified, the current non-beta version (stable) is always installed. However, this version may lack important new features or bug fixes.\\ \\ -update, -upgrade, --update and --upgrade are all equivalent.\\
The current settings in the config file are retained during the update; the service (if configured) will be restarted automatically.\\ Please use the usual updating way via Plugin-Administration for the LoxBerry-version of FOSHKplugin.
++++
----
{{anchor:push}}
++++ get push notifications for critical status changes on the smartphone/tablet |
**get push notifications for critical status changes on the smartphone/tablet**
In addition to notification via UDP, availability as status via http and logging in the log file, important status changes (e.g. firmware update, sensor, watchdog, battery, storm and thunderstorm warnings) can also be sent to any mobile device (iOS , Android) as push notification, FOSHKplugin uses the API of Pushover.\\ [[https://pushover.net/%5DPushover%5B/url|Pushover]] is a one-time purchase app (no subscription!) that listens in the background for incoming messages from the pushover server.\\ If configured accordingly, FOSHKplugin sends these critical warnings via API call via the Internet to the Pushover cloud service, which then immediately searches for contact with the devices stored there and delivers the message immediately.\\ In the mobile device itself, these push notifications then arrive - depending on the setting - with or without sound and/or vibration or silently and are displayed both on the lock screen and in the notification bar. If available and configured accordingly, the notification LED also lights up or flashes.\\ With adjustable time schedules, you can specify the time periods during which the messages are sent silently within Pushover.\\ Besides the one-off purchase price for the app, there are no other hidden costs. At least if you stay below the free 7500 (!) notifications per month.\\ I've experimented with it for a few days now and I'm thrilled! The delivery takes place reliably and promptly - within a few (here 1-2) seconds (provided that the Internet is available).
**Manual:**
- get the app Pushover from the respective store ([[https://play.google.com/store/apps/details?Id=net.superblock.pushover%5DAndroid%5B/url|Android]], [[https://apps.apple.com/de/app/pushover-notifications/id506088175%5DiOS%5B/url|iOS]])
- Start the Pushover app and assign credentials
- Log in via web browser: [[https://pushover.net/login]]
- Make a note of the key under "Your User Key", this must be specified for PO_USER in the FOSHKplugin config file foshkplugin.conf
- Generate an API token for FOSHKplugin under "Your Applications" (Create an Application / API Token) - the key specified under API Token/Key must be specified under PO_TOKEN in the FOSHKplugin config file - as app notification icon you could use [[https://foshkplugin.phantasoft.de/files/icon_72.png|this]]
- Adjust config foshkplugin.conf: Pushover\PO_ENABLE=True Pushover\PO_USER="Your User Key" and Pushover\PO_TOKEN=API-TOKEN:\\
[Pushover]\\ PO_ENABLE = True\\ PO_USER = userkey\\ PO_TOKEN = token\\ It is not necessary to enter a URL under PO_URL. This setting would overwrite the internally predefined pushover URL.\\
Restart FOSHKplugin
From now on there should be a push notification for all important status changes.\\ The sending of push messages is activated with the switch PO_ENABLE = True in the config file. Sending is deactivated by default (False).\\ Push notifications from FOSHKplugin can also be activated and deactivated during runtime, provided the correct credentials are stored in the config file.\\ This is done via http via any web browser by calling up the page http:%%//%%ipaddress:port/FOSHKplugin/pushover=enable (activate) or http:%%//%%ipaddress:port/FOSHKplugin/pushover=disable (deactivate). The port is the port specified in the config file under LBH_PORT.\\ This is also possible via the UDP interface of FOSHKplugin: sending "Plugin.pushover=enable" to the IP address of the host and the port on which FOSHKplugin is running (LBU_PORT in the config file) activates the sending; "Plugin.pushover=disable" deactivates this.\\ Any errors when sending push notifications as well as activating/deactivating during runtime are logged in the standard log file.
**You'll get Pushover-notifications (if configured) in case of:**\\ SENSOR_WARNING = True and a key (any key that is normally contained in the output string of the weather station, such as wh65batt, leakbatt1, soilbatt1, pm25batt1 ...) given in SENSOR_MANDATORY is missed in the incoming string from the weatherstation:\\ **
[Forward-21]
FWD_TYPE = RAWAMB
FWD_CMT = Forward for Ambient Weather
FWD_URL = https://api.ambientweather.net/endpoint?
FWD_ENABLE = True
FWD_STATUS = False
FWD_INTERVAL = 180
The device is authenticated via the PASSKEY sent through the GW1000/DP1500 automatically, but can be adjusted in the config file with FWD_SID = [PASSKEY] if necessary.
From now on, FOSHKplugin also sends the incoming data from the GW1000/DP1500 to Ambient Weather.\\ No additional hardware or software is required.
\\
++++
----
{{anchor:pwsdashboard}}
++++ Set up a forward to PWSDashboard |
**Set up a forward to PWSDashboard**
[[https://pwsdashboard.com/|PWSDashboard]] is a website template that can be set up very quickly. It visualizes many sensors from the world of fine offset in an extremely beautiful way.\\ Since PWSDashboard receives data in Ecowitt format, FOSHKplugin actually only needs to set up a forward in Ecowitt format (FWD_TYPE EW or RAWEW):
[Forward-11]
FWD_URL = http://192.168.15.236:80/pwsWDxx/data/report/
FWD_ENABLE = True
FWD_TYPE = EW
FWD_CMT = PWSDashboard
FWD_INTERVAL = 30
The variable $passkey1 in the index.php in the web server directory pwsWDxx/data/report still has to be filled with the value transmitted under PASSKEY.
$passkey1 = '000102030405060708090A0B0C0D0E0F'; // if PASSKEY is known enter it here
The easiest way to find the PASSKEY is in the FOSHKplugin-RAW-log file or copy it from the PWSDashboard log file pwsWDxx/data/report/ecco_stats.txt:
Fri, 10 Jul 2020 13:13:09 +0000 = Ecowitt data: 50 000102030405060708090A0B0C0D0E0F needs to be set in index.php
Also note the [[https://pwsdashboard.com/documentation2012/41a_ecowitt.pdf|documentation]] from PWSDashboard for integration via the Ecowitt protocol. \\
++++
----
{{anchor:lightning}}
++++ Saving lightning values for the GW1000/DP1500 (WH2650/WH2600Pro) |
**Saving lightning values for the GW1000/DP1500 (WH2650/WH2600Pro)**
With every restart and apparently after a certain time, the GW1000/DP1500 (probably also the WH2650/WH2600Pro) loses the values for the time of the last lightning (lightning_time) and its distance (lightning).\\ From this point on only empty values are sent instead of the actual values.\\ In the Ecowitt output string it looks like this:
[...]&lightning_time=&lightning_num=0&lightning=&[...]
[[https://pwsdashboard.com/|PWS Dashboard]] or [[https://play.google.com/store/apps/details?id=today.cba.gw1000station&hl=de&gl=US|Personal Weather Tablet]] (PWT) can no longer display lightning data because they do not buffer these values.
With the option Export\FIX_LIGHTNING (enabled by default) FOSHKplugin writes these values with every change that does not contain "" as a value into the config-file as:
== foshkplugin.conf ==
[Status]
last_lightning_time = 1610556044
last_lightning = 27
and uses these saved values when empty values are received from the weather station for all forwards and export to UDP/CSV/...
When the device is started up for the first time, these values are of course not known to FOSHKplugin. Therefore these values can be entered manually in the config file.\\ Ecowitt declares the time of the last lightning as Unixtime (UTC). The indication of the distance is saved in kilometers.\\ A service such as [[https://www.unixtime.de/]] is recommended to calculate the corresponding Unixtime yourself. But you can also just look in the raw-log file and transfer the values.
++++
----
{{anchor:exec}}
++++ modify outgoing data line (exec) |
**modify outgoing data line (exec)**
The FWD_EXEC function offers the option of editing, exchanging, deleting or adding further data for all data outgoing for this forward before it is actually sent.\\ In the config file, the line
FWD_EXEC = /path/to/script
must be entered in the corresponding forward block. Keep in mind to restart FOSHKplugin after any modification of the config file.
The output line generated for this forward is transferred to this script as a parameter.
With a shell script or another program, these data can be changed as required:
#!/bin/bash
# add additional data to outgoing data line for e.g. Ecowitt-upload
instr="$@"
echo "$instr"+"&tf_ch1=71.1&tf_batt1=1.1"
If you want to integrate the sunhours value from the independent BL-SunRecorder to the output data of a forward, just put the line **//FWD_EXEC = /path/to/addSR.sh//** in the forward section and place a script like:
#!/bin/bash
# addSR.sh - gather sunhours from BL Sun Recorder and append the value as sunhours to the output string
# execute this script with FWD_EXEC = /path/to/addSR.sh in the specific forward section
instr="$@"
sunhours=`head -1 /some/where/SRsunshine.dat`
if [ ! -z "$sunhours" ]; then srstring="sunhours=$sunhours"; fi
echo "$instr"$srstring
to /path/to/.
As in the example above, values can be added from any source - also (with curl) via http. Existing assignments can be changed, exchanged or deleted.
The last output of the script is then taken over by FOSHKplugin and sent to the destination specified under FWD_URL.
[Forward-31]
FWD_CMT = save as local realtime.txt
FWD_TYPE = REALTIMETXT
FWD_ENABLE = True
FWD_INTERVAL = 30
FWD_URL = /srv/oli-ubuntu2/loxberry-test/
[Forward-32]
FWD_CMT = save as local clientraw.txt
FWD_TYPE = CLIENTRAWTXT
FWD_ENABLE = True
FWD_INTERVAL = 30
FWD_URL = /srv/oli-ubuntu2/loxberry-test/
The owner of the generated realtime.txt and clientraw.txt corresponds to the user context in which FOSHKplugin is started. This user therefore needs the appropriate write rights in the target directory.
To save the realtime.txt/clientraw.txt file on a remote server, I recommend sending it via http(s):
[Forward-33]
FWD_CMT = save via http/POST as remote realtime.txt
FWD_TYPE = REALTIMETXT
FWD_ENABLE = True
FWD_INTERVAL = 30
FWD_SID = user
FWD_PWD = password
FWD_URL = http://wetter.phantasoft.de/files/upload.php
[Forward-34]
FWD_CMT = save via http/POST as remote clientraw.txt
FWD_TYPE = CLIENTRAWTXT
FWD_ENABLE = True
FWD_INTERVAL = 30
FWD_SID = user
FWD_PWD = password
FWD_URL = http://wetter.phantasoft.de/files/upload.php
On the server side, however, a php file upload.php is required to receive the incoming file and store it in the web server's file system:
== upload.php ==
Alternatively, you can also upload via ftp or ftps. For this purpose, the complete URI is specified in FWD_URL and the credentials are specified via FWD_SID (username) and FWD_PWD (password):
[Forward-35]
FWD_CMT = save via ftp as remote realtime.txt
FWD_TYPE = REALTIMETXT
FWD_ENABLE = True
FWD_INTERVAL = 30
FWD_SID = username
FWD_PWD = password
FWD_URL = ftp://foshkplugin.phantasoft.de/httpdocs/foshkplugin.phantasoft.de/temp/
[Forward-36]
FWD_CMT = save via ftp as remote clientraw.txt
FWD_TYPE = CLIENTRAWTXT
FWD_ENABLE = True
FWD_INTERVAL = 30
FWD_SID = username
FWD_PWD = password
FWD_URL = ftp://foshkplugin.phantasoft.de/httpdocs/foshkplugin.phantasoft.de/temp/
If the transport is to be TLS-secured (ftps), instead of ftp:%%//%% ftps:%%//%% must be used in the FWD URL.
**It should be noted that not all fields in the realtime.txt and clientraw.txt are filled by FOSHKplugin.**
++++
----
{{anchor:dailycsv}}
++++ Saving of daily values in a separate CSV file |
**Saving of daily values in a separate CSV file**
For some evaluations it can be helpful to collect the minimum and maximum values of a day as well as other statistical values on a daily basis - together with the time of the respective occurrence.\\ This statistical data includes, for example, the time and amount of the heaviest rain during the day or the number of lightning strikes. But the minimum and maximum values with the respective time of the day could also be of interest for all temperature values.\\ FOSHKplugin has a new function for this in v0.08 that creates such a CSV file.\\ During the first transmission of the day by the weather station (this does not have to be exactly 00:00 but depends on the actual transmission interval of the station), the values and calculations of the last transmission (thus the last of the previous day) are written to the CSV file.\\ The CSV file only contains metric data and its structure (with semicolon as separator and comma as decimal point) can be processed with Excel (at least in the German version) without any problems.
In the configuration file foshkplugin.conf, a name for the file to be generated must be entered in the [CSV] area under CSV_DAYFILE:
[CSV]
CSV_DAYFILE = /path/to/dayfile.csv
If a new version of FOSHKplugin results in a new structure (e.g. because new fields have been added or the sorting has been changed), the previous file /path/to/anyfile.csv is automatically renamed to /path/to/anyfile-YYMMDDHHMMSS.csv. New data will then continue to be written to the file configured under CSV_DAYFILE - but with an updated header line.\\ \\
[Forward-36]
FWD_TYPE = WSWIN
FWD_URL = /opt/loxberry/log/plugins/foshkplugin/
FWD_INTERVAL = 60
FWD_CMT = WSWin forward
Since the minimum interval for WSWin is 60 seconds, the send interval under FWD_INTERVAL should also be set to at least 60 seconds. The path specified under FWD_URL should be a path that the Windows computer can access (via Samba). Alternatively, the file storage location may also be called up via curl/wget (e.g. via a batch file) if the storage location specified as FWD_URL can be reached via a web browser. The file name is always wswin.csv.\\ \\
sudo service foshkplugin restart
or
sudo systemctl restart foshhkplugin
In addition, FOSHKplugin can also be restarted via http/webbrowser or UDP if the RESTART_ENABLE switch in the [Config] area of the config file has been set to True.\\ **Danger!**\\ If the switch is active, the service can be stopped (and automatically restarted by systemd) without further authentication. From anybody who is able to reach your system.\\ **Also important:**\\ If FOSHKplugin is not started as a service but as a program, there is NO automatic restart of FOSHKplugin - the program is only terminated.
FOSHKplugin is restarted via the web browser with
http:%%//%%ipaddress:port/FOSHKplugin/restartPlugin
where ipaddress is the hostname or IP address of the system running FOSHKplugin and port is the port configured as Config\LBH_PORT.
The string "SID = FOSHKplugin, Plugin.shutdown" must be sent via UDP to the port configured under LBU_PORT in order to terminate FOSHKplugin. It is then automatically restarted as a service by systemd.
The upper and lower case is to be observed in all cases!\\ Please activate this switch only if you can ensure that no stranger has access to your FOSHKplugin installation.
++++
----
{{anchor:telegraf}}
++++ Supplying a database with data from the weather station (pull method) |
**Supplying a database with data from the weather station (pull method)**
Since FOSHKplugin also answers HTTP requests from clients, the data can also be called up by FOSHKplugin in various formats.\\ [[https://www.influxdata.com/time-series-platform/telegraf/|Telegraf]] can retrieve this data at a specified interval and write it to various database systems. I use an InfluxDB database for this.\\ JSON is recommended as the import format. If the min/max data is also to be transferred in JSON, the optional parameter &minmax should be added to the URL.\\ If the status values are also of interest to the database, a &status can also be passed as parameter. With parameter &bool, the Boolean values are saved in JSON as True/False instead of 0/1.
A few settings are required in telegraf.conf:
[[outputs.influxdb]]
urls = ["http://127.0.0.1:8086"] # address of InfluxDB server and port
database = "weatherstation"
[[inputs.http]]
urls = [
"http://192.168.15.237:8080/JSON?minmax&status&bool" # url of host, running FOSHKplugin
]
method = "GET"
timeout = "5s"
data_format = "json"
name_override = "weatherdata"
tag_keys = [
"PASSKEY"
]
interval = "30s" # interval to gather all the data from FOSHKplugin
Once the data is in the InfluxDB database, it can also be visualized very nicely with Grafana or Chronograf, for [[https://snapshot.raintank.io/dashboard/snapshot/WJHaL8UN1zcn9O7egkJk8pzu0o9WsqSl|example]].
versions in use while testing export to InfluxDB:\\ InfluxDB v1.6.4 (git: unknown unknown)\\ Version 7.5.5 (commit: b5190ee547, branch: HEAD)\\ Telegraf 1.18.2 (git: HEAD a6143722)
++++
----
{{anchor:influxdb}}
++++ native connection to an InfluxDB database (push method) |
**native connection to an InfluxDB database (push method)**
With v0.08, FOSHKplugin can forward the weather station data directly to an [[https://www.influxdata.com/|InfluxDB]] database.\\ This requires a forward in the format INFLUXMET or INFLUXIMP - where MET stands for the metric and IMP for the data in the imperial format. The forward format is to be defined as usual with FWD_TYPE in the config.\\ The server address and database are specified here in the FWD_URL; If the InfluxDB server does not run under the standard port 8086, the correct port can be specified with a colon after the address. The name of the database is given after the @ sign. If the (existing) database requires authentication, the username and password must be entered as FWD_SID and FWD_PWD. If the connection to the database is to be made via SSL, an https:%%//%% must be entered instead of http:%%//%%.\\ It is not necessary to create a database in advance. FOSHKplugin adds the data to an existing database and - if necessary - creates a new one with the name specified after @ if the database does not exist.\\ The min/max values are always part of the data transmission. If FWD_STATUS is set to True, the status values are also transferred in Boolean format True/False.\\ This is what a corresponding forward looks like:
[Forward-3]
FWD_TYPE = INFLUXMET
FWD_CMT = InfluxDB-Forward of metric values
FWD_URL = http://192.168.15.237:8086@TestData
FWD_SID = DBusername
FWD_PWD = DBpassword
FWD_STATUS = True
FWD_EXEC =
FWD_IGNORE =
If the data is contained in the InfluxDB database, graphical evaluations can be carried out very easily using Grafana or Chronograf.\\ As an experiment I realized this with [[https://snapshot.raintank.io/dashboard/snapshot/WJHaL8UN1zcn9O7egkJk8pzu0o9WsqSl|Grafana]].
versions in use while testing export to InfluxDB:\\ InfluxDB v1.6.4 (git: unknown unknown)\\ Version 7.5.5 (commit: b5190ee547, branch: HEAD)\\ Telegraf 1.18.2 (git: HEAD a6143722) \\ \\ InfluxDB v1.8.10 is also known to work.\\
++++
----
{{anchor:log}}
++++ Log file handling |
**Log file handling**
Log files are very useful for commissioning and in the event of problems.\\ All messages that are useful for assessing the status or troubleshooting are logged. Also the forward number is logged in order to be able to find faulty blocks in the config file more easily.\\ However, you should consider whether it is really sensible to keep a permanent log. If an SD card is used as the storage medium, the SD card will eventually be written down - an SD card can only tolerate a defined number of write operations.\\ Especially the export log - if a very short interval is set - can quickly become very large, because for every message coming from the weather station - depending on the configuration - an entry for UDP, each forwarding (FWD) and CSV is also generated.
We distinguish 3 different log files with different content:
**logfile**\\ Contains status messages when the FOSHKplugin is started and stopped, shows the parameters currently in use and logs error messages while running and incoming requests that do not come from the weather station itself. In normal operation in the internal local network, this log should not be particularly large.
**rawfile**\\ Logs every (!) incoming line from the weather station. Depending on the selected transmission interval, this file can become very large very quickly - with a transmission interval of 16 seconds, 5400 lines can be stored per day, which, depending on the number of connected sensors, contain 1000 or more characters - that results in approx. 5MByte per day.\\ You should therefore urgently consider whether this logging really makes sense. I do this - simply to be able to find an explanation for a strange behavior in retrospect. However, my storage location for the log files is not an SD card but a file server connected via nfs.
**sndfile**\\ The fastest growing log file with the largest space requirement - also mentioned as Export-log.\\ Every (!) line used in a forward is logged here. Each incoming line from the weather station is multiplied by a factor of ten, depending on the number of forwards.\\ With (currently possible) 100 forwards, 100 * 5MByte per day can accrue in the log level ALL. (That's 500MByte per day!)\\ I actually write that down here - in order to be able to examine the chain from weather station - FOSHKplugin - send destination for any problems in the event of an error. But as already mentioned above, my logging target is not an SD card but an uncritical hard drive in a server system.\\ For the normal user, it should not be necessary to write the messages that have been sent successfully.
There are a few options for creating and adjusting log files in the FOSHKplugin.\\ One can configure the log level (ALL, INFO, WARNING, ERROR), filter out lines with certain strings (LOG_IGNORE), completely (LOG_ENABLE = False) or partially deactivate logging (remove filenames for logfile, rawfile or sndfile).
The sharpest sword for limiting log expenditure is the log level via Logging\LOG_LEVEL in the config file.\\ You can fine-tune the messages depending on the importance:
* **ALL**, as before, all lines are logged
* **INFO** - all lines except ERROR, WARNING, INFO and OK are hidden
* **WARNING** - all lines except ERROR and WARNING and OK are hidden
* **ERROR** - only lines with ERROR and OK are output
For reasons of compatibility, **ALL** is preset - but I recommend **LOG_LEVEL = INFO** - so everything that was **NOT** successful is logged
Another approach is to hide recurring log lines in the standard log (logfile), for example for recurring queries via cron.\\ With Logging\IGNORE_LOG, lines can be excluded from the logging in the standard log. All lines that contain one of the strings specified there (comma-separated list of search words/strings) are not logged.
Individual log files can be deactivated by leaving their log file names empty:
[Logging]
logfile = /opt/FOSHKplugin/log-foshkplugin.log
#rawfile = /opt/FOSHKplugin/raw-foshkplugin.log
sndfile = /opt/FOSHKplugin/snd-foshkplugin.log
deactivates the output of the raw log file - so the incoming lines from the weather station are not logged at all. However, the standard log foshkplugin.log and all outgoing lines are still logged.\\ So, to deactivate a specific log file, simply remove the name of the respective file.\\ From v0.08 it is possible to switch logging on and off globally via the switch in the config file Logging\LOG_ENABLE = True/False (default: True):
[Logging]
LOG_ENABLE = False
LOG_LEVEL = INFO
IGNORE_LOG = crondaemon
logfile = /opt/FOSHKplugin/log-foshkplugin.log
rawfile = /opt/FOSHKplugin/raw-foshkplugin.log
sndfile = /opt/FOSHKplugin/snd-foshkplugin.log
The names configured for logfile, rawfile and sndfile are retained. A change to True and a subsequent restart of FOSHKplugin then writes the originally configured log files again.
LOG_LEVEL can also be adjusted during operation via http:%%//%%ipadress:port/FOSHKplugin/loglevel=[ALL,INFO,WARNING,ERROR] - however, the value set in the config file applies again after a restart
One final piece of advice on logging concerns the use of logrotate.\\ As the name of the program suggests, logrotate rotates the log files and shortens them if they exceed a specified size or age. It is part of the Linux distribution and can also be used for shortening or collecting and packing log files from FOSHKplugin.\\ Instructions for this should be found on the Internet. A first attempt could be this:
== /etc/logrotate.d/foshkplugin ==
/opt/FOSHKplugin/*.log {
daily
rotate 7
missingok
dateext
copytruncate
compress
}
Just create the file /etc/logrotate.de/foshkplugin as user root and put the content in. Afterwards restart the logrotate service as root to make sure the new settings are in use:
sudo service logrotate restart
\\
++++
----
{{anchor:multipwt}}
++++ Submit station data to any number of Personal Weather Tablet (PWT) instances with ONE forward |
**Submit station data to any number of Personal Weather Tablet (PWT) instances with ONE forward**
Previously, you had to generate a separate forward for each device on which [[https://play.google.com/store/apps/details?id=today.cba.gw1000station|Personal Weather Tablet (PWT)]] was to receive the data. I had described this in the recipe "Installation of FOSHKplugin generic version for several PWT instances [[#pwt|here]].\\ However, this is quite time-consuming, especially with changing IP addresses (DHCP). And it generates useless traffic even if the corresponding target device is not switched on at all.
Therefore the new version v1.4.1 of PWT now offers a new connection type: the "**UDP broadcast listener**".\\ If PWT is operated in UDP broadcast listener mode, it listens to incoming data in Ecowwitt format on a configurable UDP port.
FOSHKplugin can already forward incoming Ecowitt data via UDP. A forward like this is required for this:
[Forward-46]
FWD_TYPE = RAWUDP
FWD_URL = 192.168.15.255:12350 # use broadcast address:port and configure PWT to the same UDP port
FWD_CMT = send the Ecowitt stream via UDP broadcast to multiple PWT instances to broadcastaddress:port
This sends the data in Ecowitt format coming from the weather station via UDP to a port (here as an example 12350) to a broadcast address (here 192.168.15.255) at which any number of clients can listen (not only PWT!) and process the incoming data.\\ I use it to operate 7 or 8 devices in parallel here and thus reduce the data transfer considerably.
From FOSHKplugin v0.09 on there is another forward type EWUDP, which receives incoming data in Ambient Weather, WU and Ecowitt format, if necessary, converts it to Ecowitt format and then sends this data via UDP.\\ PWT picks up the data and displays them accordingly - at the same time, on all devices listening on this port.\\ This means that Ambient Weather devices which transmits in AW format and stations that only can transmit data in WU format (e.g. WH600x) can then feed Personal Weather Tablet with data in this way.
I think this new feature of PWT can be very useful for some.\\ But of course the "old" way via dedicated forwards in FOSHKplugin and connection type "Custom Server" on PWT is still available.
\\
++++
----
{{anchor:remap}}
++++ Remapping keys/values |
**Remapping keys/values**
Some forward targets only support a selection of sensors, e.g. Ambient Weather only supports one internal/external PM2.5 sensor or Awekas or WSWin only support 4 soil moisture sensors.\\ However, FOSHKplugin always transmits logically continuously - i.e. starts with the first sensor and sends the maximum number of channels valid for the forward.\\ A corresponding assignment or selection can be made with FWD_REMAP.
Example:\\ Ambient Weather only supports one internal and one external PM2.5 sensor. In the Ecowitt format, however, there are four PM2.5 sensors - no distinction between internal and external.\\ FOSHKplugin sends the PM2.5 sensor of channel 1 as an outdoor and channel 2 as an indoor sensor to Ambient Weather.\\ If you want to use the PM2.5 sensor of channel 3 in Ambient Weather as an indoor sensor, you can use the remap rule:
FWD_REMAP = @pm25_ch1=@pm25_ch3,@pm25_avg_24h_ch1=@pm25_avg_24h_ch3
which convert the data of the 3rd channel to the 1st channel, whereby the 3rd channel is used as a PM2.5 outdoor sensor for Ambient Weather.\\ This can be combined as desired - so if you also want to use the data from the 4th channel as a PM2.5 indoor sensor for Ambient Weather, you can use the line
FWD_REMAP = @pm25_ch1=@pm25_ch3,@pm25_avg_24h_ch1=@pm25_avg_24h_ch3,@pm25_ch2=@pm25_ch4,@pm25_avg_24h_ch2=@pm25_avg_24h_ch4
to make this happen.\\ The assignment is always made with target = origin - whereby the origin can be a static string or a static numerical value or the content of an existing field.\\ If you want to use the content of a field, an @ must be placed at the beginning of the original field. A
FWD_REMAP = @pm25_ch1=pm25_ch3
would only assign the string "pm25_ch3" to the pm25_ch1 field. The @ classifies the content of an existing field.\\ The same goes for the target - the assignment
FWD_REMAP = pm25_ch1=@pm25_ch3
basically does the same job as
FWD_REMAP = @pm25_ch1=@pm25_ch3
however, in the second case, if the pm25_ch1 field does not exist, an error message is issued in the log; while in the first case an additional field pm25_ch1 is generated. So the @ in the target is used to check the function.
There are two critical points to note about the remap function:\\ 1. Remapping does not take place globally but is always related to the respective forward.\\ 2. The field names to be specified do NOT correspond to the key names of the target system but to the internal variable names of FOSHKplugin. Depending on the measurement system (metric/imperial) required for the target, these names can be different.
Another example:\\ With the WN34, Ecowitt offers a total of 8 temperature sensors that can be used for temperature measurements in the ground (WN34S) or in liquids (WN34L).\\ In addition to the actual interior temperature sensor, WSWin knows 6 other T/H sensors and 4 soil temperature sensors.\\ FOSHKplugin uses the first 6 WH31 to fill the 6 T/H sensors possible in WSWin and only uses channels 1 to 4 for the floor temperature sensors (channels 5..8 are discarded).\\ The user may wish to use the temperature and humidity values of an existing WH45 instead of the WH31 channel 4.\\ A remapping of the data of the WH45 on channel 4 of the additional sensors should then look like this:
FWD_REMAP = @temp4c=@tc_co2,@humidity4=@humi_co2
If you want to transfer channels 5-8 to WSWin instead of channels 1-4 of the possibly existing 8 WN34, a remap definition like this could be made:
FWD_REMAP = @tf_ch1c=@tf_ch5c,@tf_ch2c=@tf_ch6c,@tf_ch3c=@tf_ch7c,@tf_ch4c=@tf_ch8c
Last example:\\ When forwarding to air data, FOSHKplugin always uses channel 1 of the existing PM2.5 sensors. If you want to use channel 3 instead, this can be done by remapping the values:
FWD_REMAP = @pm25_ch1=@pm25_ch3
This assigns the content of the pm25_ch3 key to the pm25_ch1 key (which the will be sent to [[http://Luftdaten.info|Luftdaten.info]]).
One final note:\\ It is also possible to remove individual keys via the remap function. To do this, enter a simple minus sign as the source value:
FWD_REMAP = pm25_ch1=-
This removes the key pm25_ch1 from the input data for this forward.
The remap function is available for all forwards.
++++
----
{{anchor:aprs}}
++++ Sending weather station data via APRS/CWOP |
**Sending weather station data via APRS/CWOP**
With v0.09 of FOSHKplugin it is possible to set up a forward to CWOP via the type APRS. This requires a forward definition such as:
[Forward-23]
FWD_TYPE = APRS
FWD_URL = cwop.aprs.net:14580
FWD_SID = CWOP-ID
FWD_PWD =
FWD_ENABLE = True
FWD_INTERVAL = 300
The CW number, i.e. the identifier of the station, is to be named with FWD_SID. If a password is required for sending, this can be specified as FWD_PWD. Please also note these [[http://www.wxqa.com/servers2use.html|instructions]] regarding the need for a password and the server to be used..\\ Ham radio operators may send weather data without registering on CWOP. Just use rotate.aprs2.net as the server in FWD_URL and your own APRS credentials in FWD_SID and FWD_PWD.\\ If the standard port (14580) is used, the port can be omitted from the FWD_URL. Since the transmission does not take place via http, of course **no** http:%%//%% may be prefixed.\\ The minimal interval in FWD_INTERVAL should not be less than 300 (5 minutes).
It is also necessary to specify the decimal coordinates of the location in the Coordinates section:
[Coordinates]
ALT = 53 # not needed for APRS/CWOP
LAT = 52.669481 # use negative coordinates for southern hemispehere
LON = 13.266531 # use negative coordinates for west of the prime meridian
as these coordinates are an integral part of the data set to be transmitted to CWOP.
The values for winddir, windspeedmph, windgustmph, tempf, hourlyrainin, solarradiation, dailyrainin, humidity and baromrelin are transferred - each (hopefully) in the correct form.\\ As usual, the fields to be transferred can be remapped with the remap function FWD_REMAP (e.g. to use a WH31 instead of the WH32) and a script can still change or otherwise output the data via FWD_EXEC.
++++
----
{{anchor:pushonlimit}}
{{anchor:getvalue}}
++++ Push notifications when limit values are fallen below or exceeded (getvalue) - deprecated|
**Push notifications when limit values are fallen below or exceeded (getvalue) - deprecated**
*/5 * * * * root /usr/local/bin/checkTemp.sh
And the actual bash script checkTemp.sh, which is started every 5 minutes via cron. Of course, you can change the interval in the crontab as you like.
== checkTemp.sh ==
#!/bin/bash
# Pushover settings
po_token='YOURPUSHOVERTOKEN' # Pushover API token
po_user='YOURPUSHOVERUSER' # Pushover user name
po_title='checkTemp.sh-Warning' # Pushover message title
po_message='' # Pushover message - will be filled later
# thresholds
temp_min_thrs=5.5 # temperature min threshold
temp_max_thrs=25.5 # temperature max threshold
# main
tempc=`curl -s http://192.168.15.236:8080/getvalue?key=tempc` # retrieve temperature in °C (use tempf for °F)
if [[ ! -z "$tempc" ]]; then # make sure of value
# outdoor temperature min
if (( $(echo "$tempc < $temp_min_thrs" |bc -l) )); then # if current temp < min threshold
po_message="outdoor temperature (${tempc}°C) is below ${temp_min_thrs}°C!"
#echo $po_message # remove for cron
curl -s -o /dev/null --form-string "token=${po_token}" --form-string "user=${po_user}" --form-string "title=${po_title}" --form-string "message=$po_message" https://api.pushover.net/1/messages.json
# outdoor temperature max
elif (( $(echo "$tempc > $temp_max_thrs" |bc -l) )); then # if current temp > max threshold
po_message="outdoor temperature (${tempc}°C) is higer than ${temp_max_thrs}°C!"
#echo $po_message # remove for cron
curl -s -o /dev/null --form-string "token=${po_token}" --form-string "user=${po_user}" --form-string "title=${po_title}" --form-string "message=$po_message" https://api.pushover.net/1/messages.json
fi
fi
What is still missing here is a routine to avoid permanent push notifications - otherwise a corresponding message would be issued every 5 minutes if the temperature value is outside the threshold values.
++++
----
{{anchor:problemsolving}}
++++ problem solving |
**problem solving**
There are a few well-known problems that occur here and there, and I would like to briefly describe their solutions here:
Most problems are caused by the rather complicated rights management in Linux. Especially with manual changes to the config file or with updates, the access permissions to the corresponding files can be changed or receive the wrong owner.
For understanding:
Only the owner of a file may access a file. He therefore needs access rights that are derived from the ownership. Of course, other users may also access files - provided they have the appropriate permissions. If the first installation takes place in the context of user 1, the start as well as any updates or changes in the config file must be carried out by exactly this user, unless the group rights are changed.
Sometimes, however, one cannot remember in which context the installation originally took place or forgets to prefix the required "//sudo -u username//" when editing or updating. The owner as well as the file permissions can be shown at any time from the console or via ssh with a
ls -lah /opt/FOSHKplugin/
Example:
root@test:/opt/FOSHKplugin# ls -lah /opt/FOSHKplugin/
total 516K
drwxr-xr-x 2 root root 4.0K Feb 11 12:32 .
drwxr-xr-x 11 root root 4.0K Feb 11 12:31 ..
-rw-rw-rw- 1 root root 12K Jan 22 00:09 foshkplugin.conf
-rw-r--r-- 1 root root 12K Jan 22 00:09 foshkplugin.conf.orig
-rw-r--r-- 1 root root 2.4K Jan 22 00:09 foshkplugin.png
-rwxr-xr-x 1 root root 326K Jan 22 00:09 foshkplugin.py
-rw-r--r-- 1 root root 408 Jan 22 00:09 foshkplugin.service
-rw-r--r-- 1 root root 95K Jan 22 09:28 generic-FOSHKplugin-0.0.9Beta.zip
-rwxr-xr-x 1 root root 13K Jan 22 00:09 generic-FOSHKplugin-install.sh
-rw-r--r-- 1 root root 35K Jan 22 00:09 README.md
The same owner (root:root in this example) should be entered here for all files.
Of course, you can also change the owner of the files with //chown// or adjust the file rights with //chmod//. However, I recommend using the integrated repair function. A
/opt/FOSHKplugin/generic-FOSHKplugin-install.sh -repair
is always a good way to adjust the user rights. This repair also automatically installs any necessary but missing libraries. Especially after an update of FOSHKplugin (before v0.09), additional libraries may be required that need to be installed - the repair function automates this.
In rare cases, the FOSHKplugin config file may become corrupted and FOSHKplugin will no longer start. With every successful start FOSHKplugin creates a backup copy of the current (working) configuration, which can easily be reverted to in this case:
A
sudo cp -p /opt/FOSHKplugin/foshkplugin.conf.foshkbackup /opt/FOSHKplugin/foshkplugin.conf
copies the last working version of the config file over the (broken) file actually in use.
Also a common reason for support requests:
Changes to the config file only become active AFTER a restart of FOSHKplugin! So you can make any changes in the config file - but they will only become active after FOSHKplugin has been restarted. Restarting FOSHKplugin is of course done by restarting the underlying operating system. However, it is easier and faster to restart FOSHKplugin alone. If FOSHKplugin was set up as a service, in most cases this service can be restarted by a
sudo service foshkplugin restart
to restart the service. When the service is started, the current config file is read in and processed. If FOSHKplugin runs in the foreground and not as a service, a CTRL-C in the programme window or (if it runs in the background) a killall FOSHKplugin.py with a subsequent restart of the programme is sufficient.
In general, it is a good idea to run FOSHKplugin in the foreground in case of unclear problems. All you have to do is stop the corresponding service:
sudo service foshkplugin stop
and then start FOSHKplugin like a normal program from the command line:
sudo -u username /opt/FOSHKplugin/foshkplugin.py
Any error messages are output directly in plain text. These can then be copied and sent to me by e-mail for further analysis.
FOSHKplugin supports countless services and various weather stations - I cannot test them all to the same extent. I also don't have all the supported weather stations and sensors here myself (although I try) and with some (such as devices from Ambient Weather) it is almost impossible for me to test them in conjunction with FOSHKplugin (here in Europe 868MHz are mandatory). Therefore, it can happen that I myself do not notice any program errors because the constellation of the user is possibly different than here. Therefore, **I ask all users who find a bug to report it to me** - if possible in connection with corresponding log files.
++++
----
{{anchor:cmx}}
++++ Set up a forward to CumulusMX (CMX) |
**Set up a forward to CumulusMX (CMX)**
CMX is a free, very nice and comprehensive software for visualising and storing the data of a local weather station. It supports many forwarding options and interfaces to other programmes and presents the data - web-based - clearly in a dashboard; offers visualised instruments and enables long-term archiving of the data. The integration of local weather data into own websites is also supported.\\ The user does not have to configure or adjust much himself - most of it works out of the box.\\ On a 24/7 running computer, this can be THE central weather station app.\\ More information and the link to download the CMX package can be found [[https://cumuluswiki.org/a/Software|here]].
CMX does not need to be installed for operation under Windows - it is sufficient to unpack the ZIP file in a folder and start the CumulusMX.exe there. The further configuration is then done via web browser using the link http:%%//%%ipaddress:8998 where ipaddress corresponds to the address of the computer on which CMX was started.
In CMX you only have to go through the configuration wizard from the settings menu (Settings/Config Wizard) and enter all mandatory values (e.g. lat/lon/alt/...) and select HTTP Upload (Ecowitt) as station type.
After restarting CMX (just press CTRL-C in the corresponding Dos window and restart CumulusMX.exe) CMX should be able to receive data from the weather station via FOSHKplugin (or directly from the station) and wait for incoming data.
Since CMX receives data in Ecowitt format, you only have to set up one (more) forward in Ecowitt format in the config file of FOSHKplugin foshkplugin.conf (FWD_TYPE EW or RAWEW):
[Forward-77]
FWD_TYPE = EW
FWD_CMT = CMX
FWD_URL = http://192.168.15.252:8998/station/ecowitt/
The IP address should be the address of the computer running CMX (in this example 192.168.15.252); the port is usually 8998 and the path should be /station/ecowitt.
Don't forget to restart the FOSHKplugin service afterwards, as all newly created forwards will only be activated when FOSHKplugin is started:
sudo service foshkplugin restart
In this way CMX should receive all data from the local weather station - with FOSHKplugin as middleman.
++++
----
{{anchor:fwdwarning}}
++++ be warned in case of failed forwards (from v0.10) |
**be warned in case of failed forwards (from v0.10)**
If you have configured dozens of forwards that are inconspicuously served by FOSHKplugin, it is quite interesting and sometimes also important to be informed in case of any (longer) failures. Because sometimes there are simply problems with the internet connection or with the weather service provider itself.\\ \\ FOSHKplugin writes a line to the log file snd-foshkplugin.log for each failed forward. But who looks there regularly and without reason?\\ \\ {{ :plugins:foshkplugin:screenshot_20221109-220155.png?200}} In order to still receive information relatively promptly if a forward destination is not reachable for a longer period of time, as of v0.10 there is the possibility to be informed via push notification (Pushover).\\ After a configurable number of successive unsuccessful attempts, a push message is sent:\\
FOSHKplugin
From FOSHKplugin on 2022-11-11 at 17:24
forward FWD-53 (INFLUX2MET - InfluxDB 2.x-Forward of metric values to LoxBerry) was unsuccessful 15 times since 11.11.2022 17:16:40
(last result: : Failed to establish a new connection: [Errno 113] No route to host)
* 192.168.15.237 for ws@192.168.15.221; 11.11.2022 17:24:53 *
Included are the forward designation (Forward-nn), the forward type (FWD_TYPE) and any forward comment (FWD_CMT) - together with the error message and the time of the last successful transmission.
This message is sent exactly ONCE after the number of failed attempts specified in the config file under Warning\FWD_WARNINT. The default value is 10.\\ With each successful attempt, the internal counter is reset - so you really only get a warning if the specified number of failed attempts occur after each other.\\ After a push message, another message is only generated for this forward if at least one forward was successful before and thus the internal counter was reset.\\ This function can be deactivated via Warning\FWD_WARNING = False in the config file.\\ As usual, however, this can also be deactivated at runtime via http (**//http:%%//%%ipaddress:portnumber/FOSHKplugin/fwdwarning=disable//**) or via UDP (Plugin.fwdwarning=disable) or activated via enable.\\ \\ Beside the global variable Warning\FWD_WARNINT that specifies the number of failed forwards before a warning is issued via push notification, an individual value can be configured in each forward with FWD_WARNINT. This setting overrides the global default for that specific forward and allows the warning to be disabled individually by setting FWD_WARNING = 0.\\ This way, the warning behaviour can optionally be configured separately for each forward.\\ \\ Counting starts whenever FOSHKplugin has been started - the former state will not be saved.
In addition, there is also a simple html page at **//http:%%//%%ipaddress:portnumner/FOSHKplugin/fwdstat//** that shows the status of all activated forwards. There you can see at a glance whether and since when a forward has been hanging and, if so, with what error message.\\ On this forward status page, different font colours show at a glance the status of the forwards: black: everything is ok, orange: the last forward was unsuccessful and red: the number of successive unsuccessful attempts exceeds the defined warning limit:\\
{{:plugins:foshkplugin:fwdstat1.png?800}}
++++
----
{{anchor:dt_format}}
++++ Adjust the output format for date and time (from v0.10) |
**Adjust the output format for date and time (from v0.10)**
The formatting of date and time in all outputs - such as CSV, LOG or even in the push notification - can now be adapted via the optional setting Config\DT_FORMAT in the Config file.\\ This can then be used to determine whether this should be output as 10.11.2022 17:34:20 or 10/11/2022 17:34:20 or 11/10/2022 05:34:20 pm or whatever.\\ \\ Here, the internal possibilities of the [[https://docs.python.org/3/library/time.html#time.strftime|time library in Python]] are simply used - for dd.mm.yyyy hh:mm:ss (as usual for Germany), one simply enters in the config file under [Config]:\\
[Config]
DT_FORMAT = %d.%m.%Y %H:%M:%S
However, this is also the default that is used with the existing configuration. For UK/US users, these variables must be swapped somewhat.\\ \\ Relevant directives are:\\
%d Day of the month as a decimal number [01,31].
%m Month as a decimal number [01,12].
%y Year without century as a decimal number [00,99].
%Y Year with century as a decimal number.
%H Hour (24-hour clock) as a decimal number [00,23].
%I Hour (12-hour clock) as a decimal number [01,12].
%p Locale’s equivalent of either AM or PM.
%M Minute as a decimal number [00,59].
%S Second as a decimal number [00,61].
++++
----
{{anchor:help}}
++++ get help from FOSHKplugin |
**get help from FOSHKplugin**
Documentation is always a nightmare.\\ Therefore, with v0.9 an internal help was implemented in FOSHKplugin, which can be called via web browser.\\ A help page is available at http:%%//%%ipaddress:portnumber/FOSHKplugin/help that summarises and explains all web commands for FOSHKplugin.\\ \\ {{:plugins:foshkplugin:help.png?800}}
An overview of the variable names that can be queried is available at **//http:%%//%%ipaddress:portnumber/FOSHKplugin/keyhelp//**.\\ This is especially interesting if you want to query individual values via http using getvalue.\\ \\ {{:plugins:foshkplugin:keyhelp.png?800}}
In addition, as of v0.10 there is also a simple web page that shows the status of all active forwards. There you can see at a glance whether and since when a forward has been hanging and, if so, with what error message.\\ This can be reached via **//http:%%//%%ipaddress:portnumber/FOSHKplugin/fwdstat//**.\\ \\ {{:plugins:foshkplugin:fwdstat1.png?800}}
++++
----
{{anchor:queue}}
++++ store missed forwards and transfer them when the forward destination is available again (from v0.10) |
**store missed forwards and transfer them when the forward destination is available again (from v0.10)**
Basically, the weather station sends the data to FOSHKplugin, which receives the data, processes it and forwards it to the configured destinations in the appropriate format.\\ \\ If a destination cannot be reached, FOSHKplugin tries several times to deliver the data after all. If this does not succeed even after 3 attempts (each with a pause of 6 seconds longer), the data is discarded. This results in gaps in the data recording at the corresponding destination, which is annoying to say the least.\\ \\ Reasons for non-accessibility can be a failure of the connection (Internet, LAN cable, WIFI-AP) or a (temporary) failure or maintenance of the server of the target system.\\ \\ Very few weather services support the subsequent sending of data - they ignore the time contained in the data set (such as dateutc) and instead use the time of receipt of the data for temporal assignment.\\ With these systems, subsequent sending is therefore not possible - the current weather data would thus be overwritten with outdated values.\\ \\ InfluxDB (both v1 and v2) use the time that is transferred with the data set instead. Thus, resends and resulting gapless records are possible here. FOSHKplugin stores failed forwards to these forward targets (INFLUXMET, INFLUXIMP, INFLUX2MET, INFLUX2IMP) temporarily and resends the data automatically when the remote station is reachable. This behaviour can be deactivated individually for each forward in the config file:\\ \\ **FWD_QUEUE = False**\\ \\ For each data set, a file FOSHKplugin-queue\FWD-nn\FOSHKplugin-queued-data-nn.YYMMDDhhmmss is created in the directory of the Conf-File of FOSHKplugin, which is deleted after sending. The directory for saving these queue files can be set via\\ \\ **FWD_QDIR = /path/to/store/queue-files/**\\ \\ in the corresponding forward block.\\ \\ Awekas at least offers a manual import option for the basic data - an Excel file in the specified format can be uploaded via a web form. FOSHKplugin can at least make the creation of this Excel file a little easier by saving the data in the correct order as a CSV. The CSV can then be opened with Excel and saved as XLSX to allow the easy import into Awekas.\\ Queuing for the forward type AWEKAS is activated by default. With one line\\ \\ **FWD_QUEUE = False**\\ \\ in the forward block, the generation of the CSV FOSHKplugin-queued-data-nn.csv can be deactivated. Here, too, the following can be specified\\ \\ **FWD_QDIR = /path/to/store/queue-files/**\\ \\ so that the file can also be accessed via file access (Samba).\\ Instructions for creating the Excel file can be found on the [[https://www.awekas.at/wp/daten-import-und-export/|Awekas website]].\\ \\ Currently, the queue formats CMX and EW are supported in the forward type (FWD_TYPE) EW and RAWEW as output format in case of an impossible dispatch. CMX creates an accumulating file in the structure of a REALTIME.TXT, which unfortunately cannot be imported into CumulusMX yet:\\ \\ **FWD_QUEUE = CMX**\\ \\ The EW format is also experimental only (because it is not yet usable):\\ \\ **FWD_QUEUE = EW** \\ where each record is saved in Ecowitt format in a separate file. Here, too, you can configure an output directory for these file(s) by specifying FWD_QDIR.\\ \\ Other queue functions are currently not implemented.\\ However, as soon as I learn of other queue-enabled services or useful formats for queuing, I can implement them.\\ If you have any ideas or suggestions, please feel free to share them.\\
++++
----
{{anchor:wsscan}}
++++ scan all weather stations in your network (from v0.10) |
**scan all weather stations in your network (from v0.10)**
For all those who use several weather stations locally, FOSHKplugin from v0.10 on offers a new feature for web-based searches.\\ With the URL http%%//ipaddress%%port/FOSHKplugin/scanWS, all consoles accessible in the network segment are searched for via usual UDP broadcast and displayed as an overview page:\\ \\ {{:plugins:foshkplugin:scanws.png?600}}\\ \\ A click on the displayed ipaddress then leads directly to the WebUI of the console in question in a new browser tab - provided this console has a WebUI.\\ \\ If I am unsure whether all consoles in the network are accessible or whether one has hung up, I use this option. Or if I need the MAC address for any API attempts. \\
++++
----
{{anchor:pocustom}}
++++ custom push notifications (from v0.10) |
**custom push notifications (from v0.10)**
With v0.10 there is the possibility to create own push notifications based on the values received or calculated by FOSHKplugin.\\ \\ For each data set coming from the weather station, it is checked whether there is a reason for a warning via push notification.\\ The reason for a notification is the exceeding/falling below of the defined value range as well as the fact that no notification has yet been sent for this rule within a configurable time (hold time).\\ \\ If this is the case, a message is sent and the time at which this notification was sent is logged (to prevent this message from being sent again and again).\\ \\ With the next incoming data record, it is checked whether the configurable hold time has been exceeded and whether the value in question is outside the defined limit. However, there is only a (further) warning if the hold time has been exceeded; the hold time starts again from the beginning if there is a setpoint overrun/underrun.\\ \\ The rules for the user-defined pushover messages are stored in the Config file in the [Pushover] area and correspond to this structure:\\
PO_CUSTOMn = @key [<,<=,==,>,>=,<>,!=] value,message text,activation,hold time.
The n for variable PO_CUSTOMn corresponds to a number from 1 to 99. Thus, a maximum of 99 rules can be configured.\\ \\ The individual columns are separated by a comma. If a comma is required in the message text itself, it must be escaped with the character "\".\\ The comparison value may also be a key - this is then specified with @keyname.\\ The fields message text, activation and hold time are optional and are provided with the default values if not specified.\\ These defaults are:
message text: "condition "condition" is given!" (condition corresponds to the comparison formula - for example @rainin > 0.55)
activation: True (thus this rule can also be deactivated with False if required)
hold time: 3600 (this corresponds to 1 hour)
Only simple constructs are possible as a formula. A concatenation or more complex calculations is not intended.\\ The formula therefore always has the structure @key OPERATOR value. **The spaces between the individual components of the condition are mandatory!**\\ An attempt is always made to perform a numerical comparison first. If this is not successful, a string comparison (case-sensitive) is carried out instead.\\ Supported operators are <, <=, ==, =, >, >=, <> and != (whereby "=" and "==" as well as "<>" and "!=" are interpreted identically).\\ \\ All keys recognised or generated by FOSHKplugin can be used for comparisons - both metric and imperial values and minmax values. Only the status messages cannot be used because they generate their own notifications.\\ A list of all keys that can be used at runtime can be called up via a web browser at the address [[http://ipaddress:port/FOSHKplugin/keyhelp]] - where ipaddress is the IP address of the host on which FOSHKplugin is running and port is the corresponding port.\\ \\ If desired, the actual value can be sent in the message text with @value - before sending, @value is replaced by the measured value. The comparison value (i.e. the value after the operator) can be output in the message text with @comp. Please note that the "#" character cannot be used in the message text under any circumstances because it defines a comment. If you need the hash just replace it with a "$" - FOSHKplugin will convert it to a hash "#". The text colour can be defined within the message text with the usual html tag text. "color" corresponds to the html colours as a name (red, blue, green etc.) or as hex notation (see [[https://en.wikipedia.org/wiki/Web_colors]]). Please note that the hash character "#" cannot be used - use the dollar sign "$" instead. \\ \\ Examples:
PO_CUSTOM1 = @tempc <= 2.5,Current temperature (@value°C) is equal or below 2.5°C!,False,3600
PO_CUSTOM2 = @tempf < 32,Current temperature (@value°F) is below 32°F!,True,86400
PO_CUSTOM6 = @stationtype != GW1000A_V1.7.5,Update detected\, former version was v1.7.5 - now it's @value!
PO_CUSTOM99 = @tempc <= @dewptc,Temperature (@value°C) is lower than Dewpoint (@comp°C)!,True
PO_CUSTOM51 = @temp1c < @temp2c,Temperature of WH31 $1 (@value°C) is lower than WH31 $2 (@comp°C)!,True
A few final notes:\\ Pushover (global) as well as the custom warnings (only) can be activated and deactivated at runtime via web command and UDP. However, the current status and the hold time are not remanent - when FOSHKplugin is restarted, the configuration options stored in the config file become valid again. This control option therefore only serves to temporarily change the status.\\ \\ The http command to activate/deactivate the custom warnings is [[http://ipaddress:port/FOSHKplugin/customwaring=enable]] or disable (where ipaddress is the IP address of the host on which FOSHKplugin is running and port is the corresponding port).\\ Each push notification contains a link to the online help of FOSHKplugin - from there, the custom warning can be easily switched off for the rest of the runtime.\\ \\ A temporary (de)activation is also possible via UDP at runtime using the UDP command Plugin.customwarning=enable or disable.\\
++++
----
{{anchor:banner}}
++++ Creation of banners and stickers (from v0.10) |
**Creation of banners and stickers (from v0.10)**
As a additional forward type (FWD_TYPE) the type BANNER was introduced in v0.10. With this type, images (PNG/JPG/GIF) can be created in which weather data (values) from FOSHKplugin can be embedded:\\
{{:plugins:foshkplugin:banner-green.png}}
The generated images can be stored in the file system or sent to a remote server via FTP or http/POST. There, they can be accessed from anywhere, integrated into your own web pages or used as footers in any forum postings (if allowed).\\ So if you want to display your weather data on your own homepage, you don't have to go the complicated way of sending the data to the web server and having it processed by a server-specific read-in script.\\ One simply defines an image on the homepage that is automatically exchanged without further programming knowledge - in each case with the current data of the weather station. No further adjustments are necessary for the various CMSs; Joomla, Wordpress, Typo3 etc. simply display an image that updates itself.\\ \\ These images can have an existing image but also a definable colour as background. This colour can also be transparent, so that only the text of the image is visible and the original background remains. With the option rounded_corners = True you can create rounded corners in the image formats PNG and GIF - regardless of whether the background is an image or a colour. The radius of the rounding can be specified with the corresponding number instead of True. In the standard (True), the value 10 is taken, which corresponds to a small radius and thus a small rounding.\\ \\ Any image objects (such as logos) can be positioned within the banner.\\ These logos can also be output specifically depending on certain values. This opens up interesting possibilities for "dynamic" banners.\\ An example:\\ There is the FOSHKplugin-internal key wnowlvl, which outputs the current weather situation based on the air pressure. We don't need to discuss the quality of this statement - but here it provides a nice visual example.\\ According to the definition - depending on the weather situation - the following codes are output:\\ \\ wnowlvl = 0 --> stormy, rain\\ wnowlvl = 1 --> rainy\\ wnowlvl = 2 --> changeable\\ wnowlvl = 3 --> sunny\\ wnowlvl = 4 --> dry, thunderstorm\\ \\ In the logo configuration of the banner defnition, you can now define that a different logo is used for each individual status:\\
logo_1 = 10,100,storm.png,@wnowlvl = 0
logo_2 = 10,100,rain.png,@wnowlvl = 1
logo_3 = 10,100,change.png,@wnowlvl = 2
logo_4 = 10,100,sun.png,@wnowlvl = 3
logo_5 = 10,100,tstorm.png,@wnowlvl = 4
Thus, different images (defined in the 3rd column) are displayed depending on the data!\\ The 4th column of the logo lines is used to determine whether the logo is shown in the banner. If this column is missing or empty, the logo is integrated into the banner.\\ Otherwise, FOSHKplugin checks the content of the 4th column for validity. Fields to be queried are marked with an "@". You can also compare a field with another field, for example @temp1f <= @tempf.\\ \\ Permissible operators are: [<,<=,==,>,>=,<>,!=]\\ Only if the check is successful, the logo is included in the banner.\\ \\ These queries can be used to display a specific logo in the special cases of an empty value or a key that does not exist:
logo_6 = 10,100,emptyvalue.png,@wnowlvl = # empty value
logo_7 = 10,100,dontexist.png,@wnowlvl = null # key does not exist
With the options pre_count and dec_count, the length of the (dynamic) output string (pre_count) and the number of digits after the decimal point (incl. rounding) can be defined for each line type. This leads to a better positioning of the output values, should it be necessary.\\ \\ All FOSHKplugin-internal values can be used for integration into the image - thus values with metric or imperial units can be output (also simultaneously).\\ Access to internal status values of FOSHKplugin as well as min/max values is also possible. In addition to the keys displayed under http:%%//%%ipaddress:port/FOSHKplugin/keyhelp, the following keys can also be processed for banners & stickers:\\ \\ prgname --> program name (FOSHKplugin)\\ prgver --> program version (v0.10)\\ winddir_text --> wind direction as string like "N", "NNE", "NE", "ENE", "E", "ESE", "SE", "SSE", "S", "SSW", "SW", "WSW", "W", "WNW", "NW", "NNW" or the German abbreviations for them\\ pchange1in --> change of air pressure within the last hour in inHg (pchange1 displays this in hPa)\\ pchange3in --> change of air pressure within the last 3 hours in inHg (pchange3 displays it in hPa)\\ lightningmi --> distance of last lightning in miles (instead of km)\\ \\ Special characters such as German umlauts can be used - provided the font used supports them. A special character, however, is the comma ",". Since this is used within the configuration to separate the individual fields, it must be escaped as a string with a backslash: "," thus becomes "\,".\\ Examples of this can be found on the banner demo page specially set up for this purpose: [[https://foshkplugin.phantasoft.de/banner]].\\ \\ The embedding of the values is based on a positioning of rows per y-coordinate, which contain individual columns that can be positioned per x-coordinate. The number of rows (per type) and columns is limited to 100.\\ For each image, 10 (!) different fonts with different font, size and colour can be used: Header, Line, Footer, Special and Custom, Custom1..5. The names are only a distinguishing feature, the contents are shaped by the definition.\\ Overlapping of fonts is possible without any problems, as each line is positioned in the area of the background by x,y coordinates.\\ \\ The availability of fonts depends on many factors: Linux distribution, installed software, manually installed fonts.\\ The command\\
sudo ls -laR /usr/share/fonts/truetype/
should display all existing fonts in the system. These file names should then also be usable as font names. If necessary, however, additional fonts (even the Microsoft fonts) can be installed. A few hints on installing the fonts can be found below. If the defined font is not found, the system falls back to DejaVuSansMono.ttf.\\ \\ The font size to be used depends primarily on the size of the image in which you want to integrate your text. A very large font naturally requires a very large image. When it comes to banners or stickers, the images are rather small and then naturally require a smaller font size. However, it would not be a problem to add pictures of your own webcam with the data of your own weather station.\\ \\ When specifying the colour definition for fonts and also backgrounds, most colour names such as black, red, yellow, green, ... but also colour specifications in html notation can be configured. When specifying the html notation, however, the "$" must be entered instead of the character "#".\\ \\ There is a predefined variable $datetime that "stamps" the local time of image creation into the image in a definable format ([[https://www.w3schools.com/python/python_datetime.asp|Python-like]]: "%d.%m.%Y %H:%M:%S" or "%y/%m/%d %I:%M %p"). The output language of the months and weekdays can be set to German via locale_format = de_DE.UTF-8 or to US English (or any other installed locale) via locale_format = en_US.UTF-8 in the banner configuration file. The language packages installed in the Linux system that can be entered here can be displayed with the command\\
sudo locale -a
In the FOSHKplugin configuration file foshkplugin.conf, a usual forward with a unique number of the type "BANNER" (FWD_TYPE = BANNER) is to be created.\\ The actual banner configuration file is specified as FWD_OPTION with bannerconfig=configname.conf. This separation into FOSHKplugin configuration file and banner definition has the advantage that the banner can also be adapted at runtime by FOSHKplugin. Especially in the development of a banner, several attempts are usually necessary to position the banner components perfectly or to select the "right" font.\\ This can be done without having to restart FOSHKplugin each time.\\ Note that FWD_URL contains the destination where the generated image file is to be stored via http/POST or FTP - the actual file name is defined in the banner configuration. The access data required for the upload are defined with FWD_SID and FWD_PWD.\\ Even if the output file is intended for upload - a local file is always (!) created first, which is specified with image_name in the banner configuration.\\ Please also consider that without specifying a specific FWD_INTERVAL, a corresponding banner will be generated for EVERY input of data from the weather station. For example, if the weather station transmits at 16-second intervals, a new banner image will be generated every 16 seconds (!) and - if configured - uploaded to the upload destination. This can cause considerable traffic!\\ You should find a good balance between the timeliness of the banner images and the traffic. 60 seconds (FWD_INTERVAL = 60) should be sufficient. But 5 minutes (i.e. 300 seconds - FWD_INTERVAL = 300) can certainly still be called up-to-date.\\ \\ A forward would look like this in foshkplugin.conf, for example:\\
[Forward-19]
FWD_ENABLE = True # you may disable the forward instead of deleting
FWD_CMT = Banner-Test Simple # comment field - for your info
FWD_OPTION = bannerconfig=banner-simple.conf # file with banner definition: bannerconfig=/path/to/configfile
FWD_URL = ftps://my.domain.tld/httpdocs/img/ # you may specify a local path, a ftp or http address
FWD_INTERVAL = 60 # in seconds - if not specified a banner image will be created/sent on every weather station interval
FWD_IGNORE = # not really usefull in the BANNER context
FWD_TYPE = BANNER # use BANNER for creating banners/stickers
FWD_SID = ftpuser # user name for ftp/http access
FWD_PWD = ftppasswd # password for uploading via ftp/http
FWD_EXEC = # a script to be started before image creation - e.g. to add custom key=value entries
And the banner definition in banner-simple.conf then as follows:\\
[Banner]
# this is just a demo banner definition to see the syntax and possibilities
# there are 10 definable fonts: header, line, special, footer, custom, custom1, custom2, custom3, custom4 and custom5
# each font definition contains information on font, colour, size, decimal places (dec_count) and string length (pre_count)
# you may specify up to 100 lines (n) per font definition, where y=Y-coordinate, X-coordinate for name, name, position for value, value and unit
# each line may contain up to 100 coloumns containing the position of the text, the text itself as well as the position of the value, the value and the unit
# fontdefinition_n = y,key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni
image_name = banner-simple.png # file name of output image - may be gif, png, jpg, ... and may contain a path
image_width = 300 # only valid if no image is selected as background
image_height = 100 # only valid if no image is selected as background
image_background = white # may be transparent, any color, http color code (with $ instead of #) or a filename of an image file
dtime_format = "%y/%m/%d %I:%M %p" # use "%d.%m.%Y %H:%M:%S" for european 24h display - Python like - see https://www.w3schools.com/python/python_datetime.asp
locale_format = "de_DE.utf8" # use en_US.utf8 for English terms in dates
rounded_corners = True # rounded corners; available for png/gif only, you may specify the radius by n instead of True (default: 10)
border_width = 0 # width of the border in pixels
border_color = black # may be any color name or http colorcode (with $ instead of #)
#logo_1 = y,x,name
logo_1 = 10,250,foshkplugin.png # define logo file name and position - y,y,name - up to 100 logos possible
header_font_name = verdana.ttf # if the specified font is not available the standard font DejaVuSansMono.ttf will be used
header_font_color = blue # may be any color name or the http color code (use $ instead of #)
header_font_size = 8 # size in pixel
#header_1 = y,key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni
header_1 = 0,10,$datetime,,,,,,,, # header_0..99 - 100 possible lines with header definition; $datetime uses the current local time
header_pre_count = # length of the output value - padded with spaces if necessary
header_dec_count = # default of decimal places - will be rounded
header_dtime_format = # uses the format defined here for time/date outputs of this font (see dtime_format in the global assignment).
line_font_name = verdanab.ttf
line_font_color = black
line_font_size = 14
#line_1 = y,key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni
line_1 = 15,10,Temperatur:,140,tempc, °C,,,,,,,,,,
line_2 = 35,10,Luftfeuchte:,140,humidity, %,,,,,,,,,,
line_3 = 55,10,Luftdruck:,140,baromrelhpa, hPa,,,,,,,,,,
footer_font_name = verdana.ttf
footer_font_color = black
footer_font_size = 16
#footer_1 = y, key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni
footer_1 = 80,10,Hohen Neuendorf\, Germany,,,,,,,,
special_font_name = verdana.ttf
special_font_color = black
special_font_size = 16
#special_1 = y, key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni
#special_1 = 80,10,Hohen Neuendorf\, Germany,,,,,,,,
custom_font_name = verdana.ttf
custom_font_color = black
custom_font_size = 16
#custom_1 = y,key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni, key_pos,key,val_pos,value,uni
For testing purposes and as an overview, there is an http overview page that can be reached at http:%%//%%ipaddress:port/FOSHKplugin/banner. All images generated by existing conf files (with [Banner] stanza) are displayed there.\\ Each of the images displayed contains a link to the actual image. There are two different links - image and config. image simply displays the image generated by the given interval (FWD_INTERVAL); config generates a new image every time it is called and displays it - but it is not sent to the destination via ftp/http outside the usual interval.\\ \\ For creating and optimising banners, it is recommended to start the web page in the background with the banner to be created and a refresh (add &refresh=2 to the URL) and to edit the actual conf file in the foreground - this way you can see the changes made immediately and can position the individual elements very easily.\\ In the case of transparent banners or also to evaluate the effect of the colouring, the background colour of the web page can be changed with adding &background=grey (or any html colour code - where the "#" character must be replaced by "$") to the URL.\\ \\ Even if there are problems with incorrect assignments, missing logos or fonts, FOSHKplugin always tries to generate the appropriate image. For the wrong or faulty components, a warning is given in the snd-foshkplugin.log.\\ Common problems are missing fonts or logos or backgrounds to be embedded. Also the wrong specification of colours for background and font can lead to warnings or not expected results due to the changed syntax ($ instead of #) or typos in the colour definition.\\ However, these problems should be solved quickly with the tips in the log file and this description.\\ \\ **Problem solving:**\\ If, despite specifying the desired locale (locale_format), the weekdays or months are still not displayed in the expected language, this locale must first be installed. On Debian-based systems, this is done by ticking the corresponding locale after calling
sudo dpkg-reconfigure locales
.
**Additional notes:**\\ Font compatibility:\\ [[https://www.linux-magazine.com/Online/Blogs/Off-the-Beat-Bruce-Byfield-s-Blog/Free-equivalents-for-standard-proprietary-fonts]]\\ \\ Microsoft fonts:\\ [[https://itsfoss.com/install-microsoft-fonts-ubuntu/]]\\ \\ free DejaVu fonts:\\ [[https://dejavu-fonts.github.io/]]\\ \\ free Logos:\\ Free (public domain) logos for integration into your own banners can be found [[https://pictogrammers.com/library/mdi/|here]]. These images can be downloaded in any resolution and colour.\\ Google also has an extensive collection of [[https://fonts.google.com/|fonts]] and [[https://fonts.google.com/icons|icons]] that may be used free of charge.\\ Freely usable background founders for banners can be found at [[https://www.pexels.com|Pexels]] or [[unsplash.com|Unsplash]], among others.\\ \\ Some more free icons can be found here:\\ [[https://github.com/roe-dl/weathericons]]\\ [[https://www.dwd.de/DE/wetter/warnungen_aktuell/objekt_einbindung/piktogramm_node.html]]\\ [[https://erikflowers.github.io/weather-icons/]]\\ \\ **However, you should always make sure that the fonts, icons, logos and backgrounds used can be used legally. I assume no liability!**
++++
----
{{anchor:tagfile}}
++++ Definition of user-defined output formats - TAGFILE (from v0.10) |
**Definition of user-defined output formats - TAGFILE (from v0.10)**
For formats that are not (yet) natively supported by FOSHKplugin itself, with v0.10 there is a practicable solution for user-defined output formats with the TAGFILE-Forward.\\ Here, placeholders within a file - so-called tags - are replaced by FOSHKplugin with the actual values of the weather station.\\ \\ Example:\\ The (fictitious) weather service blaWeather would like to have the data transmitted in a custom line-oriented file format - where the first line must contain the outdoor temperature (metric), the second line the minimum temperature as well as the time of the minimum temperature, and the 3rd line the maximum temperature as well as its time:\\
tempc
tempc_min,tempc_min_time
tempc_max,tempc_max_time
However, FOSHKplugin does not natively support the output in this format. With a TAGFILE forward, however, this can be solved very easily!\\ You create a template file with the corresponding structure and the appropriate field assignment:\\
[[@tempc]]
[[@tempc_min]],[[@tempc_min_time]]
[[@tempc_max]],[[@tempc_max_time]]
and a TAGFILE forward and thus FOSHKplugin sends the generated file at the selected interval via http(s)/GET or http(s)/POST or via FTP(S).\\ \\ If you want to integrate your own web pages via iframe or provide complex web pages with current data of the weather station, you can do this as well.\\ The tag definition is user-defined (per forward) - so you can also use an http comment like . As long as FOSHKplugin has not replaced the tags, they are not visible on the html page.\\ However, when FOSHKplugin generates the page, the corresponding values are then included instead of these html comments. In the definition, @keyname must be included; however, in the template file, keyname has to be replaced by the desired key. A list of all usable keys can be queried at any time via http:%%//%%ipaddress:port/FOSHKplugin/keyhelp - where ipaddress and port correspond to the host and port on which FOSHKplugin is running.\\ \\ The website can be as complex as you like. I have put a simple example for demonstration [[https://foshkplugin.phantasoft.de/tagfile|here]]. The page with the measured values is automatically created by FOSHKplugin and stored on the web server via FTPS.\\ \\ Storing in the file system (as well as on a remote server) as a growing file (e.g. CSV file) is also possible without any problems thanks to the append function.\\ The TAGFILE function is not limited to files - weather services can also be supplied with data in the desired format directly via http/GET or http/POST.\\ \\ **Important!**\\ The tag definition is REPLACED by FOSHKplugin in the output file. In this respect, the tag definition must be unique and must not occur in the normal file content!\\ In addition, it should be noted that the hash character "#" cannot be used in the tags - it is recognised as a comment prefix and all characters behind it are ignored.\\ \\ As usual, the basis is a forward definition in foshkplugin.conf, in which the tag definition file is specified within the FWD_OPTION line:\\
[Forward-29]
FWD_ENABLE = True # you may disable the forward instead of deleting
FWD_CMT = TAGFILE-Test tag-definition # comment field - for your info
FWD_OPTION = config=tag-definition.conf # file with tag definition: config=/path/to/configfile
FWD_URL = ftps://my.domain.tld/httpdocs/img/ # you may specify a local path, a ftp or http address
FWD_INTERVAL = 60 # in seconds - if not specified a forward will be executed/sent on every weather station interval
FWD_IGNORE = # not really usefull in the TAGFILE context
FWD_TYPE = TAGFILE # use TAGFILE for creating tagged files
FWD_SID = ftpuser # user name for ftp/http access
FWD_PWD = ftppasswd # password for uploading via ftp/http
FWD_EXEC = # a script to be started before saving the output - e.g. to add custom key=value entries
Here, with config=tag-definition.conf in the FWD_OPTION line, the tag-definition.conf file is stored as the tag definition. Note! On LoxBerry, you have to use absolute paths here for the config-option! Relative paths will not work!\\ As with the BANNER forward, we also use a second definition file here to allow changes to the definitions during the runtime of FOSHKplugin.\\ \\ In the tag-definition file there are a few necessary configuration points and several optional setting options for the tag definition:\\
infile = # mandatory! - name of the template file with embedded tags (default: "")
outfile = # name of the final output file (default: "")
append = False # determines whether outfile is overwritten or appended in each interval (default: False)
task = save # sets final processing - SAVE for writing a file, GET for sending via http(s)/GET, and POST for sending via http/POST (default: save)
tag = [[@keyname]] # defines the structure of the tag - this type of string is searched for in the infile and replaced with the corresponding value (default: )
postscript = # possibility to specify a bash script to be started after saving the output file but before sending it (default: "")
dtime_format = # sets output format for values with a date/time - use "%d.%m.%Y %H:%M:%S" for european 24h display - Python like - see https://www.w3schools.com/python/python_datetime.asp (default: %d.%m.%Y %H:%M:%S)
locale_format = # defines the language of the names of the weekdays and months - use en_US.utf8 for English terms in dates (default: "")
pre_count = # length of the output value - padded with spaces if necessary (default: "")
pre_fill = # string to prepend (default: space) - could be for html files
dec_count = # number of decimal places (default: "" = as is)
dec_separator default = # you may define a comma as a decimal separator (default: .)
If set, the specifications of the tag definition override those of the settings configurable under the same name in FWD_OPTION (separated by commas).\\ \\ The file defined in the tag definition per infile is the template that defines the output format with the positions of the values of the weather station:\\
time;aqtime;temperature;temp min;temp min time;temp max;temp max time;humidity;pressure;pressure min;pressure min time;pressure max;pressure max time
[[@time]];[[@aqtime]];[[@tempc]];[[@tempc_min]];[[@tempc_min_time]];[[@tempc_max]];[[@tempc_max_time]];[[@humidity]];[[@baromrelhpa]];[[@baromrelhpa_min]];[[@baromrelhpa_min_time]];[[@baromrelhpa_max]];[[@baromrelhpa_max_time]]
Note! On LoxBerry, you have to use absolute paths here for infile and outfile! Relative paths will not work! So in the context of the TAGFILE forward, 3 files are relevant:\\
* foshkplugin.conf - definition of the actual forward, the interval, the destination for sending the data and the specification of the file name of the tag definition (FWD_OPTION = config=tagdefinition).
* a file of any name (here in the example: tag-definition.conf) in which the assignment of the tag definitions as well as the specification of the output file name is made.
* a template file with the structure of the target file and the placeholders for the weather station data (infile)
In order not to get confused with this multitude of files, I recommend as a best practice: name the template file *.template and the tag definition file *.tagdef.
Another example to illustrate the TAGFILE function can be found [[https://foshkplugin.phantasoft.de/tagfile/index-pool.html|here]] with the pool web page automatically generated by FOSHKplugin. It combines the multiple wishes for user-specific and "large" values as a web page and can thus be used as a template for own solutions. The three configuration files required for this forward are:\\ \\ Entry in foshkplugin.conf:\\
[Forward-38]
FWD_ENABLE = True
FWD_CMT = TAGFILE Pool via FTP
FWD_URL = ftps://foshkplugin.phantasoft.de/httpdocs/foshkplugin.phantasoft.de/tagfile/
FWD_OPTION = config=tag-pool.conf
FWD_INTERVAL = 60
FWD_IGNORE =
FWD_TYPE = TAGFILE
FWD_SID = ftp-username
FWD_PWD = ftp-password
FWD_EXEC =
The TAG configuration of config=tag-pool.conf:
[Tagfile]
infile = tag-pool.template
outfile = index-pool.html
append = False
task = POST
tag =
locale_format = de_DE.UTF-8
postscript =
dtime_format = %d.%m.%y %H:%M:%S
pre_count = 4
pre_fill =
dec_count = 1
dec_separator = .
And finally the template file tag-pool.template:
FOSHKplugin v0.10 TAGFILE demo
FOSHKplugin v0.10 TAGFILE demo
Außen
°C
▼ °C,
▲ °C,
Pool
°C
▼ °C,
▲ °C,
If you have a good knowledge of html and CSS, you can use this function to generate attractive static pages that are permanently updated by the refresh function. And all this without any complex server configuration or PHP scripts - it is simply a web page.
Sometimes it is not enough to just display the values of fields - i.e. @keyname - these may need to be modified beforehand.\\ FOSHKplugin has implemented a few commands (function blocks) for such special cases, which modify the values before replacing the tags.\\ Within the tags, a function block is enclosed in square brackets []. Parameters within the functions are separated by commas.\\ \\ These commands are currently implemented:\\ \\ **substr/copy**\\ only outputs part of the output string; the character count starts at 1\\ Call: substr(@keyname,startposition,count of chars)\\ \\ **round**\\ rounds the value and reduces the decimal places if necessary; if there are 0 decimal places, the value is rounded and output as an integer\\ Call: round(@keyname,number of decimal places)\\ \\ **replace**\\ replaces any character string "what" in the value of keyname with the character string "with"\\ Call: replace(@keyname,what,with)\\ \\ **fillleft**\\ inserts as many characters "with" at the end of the value until the value of keyname corresponds to the length "len"\\ Call: fillleft(@keyname,with,len)\\ \\ **fillright**\\ inserts as many characters "with" before the value of keyname until it corresponds to the length "len"\\ Call: fillright(@keyname,with,len)\\ \\ **addleft**\\ inserts a number "count" of the character "with" to the left of the value of keyname\\ Call: addleft(@keyname,with,count)\\ \\ **addright**\\ inserts a number "count" of the character "with" to the right of the value of the keyname\\ Call: addright(@keyname,with,count)\\ \\ **strip**\\ removes spaces at the beginning and end of the output string of keyname\\ Call: strip(@keyname)\\ \\ **concat**\\ joins any number of substrings to form an output string\\ Call: concat(str1,str2,str3)\\ \\ **dtime**\\ converts a Unix timestamp into a defined human-readable format (format - corresponds to Python notation - see [[https://www.w3schools.com/python/python_datetime.asp]])\\ Call: dtime(@keyname,format)\\ \\ **tdiff**\\ converts a number of seconds in keyname to days, hh:mm:ss where the format can be specified with format (e.g. %j days %H:%M:%S)\\ Call: tdiff(@keyname,format)\\ \\ **onempty**\\ replaces an empty return value with the specified string\\ Call: onempty(@keyname,string)\\ \\ **onvalue**\\ appends the string "string" if the return value is not empty\\ Call: onvalue(@keyname,string)\\ \\ **dewptF**\\ Calculates the dew point in °F for an imperial temperature value @keyname-temp based on the specified humidity value @keyname-humidity\\ Call: dewptf(@keyname-temp,@keyname-humidity)\\ \\ **dewptC**\\ Calculates the dew point in °C for a metric temperature value @keyname-temp based on the specified humidity value @keyname-humidity\\ Call: dewptc(@keyname-temp,@keyname-humidity)\\ \\ **if**\\ string "then" or "else" is output depending on the comparison between two operands (e.g. @keyname) with an operator\\ Call: if(@keyname,operator,@keyname,then,else)\\ Operators are "<", "<=", "==", ">=", ">" and "!="\\ \\ **eval**\\ Simple basic arithmetic function of two operands with one operator ("+","-", "*","/"); the non-rounded result of the calculation is output\\ Call: eval(@keyname,operator,@keyname)\\ \\ Example:\\ Suppose your tag for the indoor temperature looks like this:
data12 [[@tempinf]]
and the value of tempinf is to be multiplied by 100, then the tag should be
data12 [[@[eval(@tempinf,*,100)]]]
The functions can also be nested - so you can also use combinations of functions. However, the correct bracketing and the order of the functions must be observed.\\ Examples:\\ concat(@lightning_time," oOo ",copy(@lightning_time,1,10)," oOo ",copy(@lightning_time,12,10))\\ fillleft(substr(@model,1,3)," ",20)\\ onEmpty(onValue(Round(@soilmoisture8,0),"%"), "n.a.")\\ \\ \\ \\ To implement such a function block into e.g. web page just use the configure tag definition e.g. \\ I have published another example of the TAGFILE function including the additional functions [[https://foshkplugin.phantasoft.de/tagfile/tag-dewpoint.html|here]].\\ The necessary adjustments in the config file and the tagfile definitions can be downloaded as a ZIP package [[https://foshkplugin.phantasoft.de/files/tag-dewpoint.zip|here]]. \\ The basic settings pre_count, pre_fill, dec_count and dec_separator defined in the tag configuration are ignored in the functions, as these are defined in the functions.\\ \\
[Forward-33]
FWD_CMT = sending to Ecowitt.net with adjusted PASSKEY
FWD_SID = 000102030405060708090A0B0C0D0E0F
FWD_IGNORE =
FWD_INTERVAL = 60
FWD_TYPE = EW
FWD_URL = http://cdnrtpdate.ecowitt.net/data/report/
FWD_ENABLE = True
Similarly, a console that transmits to Ambient Weather can also be replaced. If the previous MAC address was 00:01:02:03:04:05, this must be entered as FWD_SID in a forward in Ambient Weather format:\\
[Forward-44]
FWD_CMT = Forward to Ambient Weather
FWD_SID = 00:01:02:03:04:05
FWD_IGNORE =
FWD_INTERVAL = 60
FWD_TYPE = AMB
FWD_URL = https://api.ambientweather.net/endpoint?
FWD_ENABLE = True
++++
----
{{anchor:afterinstall}}
++++ First steps after installing FOSHKplugin |
**First steps after installing FOSHKplugin**
Normally you install FOSHKplugin for a specific reason - for example, because you want to send data to a destination (weather service) that is not supported by the weather station hardware.\\ The installation is usually done quite quickly and the recipe suitable for the purpose is quickly found and entered as a forward.\\ However, there are a few more things that are necessary or at least helpful after installing FOSHKplugin and configuring the forward.\\ \\ I recommend going through the configuration file foshkplugin.conf or foshkplugin.conf.orig (which contains a few notes on the configuration items) line by line.\\ The configuration options entered in the foshkplugin.conf file are decisive for FOSHKplugin - foshkplugin.conf.orig is used exclusively for documentation purposes.\\ \\ In the **Config** section, this mainly concerns the items USE_METRIC, UDP_ENABLE, DT_FORMAT and LANGUAGE.\\ I live in the metric world - therefore the output is provided in metric values by default. The imperial measurement system can be selected with USE_METRIC = False.\\ If you want to reduce data traffic in the local network, you should deactivate the UDP transmission of the values with UDP_ENABLE = False, unless this is necessary.\\ And if you do not want weather status messages in German, the output language can be defined under LANGUAGE. EN, NL, SK, FR and ES are currently supported.\\ The output format for date and time can be customised using DT_FORMAT.\\ \\ In the **Warning** section, I recommend taking a look at the SENSOR_MANDATORY configuration item. All keys that must be present for incoming data from the weather station are entered here. If one of these keys is missing, a warning is issued.\\ This can be used to detect and alert the failure of a sensor.\\ The default setting is wh65batt. However, if you do not have a WH65/WS69 but a WS90, wh90batt (the battery value of a WS90) should be entered here instead. If you want to monitor the presence of other sensors, you can also enter the corresponding key names here, separated by commas.\\ \\ For an improved sunshine hours calculation and for forwarding to some weather services, the geographical altitude (in meters) and the longitude and latitude (decimal degrees) of the solar sensor must be entered in the **Coordinates** section.\\ If you want to use the improved sunshine hours calculation, the configuration item SUN_CALC should also be set to True under section **Sunduration**.\\ \\ The **CSV** section may also be of interest if the data is to be further processed in Excel, for example.\\ \\ Otherwise, I recommend using [[https://foshkplugin.phantasoft.de/generic#push|Pushover]] to receive push notifications about important information from FOSHKplugin. Especially because user-defined push notifications are possible - for example, if the temperature exceeds or falls below a specified level, if it starts to rain or if the temperature falls below the dew point and there is a risk of mould.\\ You are informed within a few seconds!\\ The built-in http:%%//%%foshkpluginhost:port/FOSHKplugin/help help page is also helpful. It lists all the URLs supported by FOSHKplugin's built-in web server.\\ \\ As the configuration file is only read and activated when FOSHKplugin is started, FOSHKplugin must be restarted after changes to the configuration.\\ \\ Finally, I strongly recommend checking the firmware versions of the console and any sensors and updating them if necessary. [[https://ear.phantasoft.de/|EAR]] offers assistance here.\\ The air pressure should also be calibrated [[https://www.starpath.com/barometers/baro_cal.php|correctly]].\\ \\ What else can you do with FOSHKplugin?\\ Useful functions include [[https://foshkplugin.phantasoft.de/generic#banner|banners]] and [[https://foshkplugin.phantasoft.de/generic#tagfile|tag files]]. The query options for individual values or data records via http also offer great potential for subsequent processing scenarios.\\ And if FOSHKplugin is already installed, you can also think about sending it to other weather services or programmes. See [[https://foshkplugin.phantasoft.de/files/Comparison-Cloud-Software-FineOffset-EN.pdf|this document]].\\ Perhaps you would like to visualise your weather data locally on an Android device? Personal Weather Tablet (PWT) would be a good choice. There is also a suitable [[https://foshkplugin.phantasoft.de/generic#multipwt|recipe]] for this.\\ The possibilities are manifold ...\\
++++
----
{{anchor:prometheus}}
++++ Queries through a Prometheus server |
**Queries through a Prometheus server**
Since v0.10, FOSHKplugin supports http queries by a Prometheus server.\\ This means that the data can be easily stored in a Prometheus time series database and analysed and graphically presented using Prometheus' own visualisations or Grafana.\\ FOSHKplugin provides either all, only the metric or only the imperial numerical values via the http interface.\\ This depends on the configured path in the prometheus.yml:\\
# provides all numerical data to a Prometheus server via http
- job_name: "FOSHKplugin"
static_configs:
- targets: [192.168.15.100:8096]
# only provides the metric values
- job_name: "FOSHKplugin-Metric"
metrics_path: /metmetrics
static_configs:
- targets: [192.168.15.100:8096]
# use this to retrieve the imperial value only
- job_name: "FOSHKplugin-Imperial"
metrics_path: /impmetrics
static_configs:
- targets: [192.168.15.100:8096]
The IP address specified under targets (here: 192.168.15.100) corresponds to the IP address of the host on which FOSHKplugin is running; the port number (8096 in this example) is the local http port (LBH_PORT) configured in FOSHKplugin (8080 by default).\\ More detailed explanations on Prometheus can be found in the [[https://prometheus.io/docs/prometheus/latest/|online documentation on Prometheus]].\\ \\ All values are declared as type "gauge" - only keys with "time" in the name are declared as "counter".\\ Boolean keys such as the status states are transmitted in binary form with 0 (false) and 1 (true) as "gauge" type.\\ Strings are not provided as these are (apparently) not accepted in Prometheus.\\ \\ If you have the choice between Prometheus and InfluxDB, you should rather orientate yourself towards InfluxDB. In the current implementation, data retrieval is initiated by Prometheus (pull) - if the connection between FOSHKplugin and Prometheus is interrupted, all data is lost for this period.\\ With the [[https://foshkplugin.phantasoft.de/generic#influxdb|InfluxDB implementation in FOSHKplugin]], FOSHKplugin sends the data to InfluxDB (push) and stores all data temporarily if the connection to the remote InfluxDB server is lost. This data is automatically resent once the connection is restored. This means that there are no data gaps.\\
++++
----
{{anchor:signalquality}}
++++ Processing signal quality data |
**Processing signal quality data**
With Export\ADD_SIGNAL = True in the config file the additional collection of signal quality data of all active sensors will be enabled.\\ This requires a console that supports http/JSON-API (currently GW1100, GW1200, GW2000, WN1980C, WS3xx0C).\\ The input string coming from the console defined via Weatherstation\WS_IP is supplemented by the corresponding keys with the value of the signal quality.\\ The following key assignment is available:\\
WS90: wh90sig
WS80: wh80sig
WS68: wh68sig
WH65/WS69: wh69sig
WH40: wh40sig
WH32B: wh25sig
WH32: wh26sig
WH57: wh57sig
WH45: wh45sig
WH41/WH43: wh41sigN (where N = 1..4)
WH55: wh55sigN (where N = 1..4)
WH31: wh31sigN (where N = 1..8)
WH51: wh51sigN (where N = 1..8)
WN34: wh34sigN (where N = 1..8)
WN35: wh35sigN (where N = 1..8)
WH54: wh54sigN (where N = 1..4)
The value of these keys is in the range from 0 to 4 and corresponds to the number of bars in the signal display - i.e. 0 = no reception and 4 = best reception.\\ \\ These values are only available via UDP and getvalue as well as in forwards of type UDP, BANNER, TAGFILE, MQTT and InfluxDB. If these values are also to be sent with a forward in Ecowitt format, an additional
FWD_OPTION = blacklist=False
must be entered in the forward configuration in the config file for the corresponding forward.\\
++++
----
{{anchor:script}}
++++ Provide additional data from third-party devices globally for weather services (script) |
**Provide additional data from third-party devices globally for weather services (script)**
With the FWD_EXEC function, it has long been possible to modify the output line for a forward shortly before it is actually sent to the respective weather station service using a script. This script only works on a forward-specific basis and must therefore be set up for each individual forward.\\ However, if, for example, you want to use the data from an Luftdaten.info fine dust sensor as data from a virtual WH45/WH46 for sending to several services, you would have to set up a separate script for each individual service.\\ And depending on the target format or FWD_TYPE (Ecowitt format, WU, Awekas, Ambient Weather etc.), this script must also have different content.\\ \\ As of v0.10, ADD_SCRIPT can be used to define a global script that receives the data originally coming from the weather station and makes it modifiable. After the change, FOSHKplugin receives the modified or extended data back and only then starts to process this data for each individual forward.\\ This means that there is a centralised data manipulation option that is valid for all output formats.\\ \\ Example:\\ The particulate matter sensor from Luftdaten.info can be queried locally via a web interface. The link [[http://ip-address/data.json]] (where ip-address corresponds to the IP address of the sensor) returns a JSON file with the values, which can be parsed and processed very easily using standard on-board tools.\\ \\ JSON - depending on the software version of the device, however, the structure of the JSON may be different:\\
{
"software_version":"NRZ-2020-133",
"age":"28",
"sensordatavalues":[
{
"value_type":"SDS_P1",
"value":"8.25"
},
{
"value_type":"SDS_P2",
"value":"3.03"
},
{
"value_type":"samples",
"value":"5051440"
},
{
"value_type":"min_micro",
"value":"28"
},
{
"value_type":"max_micro",
"value":"20098"
},
{
"value_type":"interval",
"value":"145000"
},
{
"value_type":"signal",
"value":"-73"
}
]
}
SDS_P1 corresponds here to the PM10 value and SDS_P2 to the PM2.5 value.\\ The WH45 recognises the keys tf_co2 (temperature in °F), humi_co2 (humidity), pm25_co2 (the PM2.5 value), pm25_24h_co2 (the 24h mean value of PM2.5), pm10_co2 (PM10 value), pm10_24h_co2 (24h mean value PM10) in Ecowitt format, co2 (CO2) and co2_24h (24h average CO2). If we do not have a real WH45/WH46 ourselves, we can use the PM10 and PM2.5 values of the luftdaten.info sensor and emulate a WH45 - at least partially - by using the WH45/WH46 keys.\\ We therefore assign the value of SDS_P2 to the pm25_co2 key and the value of SDS_P1 to the pm10_co2 key using a script.\\ \\ For a better understanding, here is the sequence of the individual steps:\\ 1. FOSHKplugin receives the general weather data from the console\\ 2. When the data is received, the configured script is started, which executes the following steps:\\ 2.1 Query foreign data - the values must come from somewhere\\ 2.2 merge with the real data from the weather station\\ 2.3 Return to FOSHKplugin\\ 3. FOSHKplugin sends the merged data to all configured weather services\\ \\ Here is the example script that executes the complete point 2:\\
#!/bin/bash
# complements the output line of FOSHKplugin with values of the particulate matter sensor from Luftdaten.info and emulates a WH41
# the channel number of the virtual WH41 is defined via the variable WH41
# depending on the output format, the output strings must be modified - in Ecowitt format, the individual components are combined
# using an "&" - used here
# needs curl and jq - install with sudo apt-get install curl jq
# general help: https://foshkplugin.phantasoft.de/generic#exec
# define the local ip address of the Sensor
ADR=192.168.15.229
# define the channel number of the virtual WH41; 9 = emulate WH45 instead
WH41=9
#JSON=`cat luftdaten2.json`
JSON=`curl -s http://${ADR}/data.json`
# the original output data from FOSHKplugin
instr="$@"
# PM2.5
pm2=`echo ${JSON}|jq ".sensordatavalues[1].value"|sed 's/\"//g'`
if [ ! -z "${pm2}" ]; then
if [ "${WH41}" = "9" ]; then pm2string="&pm25_co2=${pm2}"; else pm2string="&pm25_ch${WH41}=${pm2}"; fi
fi
# PM10
pm1=`echo ${JSON}|jq ".sensordatavalues[0].value"|sed 's/\"//g'`
if [ ! -z "${pm1}" ]; then
if [ "${WH41}" = "9" ]; then pm1string="&pm10_co2=${pm1}"; else pm1string="&pm10_ch${WH41}=${pm1}"; fi
fi
# temp in °C - must be converted to °F - F = (C*9/5)+32 -
temp=`echo ${JSON}|jq ".sensordatavalues[2].value"|sed 's/\"//g'`
temp=`echo "scale=2; (${temp}*9/5)+32"|bc`
if [ ! -z "${temp}" ]; then
if [ "${WH41}" = "9" ]; then tempstring="&tf_co2=${temp}"; else tempstring="&tf_ch${WH41}=${temp}"; fi
fi
# pressure - not supported by WH41, WH45, WH46 - you could override the original pressure from wether station
# not used
pressure=`echo ${JSON}|jq ".sensordatavalues[3].value"|sed 's/\"//g'`
if [ ! -z "${pressure}" ]; then
if [ "${WH41}" = "9" ]; then pressurestring="&tf_pressure=${pressure}"; else pressurestring="&pressure_ch${WH41}=${pressure}"; fi
fi
#humidity
humidity=`echo ${JSON}|jq ".sensordatavalues[4].value"|sed 's/\"//g'`
if [ ! -z "${humidity}" ]; then
if [ "${WH41}" = "9" ]; then humiditystring="&humi_co2=${humidity}"; else humiditystring="&humidity_ch${WH41}=${humidity}"; fi
fi
# merge the original string with the new components
echo "${instr}${pm2string}${pm1string}${tempstring}${humiditystring}"
The script here is somewhat more extensive because it can provide data for either a WH41 or WH45.\\ \\ For installation/configuration:\\ 1. save the enclosed file as addLDdata.sh in the installation directory of FOSHKplugin (/opt/FOSHKplugin/)\\ 2. customise addLDdata.sh - adjust the IP address of your particulate matter sensor at ADR\\ 3. make the script executable: chmod ug+x addLDdata.sh\\ 4. make sure that the required tools are available: sudo apt-get install curl jq\\ 5. manual test of the script: ./addLDdata.sh - a line like &pm25_co2=8.15&pm10_co2=17.17&tf_co2=31.55&humi_co2=87.72 should then be displayed\\ 6. customise the forward to PWSDashboard - the line FWD_EXEC = ./addLDdata.sh must be added in the relevant forward\\ 7. restart FOSHKplugin - sudo service foshkplugin restart\\ \\
mqtt:
sensor:
- state_topic: "GW2000/tc_co2"
name: "WH45 Temperature"
unit_of_measurement: "°C"
device_class: "temperature"
icon: "mdi:thermometer"
This is very time-consuming (with 200 or even 450 topics).\\ \\ With v0.10, FOSHKplugin now also supports the MQTT discovery of Home Assistant.\\ HA automatically finds FOSHKplugin as a device with all entities without the need for any configuration measures. Icon, unit and device class are already pre-assigned.\\ A forward block in the configuration file foshkplugin.conf should look something like this:\\
[Forward-60]
FWD_TYPE = MQTTMET
FWD_CMT = MQTT-Forward of metric values to LoxBerry
FWD_URL = 192.168.15.236:1883@homeassistant/FOSHKplugin
FWD_ENABLE = True
FWD_OPTION = MQTTCYCLE=5,hass=True,devname=GW1000-Test,minmax=False,status=False,dtime_format="%d.%m.%Y %H:%M:%S",diagnostic=False
FWD_SID = MQTT-username
FWD_PWD = MQTT-password
FWD_STATUS = True
MQTTMET should be selected as the forward type FWD_TYPE for metric values - MQTTIMP should be selected accordingly for imperial measurement systems.\\ The destination - i.e. the MQTT broker together with the desired hierarchy - must be specified in the FWD_URL. The structure of the address is MQTTipaddress:port@topic-hierarchy%prefix. A prefix "%prefix" is optional and therefore does not have to be specified.\\ In the FWD_OPTION line, at least hass=True must be entered to activate auto-discovery. The name of the device is defined with devame=name (default: FOSHKplugin).\\ By default, FOSHKplugin only sends the data to the broker when the value changes. In addition, an interval in minutes can be entered via MQTTCYCLE in which ALL topics - regardless of value changes - are sent to the broker.\\ With an interval of 0, ALL topics are sent at every send interval.\\ To minimise data transfer, I recommend entering an interval of 10 or 5 minutes for regular operation.\\ If the MQTT broker requires a login, the credentials can be configured with FWD_SID (user name) and FWD_PWD (password).\\ \\ By default, all values including the min/max values (if configured) are transmitted via MQTT. To prevent the transmission of the min/max values, minmax=False can be set as an additional option in FWD_OPTION. If the status messages from FOSHKplugin are also to be made available via MQTT, FWD_STATUS should be set to True. Alternatively, this option can also be specified as status=True in FWD_OPTION.\\ The time format for the output of timestamps (e.g. lightning_time and all min/max times) can be defined with dtime_format. For possible formatting options, see the recipe [[plugins:foshkplugin:foshkplugin_generic_version#dt_format|Adjust the output format for date and time (from v0.10)]]. If dtime_format is missing in FWD_OPTION, the central setting Config\DT_FORMAT is used instead.\\ If the sensor data is to be separated from the diagnostic data (info data, battery and signal values), this can be realised via the additional option diagnostic=True in the FWD_OPTION. Two separate cards for sensor data and diagnostic data are then generated in the Home Assistant. If diagnostic=False is set or the diagnostic option is missing within the FWD_OPTION, all data is displayed together in one card.\\ \\
[Forward-66]
FWD_CMT = save via ftps as remote clientraw.txt
FWD_ENABLE = True
FWD_SID = ftp-username
FWD_PWD = ftp-password
FWD_TYPE = CLIENTRAWTXT
FWD_URL = ftps://ftp.location.where.to/save/the/file/clientraw.txt
The credentials for the FTP(s) access must be entered under FWD_SID and FWD_PWD and the target URL under FWD_URL.\\ \\ Another - unfortunately also discontinued - project for a widget based on clientraw.txt is [[https://github.com/waynedgrant/android-appwidget-cirrus|android-appwidget-cirrus]].\\ \\ {{:plugins:foshkplugin:cirrus-widget.png?400}} \\ \\ At least the source code is available - so you could still make changes if necessary. Perhaps someone will find someone who can take the current status and develop it further.\\ When I find the time, I'll upload it to Android Studio and see what I can do with it.\\ \\ Personally, I find the font a bit small and I would also prefer German-language terms. I also like the icon for the current weather (or the forecast) from the Weather Personal widget, which is unfortunately missing here.\\ But I think it's a good basis for my own experiments ...\\ \\ This Android widget also uses a file in clientraw.txt format as the data source - so a forward would have to be configured in the FOSHKplugin as specified above. Of course, **ONE** Forward and therefore **ONE** clientraw.txt is sufficient for both widgets as well as for any other applications.\\ \\
++++
----
{{anchor:dewpoint}}
{{anchor:spread}}
++++ Additional dew point & spread calculation for outdoor and indoor sensors |
**Additional dew point & spread calculation for outdoor and indoor sensors**
Ecowitt consoles only calculate the dew point for the outdoor temperature/humidity; the dew point is not calculated for any internal T/H sensors.\\ If you also want to set up dew point monitoring indoors - for example due to possible mould development - you can do this with FOSHKplugin.\\ \\ To activate the additional dew point calculation, the corresponding item must be activated in the configuration file foshkplugin.conf:\\ \\ Export\ADD_DEWPT = True (disabled by default)\\ \\ After the required restart of FOSHKplugin, the dew points are now also output for all sensors that measure temperature and humidity\\ \\ dewptNc and dewptNf for all WH31 (where N = 1..8)\\ dewptc_co2 and dewptf_co2 for WH45/WH46\\ dewptinc and dewptinf for the indoor sensor\\ \\ Whereby the keys with "c" in the name contain the value in Celsius and the keys with "f" contain the value in degrees Fahrenheit.\\ If activated, these values are added to every forward for which the keys are permitted.\\ \\ For comparative analyses, however, the temperature valid at the respective time is required in addition to the dew point, which is a hindrance for subsequent analyses.\\ For this reason, FOSHKplugin calculates the so-called [[https://en.wikipedia.org/wiki/Dew_point_depression|spread]] - the difference between the air temperature and the dew point temperature - instead of the dew point. The greater the spread, the lower the relative humidity and the lower the spread, the more humid the air.\\ If the spread is 0, the air temperature and dew point temperature are identical - the air is saturated and therefore cannot absorb any more moisture - the moisture is deposited on surfaces.\\ The spread value is therefore already the result of the comparison of temperature and dew point.\\ \\ With the configuration option (this optional calculation is deactivated by default)\\ \\ Export\ADD_SPREAD = True\\ \\ in foshkplugin.conf, the additional calculation of the spread can be activated for the outdoor sensor as well as for all WH31 and WH45/46.\\ \\ FOSHKplugin uses the following keys for the respective dew point difference:\\ \\ outdoor: spread\\ indoor: spreadin\\ WH31: spreadN (where N = 1..8)\\ WH45: spread_co2\\ \\ These keys are part of the (daily) CSV and are transmitted via UDP and in banner, tag file ([[oint.html|example]]), MQTT and InfluxDB forwards when ADD_SPREAD is activated. The values can also be retrieved via http and used as triggers for user-defined push notifications via pushover.\\ For all other forward types, these keys are in a blacklist and are NOT transmitted automatically.\\ If you want to switch off this blacklist for a specific forward in Ecowitt format, you can do this by setting the line\\ \\ FWD_OPTION = blacklist=False\\ \\ within this forward section in the configuration file foshkplugin.conf. A separate block could be used to display these values in the PWS dashboard, for example.\\ \\ This function is available with [[https://foshkplugin.phantasoft.de/files/generic-FOSHKplugin-0.0.10Beta.zip|FOSHKplugin v0.10 from beta 240308]].\\ \\
++++
----
{{anchor:fullinstall}}
++++ Installation of FOSHKplugin generic version |
**Installation of FOSHKplugin generic version**
Required: 24/7 computer system (e.g. Raspberry Pi or a virtual machine) with ssh access or local console for installation.\\ The installation and configuration of FOSHKplugin is then ideally done via ssh (so you can also copy/paste the commands).\\ The installation requires approx. 6 steps, which are documented here. For each of these steps there is a textual help as well as (as far as possible) sensible defaults, which are shown in square brackets.\\ \\ 1. Create a directory
sudo mkdir /opt/FOSHKplugin
2. Change to the directory
cd /opt/FOSHKplugin
3. Download the installation file
wget -N http://foshkplugin.phantasoft.de/files/generic-FOSHKplugin.zip
# or for the current beta version:
wget -N http://foshkplugin.phantasoft.de/files/generic-FOSHKplugin-0.0.10Beta.zip
4. Extract the installation file
unzip generic-FOSHKplugin.zip
# or for the current beta version:
unzip generic-FOSHKplugin-0.0.10Beta.zip
5. Start the installation script
sudo ./generic-FOSHKplugin-install.sh --install
6. Initial configuration\\ In the square brackets there should already be meaningful defaults that can be selected with ENTER. However, you can also enter your own value in order to overwrite these defaults:
+++ FOSHKplugin +++ (1/6)
FOSHKplugin can automatically forward any incoming message from the weather
station via UDP to a global destination - to be defined here.
If this forwarding is required, please enter the IP address of the destination
here. If not, enter - without inverted commas - simply type a -
ENTER accepts the specified value in square brackets.
ip address of UDP-target system (use - for no UDP) []:
Leave blank if no UDP forwarding is required, otherwise enter the IP address of the destination of the UDP messages.\\
**+++ FOSHKplugin +++ (2/6)
FOSHKplugin can automatically forward any incoming message from the weather
station via UDP to a global destination - to be defined here.
If this forwarding is required, please enter the UDP port of the destination
here. If not, enter - without inverted commas - simply -.
ENTER accepts the specified value in square brackets.
udp port on UDP-target system (use - for no UDP) [12340]:
Leave blank if no UDP forwarding is required, otherwise enter the UDP port of the target system.\\
+++ FOSHKplugin +++ (3/6)
The weather station must know to which destination it should send the data.
To do this, the IP address of the host on which FOSHKplugin is running (this
system) must be specified.
ENTER accepts the specified value in square brackets.
enter the ip address of this local system (use - for none) [192.168.15.194]:
Enter the IP address of the local system, i.e. the device on which FOSHKplugin is to run (please do not use an IPv6 or localhost address).\\
+++ FOSHKplugin +++ (4/6)
The weather station must know to which destination it should send the data.
For this purpose, in addition to specifying the IP address of the host (just
done), also a TCP port must be specified on which FOSHKplugin listens for
incoming data from the weather stations.
A free and thus usable port should be found automatically by this installation
routine.
ENTER accepts the specified value in square brackets.
http port on local system - accept with ENTER [8080]:
The local port on which the internal http server is started by FOSHKplugin, the default can be accepted with ENTER.\\
+++ FOSHKplugin +++ (5/6)
Please select the weather station that should send the data to this FOSHKplugin
installation.
In addition to the IP address, the command port (default: 45000) and the desired
transmission interval of the station to FOSHKplugin are also required.
The transmission interval specifies the interval at which the weather station
sends data to FOSHKplugin (in seconds).
If no station can be found, the configuration can also be set up subsequently
via the app or on the station itself. To do this, simply continue here.
If more than one station is found, enter the IP address of the desired station:
ENTER accepts the specified value in square brackets.
ip address of weather station [192.168.15.167]:
Please enter the IP address of the weather station here. This is generally found automatically.\\
command port of weather station [45000]:
The command port of the weather station. Here, too, the default 45000 (the default port for FOSHK weather stations) can be accepted with ENTER.\\
transmission interval of weather station [60]:
Enter the desired interval in seconds at which the weather station sends the data to FOSHKplugin. The default of 30 seconds can be accepted - however, other time intervals can also be used. Note that this is also the minimum time interval for forwards.\\
+++ FOSHKplugin +++ (6/6)
It is recommended to run FOSHKplugin as a systemd service. The name of the
service is foshkplugin by default. However, if several parallel FOSHKplugin
installations are desired, each service needs its own unique name.
The service name can be changed here if necessary.
ENTER accepts the specified value in square brackets.
current services containing "foshk":
Define the name of the systemd service: [foshkplugin]:
You may specify a different name for the service. If only one service is needed the default is ok - so press ENTER
+++ FOSHKplugin +++ are these settings ok? (Y/N)
The settings made are accepted with Y. With N it can be configured again if an error is discovered.\\
+++ FOSHKplugin +++ write settings into the config-file? (Y/N)
With Y these settings are written into the config file (foshkplugin.conf).\\
+++ FOSHKplugin +++ write settings into the weather station? (Y/N)
With Y the required data (IP address and port of the target system from the perspective of the weather station, the interval and the data format Ecowitt) are written to the weather station.\\
+++ FOSHKplugin +++ enable and start the service? (Y/N)
With Y, a service (foshkplugin) is installed and started, which is started automatically every time the computer is restarted and which leads to the restart of FOSHKplugin within a few seconds even if the program crashes.\\ \\ 7. advanced configuration\\ The foshkplugin.conf file can be edited with any editor in order to make further settings. For forward operation, however, only the required forwards need to be entered.\\
vi foshkplugin.conf
The data received from the weather station are forwarded to other systems / programs via so-called forwards. A forward block is required for each desired forwarding, in which the target, format, interval and, if necessary, other forward-specific settings are specified.\\ A forward block is identified by [Forward-n] where n is a sequential number (1-99). This number must not be repeated within the config file.\\
Examples of a forward to Awekas (via API), Home Assistant (via MQTT) and Home Assistant (via Ecowitt integration):\\
[Forward-1]
FWD_CMT = forward in Awekas API format
FWD_TYPE = AWEKAS
FWD_URL = http://data.awekas.at/eingabe_pruefung.php?
FWD_SID = Awekas-ID
FWD_PWD = Awekas-password
FWD_INTERVAL = 60
FWD_ENABLE = True
Further forwards according to this template are possible:\\
[Forward-2]
FWD_CMT = MQTT-Forward of metric values to Home Assistant via MQTT broker (see https://foshkplugin.phantasoft.de/generic#hass)
FWD_TYPE = MQTTMET
FWD_URL = 192.168.15.236:1883@homeassistant/FOSHKplugin
FWD_ENABLE = True
FWD_OPTION = MQTTCYCLE=5,hass=True,devname=GW1000-Test,minmax=False,status=False,dtime_format="%d.%m.%Y %H:%M:%S",diagnostic=False
FWD_SID = MQTT-username
FWD_PWD = MQTT-password
FWD_STATUS = True
[Forward-3]
FWD_CMT = EW-Forward for Home Assistant Ecowitt Integration
FWD_TYPE = EW
FWD_URL = http://192.168.15.157:8123/api/webhook/a64287c35b370ec8492c34470a75988b
FWD_ENABLE = True
FWD_OPTION = blacklist=False
FWD_IGNORE =
FWD_QUEUE = False
A web browser can be used to check whether FOSHKplugin is running via [[http://ipaddress:port]]. ipaddress is the IP address of the host on which FOSHKplugin is running (see point 3 of the installation instructions) and the port is the port on which FOSHKplugin is listening (point 4).\\ If the weather station is sending data, the station's data should be displayed on this page. If a white page is displayed, FOSHKplugin is running, but the weather station has not yet sent any data. If an error is displayed (timeout, page not found), either the specified IP address or port is incorrect or FOSHKplugin is not running at all.\\ \\ After each change to the config file foshkplugin.conf, the FOSHKplugin service must be restarted for the new configuration to become active. Depending on the Linux system used, the service can be restarted in different ways. For systems based on Debian, this is normally done with:
sudo service foshkplugin restart
\\
++++
----
{{anchor:pwsweather}}
++++ Send data to PWSWeather |
**Send data to PWSWeather**
[[https://www.pwsweather.com/|PWSWeather]] is taking a very customer-friendly approach with the [[https://www.pwsweather.com/contributor-plan|Aeris forecast data]]. Those who upload station data receive free forecast data in return.\\ It is therefore advisable to (also) send the data from your own weather station to PWSWeather.\\ The data is transmitted using the WU protocol.\\ \\ A forward to PWSWeather that works here looks like this:\\
[Forward-5]
FWD_ENABLE = True
FWD_URL = http://www.pwsweather.com/pwsupdate/pwsupdate.php?ID=myID&PASSWORD=myPassword&
FWD_INTERVAL = 300
FWD_TYPE = WU
FWD_CMT = PWSWeather
Note the "&" at the end of the FWD_URL!
To upload the data, I use the station ID (found in the [[https://dashboard.pwsweather.com/|PWSWeather profile]]) as the ID and the password that I use to log in to [[https://dashboard.pwsweather.com/|PWSWeather dashboard]] as myPassword. However, you can probably also use the API key from the profile instead.
++++
----
{{anchor:checkconfig}}
++++ Help I am overwhelmed with the number of my forwards! |
**Help I am overwhelmed with the number of my forwards!**
With a certain number of forwards, the foshkplugin.conf quickly becomes somewhat confusing. If you then want to set up another forward, there is no overview of which next free number is available.\\ As I know the problem myself, I have added a little help for this.\\ If you start FOSHKplugin from the console with the -checkConfig parameter, it displays the next free gap and the next number that can be used as a forward number.\\ The next free gap is found by counting up from 0 to 99 and checking whether there is a forward for each of these numbers. If a corresponding forward is missing, this number can be used for a new forward and is output as free.\\ For finding the next number it is counted backwards from 100 and the first free number (without a forward) is output.\\ An example:\\
bash# ./foshkplugin.py -CHECKCONFIG
checking config file foshkplugin.conf
free section: [Forward-5]
next section: [Forward-34]
This means that the designation for the next forward may be "Forward-5" or "Forward-34" (as these forward designations are not yet in use).\\ However, it is conceivable that there will be further gaps after "Forward 5" up to 34. What is certain is that any number from 35 to 99 may be used as a new forward designation, as these have not yet been used.\\ \\ The config file can be specified as a second - optional - parameter if it is not in the same directory as the Python programme.\\
++++
----
{{anchor:wns}}
++++ Send data to Wetternetz Sachsen |
**Send data to Wetternetz Sachsen**
[[https://www.wetternetz-sachsen.de/|Wetternetz Sachsen]] accepts data in different formats. We use the [[#tagfile|TAGFILE forward]] to send data avtively via HTTP Get method. As described in the [[#tagfile|TAGFILE section]], we need two files: ''wns.tagdef'' and ''wns.template'':
[Forward-99]
FWD_ENABLE = True
FWD_CMT = TAGFILE Wetternetz Sachsen
FWD_OPTION = config=/opt/loxberry/config/plugins/foshkplugin/wns.tagdef
FWD_URL = https://www.wetternetz-sachsen.de/get_daten_23.php?
FWD_INTERVAL = 60
FWD_TYPE = TAGFILE
Again: Adjust paths if needed. Before sending data, it is a good idea to test/check the data. Use ''FWD_URL = /opt/loxberry/log/plugins/foshkplugin/'' for testing and only write the output file locally without sending (see also above).
++++
----
{{anchor:several}}
++++ Why are there several versions of FOSHKplugin? |
**Why are there several versions of FOSHKplugin?**
There are two versions of FOSHKplugin - the [[https://foshkplugin.phantasoft.de/|LoxBerry version]] and the [[https://foshkplugin.phantasoft.de/generic|generic version]].\\
The LoxBerry version requires an existing [[https://wiki.loxberry.de/en/start|LoxBerry]] installation - a widely used, free add-on with many additional options in the Loxone Smarthome system environment.\\
You have to assess for yourself whether it is worth the effort to install and maintain a LoxBerry system just to run the LoxBerry version of FOSHKplugin on it. In general, the statement applies: without Loxone no LoxBerry and without LoxBerry no LoxBerry version of FOSHKplugin.\\
\\
The generic version of FOSHKplugin is intended for the general public. This only requires any Linux as a basis (although Debian derivatives are preferable). Documentation is available in English. Here you can install FOSHKplugin with very little effort - even on an existing Linux system.\\
The installation is described step by step here: [[https://foshkplugin.phantasoft.de/generic#fullinstall|Installation of FOSHKplugin generic version]]\\
\\
The code base and functionality is identical for the LoxBerry version and generic version.\\
The only difference is that some configuration changes in the LoxBerry version can be made via a web form. In the generic version, console access and an editor are required for [b]all[/b] configurations.\\
As this is also necessary for advanced configurations (e.g. forwards) in the LoxBerry version, you can also do this in general.\\
++++
----
{{anchor:sunhours}}
++++ Improved sunshine duration calculation and other solar topics |
**Improved sunshine duration calculation and other solar topics**
By default, FOSHKplugin checks whether the reported solar radiation value is higher than 120W/m² for the calculation of the daily sunshine duration in each transmission interval and if so, this minute is added to the sunshine duration.\\
A better calculation according to [[https://github.com/Jterrettaz/sunduration|Jterrettaz]] with dynamic and location-dependent thresholds (as WeeWX and WSWin also do) is available if you set Sunduration\SUN_CALC = True in the config file and (important!) also specify the geographical coordinates under Coordinates\ALT (altitude), Coordinates\LAT (latitude) and Coordinates\LON (logitude):\\
[Coordinates]
# coordinates are only needed for calculating cloudbase and sunhours or export to Awekas-API, clientraw.txt, Weather365.net
ALT = # altitude in m e.g. 53
LAT = # latitude in decimal grad e.g. 52.668759; North of the equator has no sign. South of the equator has a - sign.
LON = # longitude in decimal grad e.g. 13.266274; for longitudes left of Greenwich a - sign is needed.
Sunduration\SUN_MIN can be used to specify the solar radiation threshold above which the detection is counted as sunshine. The calculation can be tweaked with Sunduration\SUN_COEF (default=0.92): too little sunshine recorded: decrease value; too much sunshine recorded: increase the SUN_COEF value:\\
[Sunduration]
SUN_CALC = False # enable for better sunhours calculation (LAT, LON needed), disable to use static threshold of 120W/m²
SUN_MIN = 0 # from this value (W/m²) calculation starts
SUN_COEF = 0.92 # adjustment factor also depends on the location
SUNSHINE_HOLD = 0 # Hold time in seconds for value sunshine, this time continues to be output sunshine = True, even if there is no sunshine (default: 0)
For compatibility reasons, the conventional calculation with a threshold value of 120W/m² - i.e. Sunduration\SUN_CALC = False - is the standard. The standard calculation is performed without specifying the geographical coordinates.\\
\\
FOSHKplugin outputs a few more light-specific entities, which are briefly explained here:\\
\\
last_suncheck = timestamp of the last time a sunshine check was performed\\
last_suntime = timestamp when sunshine was last detected\\
sunhours = shows the duration of daily sunshine in hours (solarradiation >= 120W/m² or - with Sunduration\SUN_CALC = True - with dynamic, location-dependent threshold value)\\
sunmins = shows the duration of daily sunshine in minutes (solarradiation >= 120W/m² or - with Sunduration\SUN_CALC = True - with dynamic, location-dependent threshold value)\\
sunshine = represents the presence of sunshine; can be artificially extended with Sunduration\SUNSHINE_HOLD to prevent constant changes\\
theosunsr = Theoretical sunshine limit above which sunshine would be declared\\
srsum = daily solar radiation sum since midnight (00:00)\\
\\
++++
----
2bc ...
\\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\