Difference between pages "Add-On Services" and "Templates"

From meteoplug
(Difference between pages)
Jump to: navigation, search
(→‎Twitter Upload)
 
(→‎Examples)
 
Line 1: Line 1:
 
__NOTOC__
 
__NOTOC__
−
Meteobridge provides some additional services, which might be interesting, when you also want to use received data with your own postprocessing IT. Live data can be derived in two ways. Meteobridge client can be asked by a HTTP request to return data (pull mode) or can send data as HTTP-GET requests with user-defined URL parameters to a user-defined Internet address, or can twitter weather data or can upload data into a MYSQL database (push mode).  
+
Meteobridge provides a very flexible mechanism to smuggle sensor data of different kinds into strings to be used by Meteobrdge push services like Twitter, HTTP GET uploads or MSQL database insert requests.
 +
Simply type in the text you want to upload and represent the pieces of sensor data by so called variables. When data gets uploaded, these variables will be replaced by current sensor data and so a string filled with the data you intended will be uploaded.
  
−
==Pull Mode==
+
Each variable starts with an opening square bracket "[" and is terminated by a closing square bracket "]". The structure of the variable name between these brackets is as follows: <pre>sensor-selector=converter.decimals:replacement</pre>
−
Web server of Meteobridge client, which presents web interface for adminstration to you, can also deliver weather data. There are two URLs defined that can be polled to get most recent sensor data in XML or plain text. Although we don't recommend this for security reasons, you can make that URLs accessible from the Internet by configuring your router appropriately. However, when you want to bring sensor data to one of your own servers in the Internet we recommend to make use of Meteobridge's push mode, which will not need you to open up your firewall.
+
"converter", "decimals" and "replacement" can be omitted, "sensor" and "type" are mandatory.
−
+
While "sensor" tells what sensor and what piece of information of the sensor to use, "selector" decides data from what time period should be taken into account and "converter" does convert data into measurement units the user likes most. "Decimals" decides about precision the result should be shown in and "replacement" gives the string to be returned when there is no data for defined sensor available.
−
===Live Data as XML===
+
−
By sending the meteobridge a HTTP request like "http://ip-of-meteobridge/cgi-bin/livedataxml.cgi" (where "ip-of-meteobridge" must be replaced by the IP itself) meteobridge returns current weather data in XML notation. Each reply starts witch tag <logger> and ends with </logger> with the sensor data as records with sensor specific tags "THB", "TH", "WIND", "RAIN", "UV", "SOLAR". Example below illustrates the XML format:
+
  
−
<pre><logger>
+
==Sensors==  
−
  <THB date="20121227224318" id="thb0" temp="26.0" hum="37" dew="10.2"
+
These sensors are defined in Meteobridge.
−
      press="1008.8" seapress="1010.1" fc="2"/>
+
* '''th0temp''': outdoor temperature in degrees Celsius
−
  <TH date="20130104141909" id="th0" temp="9.1" hum="95" dew="8.3"/>
+
* '''th0hum''': relative outdoor humidity as percentage
−
  <RAIN date="20130104141856" id="rain0" rate="0.0" total="3.0" delta="0.0"/>
+
* '''th0dew''': outdoor dew point in degrees Celsius
−
  <WIND date="20130104141916" id="wind0" dir="109" gust="0.9" wind="2.2" chill="9.1"/>
+
* '''thb0temp''': indoor temperature in degrees Celsius
−
</logger></pre>
+
* '''thb0hum''': indoor humidity as percentage
 +
* '''thb0dew''': indoor dewpoint in degrees Celsius
 +
* '''thb0press''': station pressure in hPa
 +
* '''thb0seapress''': normalized pressure (computed to sea level) in hPa
 +
* '''wind0wind''': wind speed in m/s
 +
* '''wind0avrwind''': average windspeed in m/s (time used for average depends on station)
 +
* '''wind0dir''': wind direction in degress (0° is North)
 +
* '''wind0chill''': wind chill temperature in degrees Celsius
 +
* '''rain0rate''': rain rate in mm/h
 +
* '''rain0total''': rain fall in mm
 +
* '''uv0index''': uv index
 +
* '''sol0rad''': solar radiation in W/m^2
 +
If a sensor is not there or data of sensor has passed the "tolerated data age" interval, Meteobridge will not provide data for it and will present the value defined as "replacement". If no replacement is given, variable will not be converted into data but will stay as is.
  
