Difference between revisions of "Push Services"

Latest revision as of 15:44, 26 August 2021

xxxxxMeteobridge provides some additional "push services", which can distribute weather information to you via email, twitter, HTTP requests, FTP uploads, mysql queries or by invoking a user defined script. All these services can be triggered by certain alarm conditions, at a certain time of the day or in periodic intervals ranging from a few seconds to minutes or hours.

Configuring push services is done in two steps.

1. When you want to use a email, twitter, mysql or FTP you have to configure the basic authentication for these services fist.
2. Having gone the service configuration you can then define a specific event that makes use of one of the services.

When you first enter this tab has no events defined and looks like this:

Configuration Of Services

The services types twitter, email, mysql and FTP need some configuration before you can make use of it.

Twitter Upload

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 5 steps.

1. Press "Request PIN" button

2. An additional window will pop-up where twitter asks you to log-in to your twitter account

3. Please log-in and copy the pin that twitter does present to you

4. Insert pin into input field next to "Activate PIN" button and press the button

5. When PIN was accepted twitter service is marked with "Authentication: done" flag

Now twitter is ready to be used by events you will define later on.

Sending E-mails

Meteobridge can send largely customized e-mails. To get this service initialized you have to work through the following settings:

• Authentication: This drop-down box allows you to define the authentication mode used with the SMTP server. You can choose between:
  • none: This setting does not send any authentication information to the SMTP server. Only servers in closed LANs will provide that (if at all).
  • basic: Old-fashioned user name and password authentication, without SSL encryption
  • tls: authentication with SSL encryption (a variant not used very often)
  • starttls: standard authentication with SSL encryption (most often used)
• SMTP Host: specifies the IP or name of the SMTP server to use.
• Port: port number where SMTP server listens for mails (standard ports are 25 for non-SSL and 587 for SSL communication)
• User: user name to be used for authentication
• Password: password to be used
• To-Addr.: E-mail address of the recipient
• From-Addr.: E-mail address of the sender (many SMTP servers only accept mails with a sender address being in the same domain as the SMTP server itself)

Pressing the "Test" button sends an e-mail with subject "Meteobridge Test" to the given address. If sending the mail does not work, an error message will pop-up, trying to explain what went wrong.

MYSQL Uploads

When you prefer to store your weather station's data in your own MYSQL database, Meteobridge can feed sensor data to it in a very easy way. In order to support MYSQL queries some genric data must be specified.