−
Each sensor data record has a mandatory "date" and "id" parameter. The other parameters are sensor specific. Meaning of parameters is:
+
==Selectors==
−
* '''date''': UTC timestamp of reception of sensor data in format "YYYYMMDDhhmmss"
+
Sensors are followed by a selector (syntactically separated by a dash) that specifies what period in time should be used for evaluation. Valid selectors are:
−
* '''id''': Unique ID of sensor, consists of a sensor type description shortcut followed by a number, which is always "0" in Meteobridge, as additional sensors are not supported
+
* '''act''': most recent data
−
* '''temp''': temperature in degrees Celsius (with one decimal)
+
* '''hmin''': minimum value of this hour
−
* '''hum''': relative humidity in percent (no decimals)
+
* '''hmax''': maximum value of this hour
−
* '''dew''': dew point temperature in degrees Celsius (with one decimal)
+
* '''dmin''': minimum value of today
−
* '''press''': station pressure (without altitude correction) in hPa (with one decimal)
+
* '''dmax''': maximum value of today
−
* '''seapress''': normalized pressure with altitude correction (also called sea level pressure) in hPa (with one decimal)
+
* '''mmin''': minimum value of this month
−
* '''fc''': stations forecast code, if provided. As this has low evidence and also largely varies between stations, meteobridge does not recommend to make use of this data.
+
* '''mmax''': maximum value of this month
−
* '''rate''': measured rain rate in mm per hour (with one decimal).
+
* '''hmin''': minimum value of this year
−
* '''total''': current value of rain bucket counter, converted to mm (with one decimal).
+
* '''hmax''': maximum value of this year
−
* '''delta''': additional rain fall in mm since previous readout of this data (with one decimal).
+
* '''hmin''': minimum value of all time
−
* '''wind''': current average wind speed im m/s (with one decimal).
+
* '''hmax''': maximum value of all time
−
* '''gust''': curent not avergaed wind speed in m/s (with one decimal).
+
−
* '''dir''': wind direction in degrees (0-359, no decimals).
+
−
* '''chill''': wind chill temperature in degrees Celsius (with one decimal).
+
−
* more to come...
+
  
−
===Live Data as Plain Text===
+
Apart from selectors that use absolute, predefined time slots there are also selectors that look for a certain amount of time into the past.
−
By sending the meteobridge a HTTP request like "http://ip-of-meteobridge/cgi-bin/livedata.cgi" (where "ip-of-meteobridge" must be replaced by the IP itself) meteobridge returns current weather data as plain text. Each reply consists of a series of lines, where each line represnets a sensor. Lines do start with a time stamp and a unique sensor id followed by sensor specific parameters. Example below illustrates the format:
+
* '''max2''', '''max5''', '''max10''', '''max15''', '''max30''', '''max60''': selects the maximum value from the last 2, 5, 10, 15, 30 or 60 minutes
 +
* '''min2''', '''min5''', '''min10''', '''min15''', '''min30''', '''min60''': selects the minimum value from the last 2, 5, 10, 15, 30 or 60 minutes
 +
* '''avg2''', '''avg5''', '''avg10''', '''avg15''', '''avg30''', '''avg60''': selects average value from the last 2, 5, 10, 15, 30 or 60 minutes
 +
* '''sum2''', '''sum5''', '''sum10''', '''sum15''', '''sum30''', '''sum60''', '''sumday''': selects summerized delta values from the last 2, 5, 10, 15, 30, 60 minutes or current day (useful to get amount of total rain in a certain time frame: "rain0total-sum60" is rainfall im mm of last 60 minutes, "rain0total-sumday" is todays rain fall)
  
−
<pre>20130104142614 thb0 26.9 38 11.4 1020.4 1021.7 2
+
==Converters==
−
20130104142610 rain0 0.0 3.0 0.0
+
Sensor data is reported in ISO units (°C, hPa, mm, m/s) by default, but can be converted into non-ISO units (imperial) by adding a conversion token. Defined tokens are:
−
20130104142636 th0 9.1 95 8.3
+
* '''F''' converts temperature from Celsius to Fahrenheit.
−
20130104142652 wind0 160 2.2 1.8 8.0</pre>
+
* '''psi''' converts pressure from hPa (equivalent to mbar) to psi.
 +
* '''mmHg''' converts pressure from hPa to millimeters of mercury.
 +
* '''inHg''' converts pressure from hPa to inches of mercury.
 +
* '''kmh''' converts wind speed from meters per second to kilometers per hour.
 +
* '''mph''' converts wind speed from meters per second to miles per hour.
 +
* '''kn''' converts wind speed from meters per second to knots.
 +
* '''bft''' converts wind speed from meters per second to Beaufort scale.
 +
* '''in''' converts millimeters to inches.
 +
If an unknown conversion string is used, no conversion will take place, no error message will appear.
  
−
==Push Mode==
+
==Special Variables==
−
When you select expert mode at the bottom of "Upload Data" tab, you will see an additional entry that allows you to send sensor data to a user-defined server via HTTP requests or MYSQL updates and to twitter.  
+
There are a couple of variables that don't come as "sensor-selector=converter" chains but have a distinct meaning by themselves.
  
−
===Twitter Upload===
+
Date und time variables are defined as follows:
−
Meteobridge allows you to send weather data snippets to your twitter account. As twitter requires a bit complicated authentication you will have to run through 6 steps.
+
* '''YYYY''': year as four digit number
 +
* '''YY''': year as two digit number
 +
* '''MM''': month as two digit number, if only one digit neede a zero will be used as first digit
 +
* '''M''': month as one or two digit number, no leading zeros
 +
* '''DD''': day of month as two digit number, if only one digit neede a zero will be used as first digit
 +
* '''D''': day of month as one or two digit number, no leading zeros
 +
* '''hh''': hour as two digit number, if only one digit neede a zero will be used as first digit
 +
* '''h''': hour as one or two digit number, no leading zeros
 +
* '''mm''': minute as two digit number, if only one digit neede a zero will be used as first digit
 +
* '''m''': minute as one or two digit number, no leading zeros
 +
* '''ss''': seconds as two digit number, if only one digit neede a zero will be used as first digit
 +
* '''s''': seconds as one or two digit number, no leading zeros
 +
When a capital "U" preceeds a date/time variable name, UTC is used instead of local time ("[Uhh]:[Umm]:[Uss] UTC" is evaluated to a string like "16:03:33 UTC")
  