• Host: server name or IP of server (when DNS can't resolve 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: password for user name.

When mysql service is not defined and not used by events, Meteobridge removes the storage intensive mysql libraries during boot. This is indicated by the orange "inactive" sticker. You can still define the mysql server credentials, but it will need an event definition making use of mysql saved and then the Meteobridge rebooted to get the mysql libraries ready for operation.

Sending SMS

Meteobridge can make use of SMS gateway MesageBird. To have this service working you just need a MessageBird account, which can be setup with a few simple steps.

1. Sign Up at MessageBird

Please get a personal account at http://www.messagebird.com where you also get a welcome credit of 10 free SMS to test with. When you successfully tested SMS service you can put some prepaid amount onto the Messagebird SMS account. Validation of payment will take 24 hours. After that your paid account is fully operational.

2. Get Your Personal Access Key

In the API section of your MessageBird account you will find the access key which Meteobridge needs to fire SMS via MessageBird.

3. Enter Access Key

Please enter the access key as shown in the picture below and press "Save". As Originator you can insert any string or phone number you want to be displayed as sender in the SMS message. The "access key" input field is a password field that usually does not show the given details. By selecting the "show" check box you will see the content.

4. Test SMS Operation

When you press the "Test SMS" button Meteobridge connects to MessageBird, tests credentials and returns balance of your account. When you are in tryout mode number of available free SMS will be shown and you can only use your own phone number to send SMS to. When you are a paying user your financial balance will be shown and you can send SMS to any recipient.

When sending SMS via Messagebird costs will occur. We recommend to use prepaid accounts only to limit you financial exposure. Please be aware that any misconfiguration of your SMS send service in Meteobridge or a Meteobridge malfunction can accidentially fire a lot of SMS messages and by that can eat up your account balance. smartbedded is in no way liable for anything happening with your Messagebird account. If you are not fine with this, please don't apply your SMS account details to Meteobridge.

FTP Uploads

Meteobridge allows you define a FTP server that can be bu used for uploading files. Per default Meteobridge just handles one FTP server, but you can define distinct directories and file names for each upload event later on. Setup of generic FTP upload credentials is done as follows:

• FTP Host: server name or IP of server (when DNS can't resolve the name)
• Port: port number where to reach FTP process on your server
• FTP User: user name to be used for FTP upload
• FTP Password: password to be used for FTP upload

In order to check if FTP credentials do work, you can press "Test Upload" button. Meteobridge will upload a file named "test-upload" with current time stamp as content to your FTP server. File will be located at directory that is default when doing FTP login. When you want to test upload to different directories you can specify an path in "Test Path" field. This path is used for test uploads only.

When you want to upload data to another FTP server, you can use a fully qualified URL-like FTP notation in the "Path" field. Format of the FTP URI has to be: ftp://user:password@host:port/path. Please notice that none of the elements is allowed to miss. Example: ftp://johndoe:mysecret@ftp.server.com:21/public_html/index.html

Definition Of Events

Meteobridge allows you to define up to 20 events that make use of push services. You have defined events listed at the top of the tab.

Adding an event is extremely easy. Just pull down the "Select Service" selector and choose the service type you want to use.

Next choose the type of event you want to define and then you press "Add Service Event" button.

Having done that a new service event will be added to the list of events and you can specify details of this specific event. Each event definition consists of a section where the trigger conditions are specified and a section that defines the payload the event is expected to transport via the service underneath.

Event Types

There are three event types to choose from that can be applied to all push services Meteobridge provides.

Periodical

This allows you to define the interval the event will be triggered. For some services it goes down to every 5 seconds and for the rest it is in the range of minutes up to hours. You simply select the repeating interval by a drop-down list.

Specific Time

Here you can define the time of day when the event has to be triggered. Time can be selected from a drop-down list in 15 minute steps.

Alarm Conditions

This allows you to specify the alarm trigger mode and conditions used for raising and clearing the alarm.

You can choose between "One-Time Alarms" which are triggered once and need to be cleared before they can fire again, and "Incremental Alarms" which allow a re-triggering of a non-cleared alarm, when the triggering event matches "raise condition" by a larger magnitude than the last trigger event.

• Raise Condition: defines the condition to be met in order to fire an alarm. Once an alarm is fired, it will not be fired again until the alarm is cleared again. When you have selected incremental alarms, an alarm can be fired again under certain circumstances. Details on condition statements are explained in "conditions" subsection below.
• Clear Condition: defines the condition to be met to clear a fired alarm. Details on condition statements are explained in "Alarm Conditions" subsection below.

There are two type of conditions that are formulated exactly the same way, but have different meaning. If a "raise condition" is satisfied, the related event service will be triggered. To trigger the services event again, it needs the "clear condition" to be satisfied first. The idea behind that is to suppress a large amount of follow-up event evocations on an event already given attention. For example, when raise condition is set to "outdoor temp at least 35°C" and clear condition is set to "outdoor temp below 30 °C" and resolution used for comparison is integer level (zero decimals) you will get a message once the temperature reaches 35° but will not get additional messages on that until the temperature has dropped below 30°C again. When you have selected "incremental alarms" and temperature raises from 34°C up to 37.2°C you will get one messages about reaching 35°C, one about reaching 36° and one about reaching 37°C threshold. This gives you the chance to notice how much the given threshold was passed.

Condition Expression

Condition expressions can make use multiple operators and brackets. Weather data can be used in terms of Meteobridge variables as explained in Templates section. Variables can be used enclosed by square brackets, like [th0temp-act=F.0:0], or without, like th0temp-act=F.0:0. Please make sure a variable is surrounded with blanks if you don't use square brackets. Defined operators are:

Result of the expression is interpreted as a boolean. Values above zero are regarded "true", values below or equal zero are regarded "false". When "incremental alarm" is specified, Meteobridge compares new value with former value and does trigger an alarm, when new value is bigger then the one that has triggered an alarm before.

Examples:

• [rain0total-sumday=mm:0] - 10
  triggers an alarm when todays rain exceeds 10mm. When alarm mode is set to "incremental alarm", every time rain increases above 10mm, a new alarm will be triggered. This happens because the expression does not return a boolean, but a value that regarded "true" when result is above zero (here, 10mm rain fall). Further increases will keep the condition "true" but will also increment the number and therefore, will fire additional alarms.
• [wind0wind-act=kmh.1:0] > 20 && ([wind0dir-act:180] >= 315 || [wind0dir-act:180] <= 45)
  triggers an alarm when non-averaged wind speed is more than 20 km/h and wind direction is mainly North (NW-NNW-N-NNE-NE).

Event Deletion

Getting rid of a defined event definition is simply done by pulling down the select box in front of the event definition and to press "save" after that.

Twitter Event

When you define a twitter event you just have to fill the "text message" with the message to be posted. Text message can make full use of Meteobridge template variables. The example below sends out a twitter message every day at noon that contains outdoor temperature in degrees Celsius.

Email Event

When you define an email event you have the fill the mandatory email body text field. If the optional "Addr.-To" field is left blank, then the email address from the email service definition at the bottom of the tab is used as default. Body text field is not allowed to make use double quotes (") but single quotes (') can be used. A maximum of 4000 characters can be used in the email body.

temp 12.3°C
gust 6.7kmh

SMS Event

When you define a SMS event you have the fill the mandatory message text field. Message text field is not allowed to make use double quotes (") but single quotes (') can be used.

In the example above at high noon a SMS is sent out showing the current temperature in degrees Celsius to the given recipient. Please be aware that recipient must be the phone number including the country code (1 for USA) but with out any leading "0" or "+".

FTP Event

Data to be uploaded via FTP cannot be stored on the Meteobridge as it does not provide the necessary persistent storage capacity. Therefore the templates to be filled with weather data have to reside on a server where Meteobridge can request it from by an URL. When the template URL is specified you have to press "Reload Template" to store the current version of the template into the RAM of the Meteobridge for further use. Beside the URL to the template you also have to define a path that defines to which folder of the FTP server the filled template should be uploaded to.

FTP Dashboard Example

Example above makes use of a pre-defined dashboard html file and fills it every 10 minutes with recent weather data and uploads it as file name "/public_html/dashboard.html" to the specified FTP server. The file "dashboard.html" is a simple HTML file with some Meteobridge weather variables included. When you view "dashboard.html" with your browser it looks like this:

Details of using variables in templates are explained in Templates section. To illustrate that using these variables is quite easy the HTML body part (omitting the CSS styles for formatting it nicely) of the template of above's example is attached below:

<body>
  <table id="table-2">
    <thead><tr><th>Sensor</th>
               <th>Current</th>
               <th>Today (min)</th>
               <th>Today (max)</th></tr></thead>
    <tbody>
      <tr><td>Outdoor Temperature</td>
          <td>[th0temp-act.1:--]° C</td>
          <td>[th0temp-dmin.1:--]° C</td>
          <td>[th0temp-dmax.1:--]° C</td></tr>
      <tr><td>Outdoor Humidity</td>
          <td>[th0hum-act.0:--] %</td>
          <td>[th0hum-dmin.0:--] %</td>
          <td>[th0hum-dmax.0:--] %</td></tr>
      <tr><td>Outdoor Dew Point</td>
          <td>[th0dew-act.1:--]° C</td>
          <td>[th0dew-dmin.1:--]° C</td>
          <td>[th0dew-dmax.1:--]° C</td></tr>
      <tr><td>Wind Chill Temperature</td>
          <td>[wind0chill-act.1:--]° C</td>
          <td>[wind0chill-dmin.1:--]° C</td>
          <td>[wind0chill-dmax.1:--]° C</td></tr>
      <tr><td>Air Pressure</td>
          <td>[thb0seapress-act.1:--] hPa</td>
          <td>[thb0seapress-dmin.1:--] hPa</td>
          <td>[thb0seapress-dmax.1:--] hPa</td></tr>
      <tr><td>Wind Direction</td>
          <td>[wind0dir-act.0:--]°</td>
          <td></td><td></td></tr>
      <tr><td>Wind Speed (averaged)</td>
          <td>[wind0avgwind-act.1:--] m/s</td>
          <td>[wind0avgwind-dmin.1:--] m/s</td>
          <td>[wind0avgwind-dmax.1:--] m/s</td></tr>
      <tr><td>Gust Speed</td>
          <td>[wind0wind-max5.1:--] m/s</td>
          <td>[wind0wind-dmin.1:--] m/s</td>
          <td>[wind0wind-dmax.1:--] m/s</td></tr>
      <tr><td>Rain</td>
          <td>rate: [rain0rate-act.1:--] mm/h</td>
          <td>sum [rain0total-sumday.1:--] mm</td>
          <td></td></tr>
      <tr><td>Solar Radiation</td>
          <td>[sol0rad-act.0:--] W/qm</td>
          <td>[sol0rad-dmin.0:--] W/qm</td>
          <td>[sol0rad-dmax.0:--] W/qm</td></tr>
      <tr><td>UV Index</td>
          <td>[uv0index-act.1:--] uvi</td>
          <td>[uv0index-dmin.1:--] uvi</td>
          <td>[uv0index-dmax.1:--] uvi</td></tr>
    </tbody>
  </table>
</body>

Saratoga Template Example

Meteobridge is supported by the well-known Saratoga templates, which allow you to easily build your own powerful weather homepage. Procedure how to install the php scripts and how to configure Meteobridge's FTP upload is described in detail here.

When having done the well explained and easy to do setup, your website will look like this:

FTP Camera Event

If Meteobridge drags pictures from a web cam or an Ubiquiti AirCam these pictures can also be uploaded via FTP. Here you just have to define the target path and file name, which can include date and time variables as specified by "strftime" GNU C function.

Example above stores a web cam picture every ten minutes and gives it a file name reflecting date and time like "2014-06-23_12:34_weatherpic.jpg". Details about "strftime" syntax can be found here.

HTTP Event

Meteobridge can send HTTP GET requests containing weather data as URL parameter. This can be used to feed individual weather networks. Beside the mandatory URL you can optionally define a success string that is matched against the data the requested web server returns to the Meteobridge.

• When the success string is empty, no checking against the returned data is done
• If the success string is not empty the returned data is analyzed and if the given success string is found in the returned data the transmission is expected to be successful, otherwise an Error is signaled.
• If the success string starts with an exclamation mark "!" the transmission is regarded successful when the string is not found in the returned data.

In the example above Meteobridge sends recent wind speed every 15 seconds to the specified server and assumes transmission went fine, when returned data does not include the string "Error".

MYSQL Event

Meteobridge can send queries to a mysql server, which can be used to register weather data into a regular database. The mandatory query text field will usually contain a mysql insert statement followed by a table name and a list of column names and values. The query is subject to template replacement, so you can use Meteobridge variables to upload weather data to your database.

In the example above Meteobridge sends recent temperature and average wind speed every 10 minutes to a mysql database.

Script Execution Event

Meteoridge can download executable shell scripts from an URL and can execute these scripts. When you define a new event of this type, please lead the script by the "Reload Script" button before trying to execute the script. The parameter text field is optional, in case the script can handle additional parameters. The documentation string is derived from the loaded script and just displays the first line of the script containing a "###" pattern.

Settings above define to trigger script stored at "http://templates.meteobridge.com/reboot.sh" every day at 23:45. There are no parameters to be handed over to the script. The script provides a one-line documentation, which is marked in the script by three leading '#'. As you can see the script below does mainly issue a "reboot" of the Meteobridge.

#!/bin/sh
#
### reboot Meteobridge; no parms
reboot
exit 0

Enhancements for Meteobridge PRO

Meteobridge PRO adds three functions to it. One is about automated backups of stored sensors data the other is about controlling the display in the front panel and the third allows to schedule data exports.

Automated Backups

Meteobridge PRO adds a backup script to the selection of shell scripts to be started on certain conditions. When triggered, this backup script looks for a connected USB drive (with a FAT or EXT3 filesystem) and copies the current database containing all stored sensor data to the USB drive. Copied file has a date/time stamp in the file name. When storage is getting low on the USB stick, the oldest backups will be deleted in order to be able to store new backups. This mechanism allows you to have an external USB stick constantly connected to the Meteobridge PRO and to schedule daily backups onto that, without worrying if USB stick gets filled up over time. While backup script is executed, logging of new data is halted (queued up). Script name in drop-down list is "backup".

Display Content

When Meteobridge PRO was given a display on the front panel the idea was not just to show some predefined sets of data there, but to give the user maximum freedom to display an kind of sensor data on it. We did not jump into this for providing graphs and curves on the display, as it is on 0.96" in diagonal, but what we did is providing mechanisms for providing textual data.

The core framework used for this is Google's u8g project which has been ported interpret commands given in a description language. Before we dig into details, please have a loo at the 3 predefined display options:

The first one reports wind/outdoor/indoor/rain/system data with swapping screen in ISO units, while the second one does the same with imperial units. Flow of screens is as follows:

In a nutshell the declaration that produces these screens is given in the "message" field in terms of a template, where Meteobridge fills in the current sensor data as it does with templates used for emails, twitter, etc. How this works is described in a separate chapter called "Meteobridge PRO Display".

Scheduled Data Exports

Meteobridge PRO allows to automate the generation of data exports. How data exports work and how the used templates look like is explained in PRO_History section.

Data export service can be easily defined by setting three parameters.

• Time Frame specifies when data export should be done. Possible values are shown the example above. Doing data export more frequently than every hour is not supported to keep system load in reasonable bounds.
• Resolution allows to pick the granularity used for data export. Values can be "minute", "hour", "month", "year". All combinations of time frames and resolution are allowed. Only exception is the combination "year - minute" which cannot be selected as it would result into a too large export file.
• Template presents you all the available data export templates (files with extension ".exp") stored in PC network share "templates".

When data export is executed a line in the message list (on "System" tab) will appear that reports about the data export and how many lines of export data have been generated. Example below generates on every new day the data from the day before in a resolution of one minute using template "standard-iso.exp".

Storing Templates Locally

Meteobridge PRO allows to hold templates and other data used by services on the USB store, which you can access as a PC network folder (SMB share). The table below explains in which sub folders of the SMB share Meteobridge PRO expects to find data for various services and file extensions expected from Meteobridge PRO. Files having right extension and residing in the correct sub folder will be presented in drop-down lists on Meteobrodge PROs services tab. This is the mapping of services, sub folders and file extensions.