−
<gallery perrow=1 widths=500 heigths=350>
+
==Decimals==
−
File:twitter0.png|1. Press "Request PIN" button.
+
Unless otherwise defined numbers are reported with one decimal. By specifying a value for "decimals" you can determine resolution of presented values.
−
File:twitter2.png|2. An additional window will pop-up (please make sure your browser's pop-up blocker does not block it!) where twitter asks you to log-in to your twitter account.
+
−
File:twitter2b.png|3. Please log-in and copy the pin that twitter does present to you.
+
−
File:twitter4.png|4. Switch back to Meteobridge page and Insert pin into input field next to "Activate PIN" button and press this button.
+
−
File:twitter3.png|5. Finally, insert message text that Meteobridge should tweet and set upload interval and retry count and press save to make these settings permanent. If Authentification with twitter does fail, you can start process with pressing "Request new PIN" from the start.
+
−
File:twitter5.png|6. To fill message text with weather data and/or a timestamp, you can make use of Meteobridge variables as explained in [[Templates]] section. Example above is a result of this message text: <font face="Courier"><span style="background-color:yellow;">[hh]:[mm]h Outdoor temp: [th0temp-act=F.1:--]°F </span></font face>
+
−
</gallery>
+
  
−
===Individual HTTP Upload===
+
==Replacement==
−
Data will be sent as HTTP GET requests with URL parmeters you can define to your liking. Parameters of a URL consist of name-value pairs seperated by '&'. You can define names yourself and can use a certain set of variables provided by Meteobridge to be used as values. Variable names will be automatically replaced by their current values, each time a HTTP request is sent. Please have a look at the example below.
+
When a variable is not defined or there is no data for a specified sensor, information specified as "replacement" string will be represented instead.
  
 +
==Examples==
 +
Having a look at examples usually helps to understand how easy that is.
  
−
[[file:http-upload.png]]
+
# Template <font face="Courier"><span style="background-color:light-grey;">Outdoor temperature is [th0temp-act=F.1:--]°F</span></font face> will be converted into <font face="Courier"><span style="background-color:yellow;">Outdoor temperature is 3.4°F</span></font face> when there is outdoor temp data and into <font face="Courier"><span style="background-color:yellow;">Outdoor temperature is --°F</span></font face> if outdoor temp sensor does not provide recent data.
−
 
+
# Template <font face="Courier"><span style="background-color:yellow;">Local time is [hh]:[mm]</span></font face> will be converted into <font face="Courier"><span style="background-color:yellow;">09:27</span></font face>.
−
 
+
# Template <font face="Courier"><span style="background-color:yellow;">Max gust in last 10 minutes was: [wind0wind-max10.1:--]m/s, [wind0wind-max10=mph.1:--]mph, [wind0wind-max10=kn.0:--]kn</span></font face> will be converted into <font face="Courier"><span style="background-color:yellow;">Max gust in last 10 minutes was: 10.5m/s, 23.5mph, 20kn</span></font face>.
−
Upload schedule is defined to every 5 seconds. URL specifies server address, where to deliver data ("http://myserver.com/upload.php" in the example above). "Success Condition" allows to specify a matching string which is compared to to the return message from the server to decide if upload was successful or not.
+
−
 
+
−
Weather data is transported to the server by means of URL parameters. Meteobridge provides a large set of variables that can be used to feed URL parameters with current sensor data. Section [[Templates]] will explain how to use these variables to fill URL parameters with recent sensor data.
+
−
 
+
−
===Individual MYSQL Uploads===
+
−
When you prefre to store your weather station's data in your own MYSQL database, Meteobridge can feed sensor data to it in a very easy way. Just state
+
−
* '''Host''': server name or IP of server when DNS can' resolv the name
+
−
* '''Port''': port number where to reach MYSQL database on your server
+
−
* '''Database''': name of database to feed
+
−
* '''User''': name of database user to use for data upload
+
−
* '''Password''': passwrod for user name.
+
−
* '''Query''': payload that should be sent to the database. Query usually contains a MSQL insert statement followed by a table name and a list of column names and values. The query ist subject to template replacement, so you can use Meteobridge variables to upload weather data to your database.
+
−
 
+
−
 
+
−
[[File:mysql.png]]
+
−
 
+
−
 
+
−
Query <font face="Courier"><span style="background-color:yellow;">insert upload (temp, wind) values ([th0temp-act.1:-9999], [wind0wind-act=kmh.1:-9999])</span></font face> in example above stores actual outdoor temperature to field "temp" of table "upload" of database "test". Field "wind" is filled with current non averaged wind speed in km/h. When temperature or wind data is not there a value of -9999 is stored.
+
−
 
+
−
Details of using variables in templates is explained in [[Templates]] section.
+

Revision as of 02:13, 27 January 2013

Meteobridge provides a very flexible mechanism to smuggle sensor data of different kinds into strings to be used by Meteobrdge push services like Twitter, HTTP GET uploads or MSQL database insert requests. Simply type in the text you want to upload and represent the pieces of sensor data by so called variables. When data gets uploaded, these variables will be replaced by current sensor data and so a string filled with the data you intended will be uploaded.

Each variable starts with an opening square bracket "[" and is terminated by a closing square bracket "]". The structure of the variable name between these brackets is as follows: 
sensor-selector=converter.decimals:replacement

"converter", "decimals" and "replacement" can be omitted, "sensor" and "type" are mandatory. While "sensor" tells what sensor and what piece of information of the sensor to use, "selector" decides data from what time period should be taken into account and "converter" does convert data into measurement units the user likes most. "Decimals" decides about precision the result should be shown in and "replacement" gives the string to be returned when there is no data for defined sensor available.

Sensors

These sensors are defined in Meteobridge.

  • th0temp: outdoor temperature in degrees Celsius
  • th0hum: relative outdoor humidity as percentage
  • th0dew: outdoor dew point in degrees Celsius
  • thb0temp: indoor temperature in degrees Celsius
  • thb0hum: indoor humidity as percentage
  • thb0dew: indoor dewpoint in degrees Celsius
  • thb0press: station pressure in hPa
  • thb0seapress: normalized pressure (computed to sea level) in hPa
  • wind0wind: wind speed in m/s
  • wind0avrwind: average windspeed in m/s (time used for average depends on station)
  • wind0dir: wind direction in degress (0° is North)
  • wind0chill: wind chill temperature in degrees Celsius
  • rain0rate: rain rate in mm/h
  • rain0total: rain fall in mm
  • uv0index: uv index
  • sol0rad: solar radiation in W/m^2

If a sensor is not there or data of sensor has passed the "tolerated data age" interval, Meteobridge will not provide data for it and will present the value defined as "replacement". If no replacement is given, variable will not be converted into data but will stay as is.

Selectors

Sensors are followed by a selector (syntactically separated by a dash) that specifies what period in time should be used for evaluation. Valid selectors are:

  • act: most recent data
  • hmin: minimum value of this hour
  • hmax: maximum value of this hour
  • dmin: minimum value of today
  • dmax: maximum value of today
  • mmin: minimum value of this month
  • mmax: maximum value of this month
  • hmin: minimum value of this year
  • hmax: maximum value of this year
  • hmin: minimum value of all time
  • hmax: maximum value of all time

Apart from selectors that use absolute, predefined time slots there are also selectors that look for a certain amount of time into the past.

  • max2, max5, max10, max15, max30, max60: selects the maximum value from the last 2, 5, 10, 15, 30 or 60 minutes
  • min2, min5, min10, min15, min30, min60: selects the minimum value from the last 2, 5, 10, 15, 30 or 60 minutes
  • avg2, avg5, avg10, avg15, avg30, avg60: selects average value from the last 2, 5, 10, 15, 30 or 60 minutes
  • sum2, sum5, sum10, sum15, sum30, sum60, sumday: selects summerized delta values from the last 2, 5, 10, 15, 30, 60 minutes or current day (useful to get amount of total rain in a certain time frame: "rain0total-sum60" is rainfall im mm of last 60 minutes, "rain0total-sumday" is todays rain fall)

Converters

Sensor data is reported in ISO units (°C, hPa, mm, m/s) by default, but can be converted into non-ISO units (imperial) by adding a conversion token. Defined tokens are:

  • F converts temperature from Celsius to Fahrenheit.
  • psi converts pressure from hPa (equivalent to mbar) to psi.
  • mmHg converts pressure from hPa to millimeters of mercury.
  • inHg converts pressure from hPa to inches of mercury.
  • kmh converts wind speed from meters per second to kilometers per hour.
  • mph converts wind speed from meters per second to miles per hour.
  • kn converts wind speed from meters per second to knots.
  • bft converts wind speed from meters per second to Beaufort scale.
  • in converts millimeters to inches.

If an unknown conversion string is used, no conversion will take place, no error message will appear.

Special Variables

There are a couple of variables that don't come as "sensor-selector=converter" chains but have a distinct meaning by themselves.

Date und time variables are defined as follows:

  • YYYY: year as four digit number
  • YY: year as two digit number
  • MM: month as two digit number, if only one digit neede a zero will be used as first digit
  • M: month as one or two digit number, no leading zeros
  • DD: day of month as two digit number, if only one digit neede a zero will be used as first digit
  • D: day of month as one or two digit number, no leading zeros
  • hh: hour as two digit number, if only one digit neede a zero will be used as first digit
  • h: hour as one or two digit number, no leading zeros
  • mm: minute as two digit number, if only one digit neede a zero will be used as first digit
  • m: minute as one or two digit number, no leading zeros
  • ss: seconds as two digit number, if only one digit neede a zero will be used as first digit
  • s: seconds as one or two digit number, no leading zeros

When a capital "U" preceeds a date/time variable name, UTC is used instead of local time ("[Uhh]:[Umm]:[Uss] UTC" is evaluated to a string like "16:03:33 UTC")

Decimals

Unless otherwise defined numbers are reported with one decimal. By specifying a value for "decimals" you can determine resolution of presented values.

Replacement

When a variable is not defined or there is no data for a specified sensor, information specified as "replacement" string will be represented instead.

Examples

Having a look at examples usually helps to understand how easy that is.

  1. Template Outdoor temperature is [th0temp-act=F.1:--]°F will be converted into Outdoor temperature is 3.4°F when there is outdoor temp data and into Outdoor temperature is --°F if outdoor temp sensor does not provide recent data.
  2. Template Local time is [hh]:[mm] will be converted into 09:27.
  3. Template Max gust in last 10 minutes was: [wind0wind-max10.1:--]m/s, [wind0wind-max10=mph.1:--]mph, [wind0wind-max10=kn.0:--]kn will be converted into Max gust in last 10 minutes was: 10.5m/s, 23.5mph, 20kn.
Retrieved from "https://wiki.meteoplug.com/wiki/index.php?title=Add-On_Services&oldid=890"