Monitoring

1) First, open the HWg-SMS-GW3 web administration at the General setup tab. The most important parameters are IP Address and Port. Copy the IP Address (192.168.100.174 in this example) and enter it in HWg-WLD. 

2) Once the IP address of HWg-SMS-GW3 is determined, open the HWg-WLD web administration interface at the Remote SMS tab.

3) Enable the SMS Gateway and enter the IP address, the port and the phone number for receiving notifications. If the HWg-SMS-GW3 is secured, also enter the username and password. Finally, enter the SMS text. Remember to save everything. Depending on the desired SMS format, the default text can be used.

4) Then, select the test to perform. Both variants should be tested. The information window displays a successful test result.

5) If the test completed correctly, go to the Sensors tab and enable the Remote SMS option. 

Methods of sending text messages:

1. Using netGSM (SOAP - HTTP POST)
   1. Uploading a XML file using cURL
   2. Uploading a XML file using PHP
   3. Sending a SMS from Nagios
2. Using HTTP GET
   1. Sending a SMS from Nagios
   2. Sending a SMS using Wget
   3. Sending a SMS using cURL
   4. Sending a SMS from PRTG
3. Using the SNMP Write function

Sending text messages using the netGSM protocol

The netGSM protocol is based on SOAP; that is, sending a XML file using HTTP POST. For a description of the netGSM protocol, see: http://hw-group.us/product-version/netgsm

In a nutshell, HTTP POST is used to send a XML file (service.xml) with the following structure:

Send SMS:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header/>
  <soapenv:Body>
    <pos:QueueAdd>
      <Queue>GsmOut</Queue>
      <Gsm>
        <Cmd>SMS</Cmd>
        <Nmr>123456789</Nmr>
        <Text>Hello World!</Text>
      </Gsm>
    </pos:QueueAdd>
  </soapenv:Body>
</soapenv:Envelope>

Ring (Call):

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header/>
  <soapenv:Body>
    <pos:QueueAdd>
      <Queue>GsmOut</Queue>
      <Gsm>
        <Cmd>Call</Cmd>
        <Nmr>123456789</Nmr>
        <Text>Hello World!</Text>
      </Gsm>
    </pos:QueueAdd>
  </soapenv:Body>
</soapenv:Envelope>

For a description of individual parameters, see the above-mentioned protocol description.

Uploading a XML file using cURL

cURL is a command-line tool to transfer data using protocols such as HTTP, FTP and more. cURL consists of two parts – the curl.exe console application, and the libcurl.dll library that implements all the curl functions.

The library can be used for writing your own scripts (bindings are available for many languages).

cURL is available free of charge at https://curl.haxx.se/ (https://curl.haxx.se/download.html) however, attention must be paid to choose the correct version to download.

The 32-bit version will not work in a 64-bit Windows environment, even though it starts OK!

cURL is started from the command line with the following command:

curl -X POST -T service.xml 192.168.100.169

where

-X defines the transfer method, in this case POST
-T specifies that a file is uploaded and what is its name (the file must be in the same folder as the curl.exe utility; otherwise, the path must be given)
IP address is the address of HWg-SMS-GW3

If the HWg-SMS-GW3 is secured with a username and a password, the credentials must be specified with the -u parameter:

curl -X POST -T service.xml -u user:pass 192.168.100.169

The response is:

C:\Users\volmr\Desktop\curl>curl -X POST -T service.xml -u user:pass 192.168.100.169
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0   375    0     0    0     0      0      0 --:--:--  0:00:01 --:--:--     0<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pos="poseidonService.xsd">
<soapenv:Header/>
<soapenv:Body>
<pos:QueueAddResponse>
<Rslt>1</Rslt>
<ID>169</ID>
</pos:QueueAddResponse>
</soapenv:Body>
</soapenv:Envelope>
100   667  100   292  100   375    292    375  0:00:01  0:00:01 --:--:--   657
 
C:\Users\volmr\Desktop\curl>

Uploading a XML file using PHP

PHP is one of the most popular open source web scripting language. Sending a SMS from your own website is very simple; an example script follows:

<?php
 
$type = "SMS";
$nmr = "+420123456789";
$text =  "Hello world!";
 
$host = "mysmsgw.domain.com";
$port = 80;
$user = "username";
$pass = "password";
 
$xml = "<soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\">
	<soapenv:Header/>
	<soapenv:Body>
		<pos:QueueAdd>
			<Queue>GsmOut</Queue>
			<Gsm>
				<Cmd>".$type."</Cmd>
				<Nmr>".$nmr."</Nmr>
				<Text>".$text."</Text>
			</Gsm>
		</pos:QueueAdd>
	</soapenv:Body>
</soapenv:Envelope>";
 
$fp = @fsockopen($host, $port, $errno, $errstr, 30);
if (!$fp) {
    echo "$host:$port: $errstr ($errno)\r\n";
}
else {
    fwrite($fp, "POST /service.xml HTTP/1.0\r\n");
    fwrite($fp, "User-Agent: MyPHPTest\r\n");
    fwrite($fp, sprintf("Host: %s\r\n", $host));
    fwrite($fp, sprintf("Authorization: Basic %s\r\n", base64_encode($user . ":" . $pass)));
    fwrite($fp, sprintf("Content-Length: %d\r\n\r\n", strlen($xml)));
 
    fwrite($fp, $xml);
    while (!feof($fp)) {
        echo fgets($fp, 128);
    }
    fclose($fp);
}
 
?>

Simply fill out the address, username and password for your HWg-SMS-GW3 and everything works right away. The $type, $nmr and $text variables can be of course passed from other scripts.

Sending a SMS from Nagios

Nagios uses scripts written in Perl. The Netways company from Germany has provided the notify-poseidon-sms.pl script that can send up to 160 characters with this command:

./notify-poseidon-sms.pl -H 192.0.2.10 -M "Test message" -D 123456789

where:
-H – (Host) IP address of HWg-SMS-GW3
-M – (Message) message text
-D – (Destination) recipient’s telephone number

A limitation is that the script can only send SMS and cannot ring the recipient’s phone number; however, this can be easily changed, see e.g. notify-poseidon-call.pl (see the attachments). Also, it does not support http authentication.

Example of use in Windows:

C:\Users\volmr\Desktop\curl>perl notify-poseidon-sms.pl -H 192.168.100.169 -M "Hello World!" -D 123456789
OK, message sent with ID 1 to '123456789'
 
C:\Users\volmr\Desktop\curl>

Sending text messages using HTTP GET

HTTP GET is a method where all parameters are passed directly in the URL. This method is often used for simple applications because it allows for simple debugging and is easy to code. One simply invokes the address with the necessary parameters:

Send SMS:

values.xml?Cmd=SMS&Nmr=00420123456789&Text=Hello World!

Ring (Call):

values.xml?Cmd=Call&Nmr=00420123456789

where:
Values.xml – file in the GW that the command should process. It is either values.xml or service.xml
Cmd – command that instructs what the GW should do: SMS – send a text message, Call – ring the number
Nmr – phone number in national or international format. It is recommended to use 00 instead of the “+” sign so that there is no need to replace the “+” with an entity
Text – message text encoded in UTF-8

A disadvantage is that the HTTP GET method, natively used to display WWW pages, is difficult to secure against misuse (one would need to set WWW Security, which then prevents unrestricted browsing of the HWg-SMS-GW3 web interface).

And even then, the login credentials are sent in the URL in the open:

Send SMS:

http://user:pass@192.168.1.1/values.xml?Cmd=SMS&Nmr=123456789&Text=Hello World!

Ring (Call):

http://user:pass@192.168.1.1/values.xml?Cmd=Call&Nmr=123456789

For these reasons, the sending of messages via HTTP GET is disabled by default, and must be manually enabled at the GSM Modem tab if it is needed:

Sending a SMS from a web browser

Enter the URL of HWg-SMS-GW3 including the requested commands into the address field of the web browser:

SMS:

http://192.168.100.169/values.xml?Cmd=SMS&Nmr=123456789&Text=Hello World!

Ring (Call):

http://192.168.100.169/values.xml?Cmd=Call&Nmr=123456789

After sending, a XML confirmation appears:

<Root>
  <QueueAddResponse>
    <Rslt>1</Rslt>
    <ID>2</ID>
  </QueueAddResponse>
</Root>

Sending SMS using Wget

GNU Wget is a command-line utility that serves as a simple but powerful http client. It implements file transfer over HTTP, HTTPS and FTP protocols. It is available at https://www.gnu.org/software/wget/ and Windows versions are available at http://gnuwin32.sourceforge.net/packages/wget.htm

Wget is very simple to use – simply enter the same command that would be entered in the browser address field. However, the entire URL must be enclosed in double quotes:

Send SMS:

wget "http://192.168.100.169/values.xml?Cmd=SMS&Nmr=123456789&Text=Hello World!"

Ring (Call):

wget "http://192.168.100.169/values.xml?Cmd=Call&Nmr=123456789"

The result looks like this (to SMS command):

C:\Users\volmr\Desktop\wget>wget "http://192.168.100.169/values.xml?Cmd=SMS&Nmr=123456789&Text=Hello World!"
--2017-12-28 15:56:35--  http://192.168.100.169/values.xml?Cmd=SMS&Nmr=777232759&Text=Hello%20World!
Connecting to 192.168.100.169:80... connected.
HTTP request sent, awaiting response... 200 Ok
Length: unspecified [text/xml]
Saving to: 'values.xml@Cmd=SMS&Nmr=123456789&Text=Hello%20World!.1'
 
values.xml@Cmd=SMS&Nmr=777232     [ <=>                                              ]     118  --.-KB/s    in 0s
 
2017-12-28 15:56:35 (5.48 MB/s) - 'values.xml@Cmd=SMS&Nmr=123456789&Text=Hello%20World!.1' saved [118]
 
C:\Users\volmr\Desktop\wget>

Sending SMS using cURL

The cURL utility is used in the same way as the wget utility. This is the command:

SMS:

curl "http://192.168.100.169/values.xml?Cmd=SMS&Nmr=123456789&Text=Hello World!"

Ring (Call):

curl "http://192.168.100.169/values.xml?Cmd=Call&Nmr=123456789"

And this is the application’s response (to SMS command):

C:\Users\volmr\Desktop\curl>curl "http://192.168.100.169/values.xml?Cmd=SMS&Nmr=123456789&Text=Hello World!"
<?xml version="1.0" encoding="utf-8"?>
<Root>
<QueueAddResponse>
<Rslt>1</Rslt>
<ID>4</ID>
</QueueAddResponse>
</Root>
C:\Users\volmr\Desktop\curl>

Of course, the main result is that the message is sent.

Sending a SMS from PRTG

PRTG Network Monitor is a complex network monitoring solution that combines Paessler’s expertise with a complete set of monitoring functions, intuitive and easy-to-use UI and the most advanced monitoring tool suitable for all types of networks.

PRTG Network Monitor can send text messages using the HTTP GET method. The setting up only involves specifying a URL for sending the messages.

This is done with the Enterprise Console (application or WWW interface) in Setup > System Administration > Notification Delivery. The Custom URL field should contain:

http://IP_address/values.xml?Cmd=SMS&Nmr=%SMSNUMBER&Text=%SMSTEXT 

This ensures that the SMSNUMBER and SMSTEXT system variables are inserted at the correct places in the URL.

PRTG currently does not support security using username and password!

Sending a SMS using the SNMP Write function (snmpset)

Starting from firmware version 1.1.3, HWg-SMS-GW3 supports the sending of SMS and dialing of numbers using SNMP. SNMP write, or more exactly SNMP SET function, is used for that purpose.

However, it is necessary to write all the 3 required OIDs for the recipient’s number, message text and function (SMS/ring/SMS+ring). The OIDs are the following:

• msgQueueNmr (OID .1.3.6.1.4.1.21796.4.10.2.2.0) - (mandatory) Recipient’s phone number in national or international format. The international format can use either “+” or “00”.
• msgQueueCmd (OID .1.3.6.1.4.1.21796.4.10.2.3.0) - (mandatory) Action: 1=sms, 2=ring, 3=sms+ring
• msgQueueText (OID .1.3.6.1.4.1.21796.4.10.2.1.0) - (mandatory) Message text. Can be omitted if the requested action is ring only.

In a concrete example (Send SMS), the individual commands could look like this:

snmpset -v 1 -c private 192.168.100.169 1.3.6.1.4.1.21796.4.10.2.2.0 s: 123456789
snmpset -v 1 -c private 192.168.100.169 1.3.6.1.4.1.21796.4.10.2.1.0 s "Hello World!" 
snmpset -v 1 -c private 192.168.100.169 1.3.6.1.4.1.21796.4.10.2.3.0 i: 1

When the commands are entered in the command line, the following appears:

C:\usr\bin>snmpset -v 1 -c private 192.168.100.169 1.3.6.1.4.1.21796.4.10.2.2.0 s: 123456789
SNMPv2-SMI::enterprises.21796.4.10.2.2.0 = STRING: 123456789
 
C:\usr\bin>snmpset -v 1 -c private 192.168.100.169 1.3.6.1.4.1.21796.4.10.2.1.0 s "Hello World!"
SNMPv2-SMI::enterprises.21796.4.10.2.1.0 = STRING: "Hello World!"
 
C:\usr\bin>snmpset -v 1 -c private 192.168.100.169 1.3.6.1.4.1.21796.4.10.2.3.0 i: 1
SNMPv2-SMI::enterprises.21796.4.10.2.3.0 = INTEGER: 1
 
C:\usr\bin>

The command to Ring (Call) the number then looks like this:

snmpset -v 1 -c private 192.168.100.169 1.3.6.1.4.1.21796.4.10.2.2.0 s: 123456789
snmpset -v 1 -c private 192.168.100.169 1.3.6.1.4.1.21796.4.10.2.3.0 i: 2

and the response:

C:\usr\bin>snmpset -v 1 -c private 192.168.100.169 1.3.6.1.4.1.21796.4.10.2.2.0 s: 123456789
SNMPv2-SMI::enterprises.21796.4.10.2.2.0 = STRING: 123456789
 
C:\usr\bin>snmpset -v 1 -c private 192.168.100.169 1.3.6.1.4.1.21796.4.10.2.3.0 i: 2
SNMPv2-SMI::enterprises.21796.4.10.2.3.0 = INTEGER: 2
 
C:\usr\bin>

 

The hidden option is activated on the System page of the HWg-PWRx:

In the Password field (first line only), enter #Hwg

This activates the Secret Setup:

Here, enable the Mbus Meter Model Enable function. Then, switch to the page for the particular meter. The following item is displayed:

Select and save to activate the corresponding mode.

In order to read the values with different requests, the particular meter needs to be manually added to HWg-PWR once more. At the Device page, copy the SEC address of the meter: 

Then, click the Manual Add link at the same page. A dialog for adding a device manually appears. Enter the meter’s secondary address and select it for use for the reading.

After saving the changes, continue with the automatic finding of values as usual.

Reliable protocol

Existing features of SNMP traps meant trasfer via UDP protocol, which is not confirmed, in other words the side which sent a trap, does not know whether it was recieved by target device. The UDP packets are very fast and short, however there might be losses, which is not suitable for Box2Box use. TCP protocol on the other hand has all packets confirmed, so when data are not recieved, the source device is prompted to resend it again.

Repeated each 60s

When using Box2Box mode via SNMP Traps, commands for switching on and off are always sent only at the moment when a condition for sending an alarm trap is met (start or end of an alarm). When you have an application which allows you to reset the remote device (e.g. due to power outage) with controlled output, this transmission is not suitable, because after restart (power on),  the remote device doesn‘t know that it has to switch the output. In the case of Virtual outputs an instruction is sent each 60s for as long as a condition switching remote output remains valid. The problem is solved.

Secure communication

In remote equipment, communication for virtual outputs can be secured by a username and password (level Read only + Outputs or Read + Write). SNMP Traps do not have this feature.

You can apply the same functions to Virutal Outputs as to physical ones

After adding a virtual output to unit Poseidon2 or Damocles2, this output will be displayed in the same tab with the same parameters as for the physical output. All conditions can be applied and atributes as for the physical one, including the option of creating pulse output.

How it all works

First we define on the Virtual Outputs tab virtual output. Normaly there can be up to 8 and they are off in default mode. After enabling, the following can be configured: the name, the IP address of the remote device, ID  remote output (can be found in the Outputs tab); if the device is secured by authentication, we can set a username and password (levels Read only + Outputs or Read + Write).

After save we can see the output on tab Outputs and we can configure it as we need

Reaction time for switching the remote output is around 1,5-2,5s.

How MQTT works

MQTT works at the TCP layer in a way similar to SNMP Traps. There is no request-response communication; instead, data are sent ("published") and acknowledged. This reduces network load: individual “input” devices (sensors, detectors etc.) actively send only short TCP messages to a specified address (to a “broker”).

The advantage is that the input devices only transmit whenever they need to – in regular intervals, or according to other manufacturer-specified criteria (input closed or open, a threshold exceeded, a value increase or decrease, etc.).
Each message begins with a “Topic” that identifies, characterizes or groups the data.

Broker

A MQTT broker primarily acts as a server, that is, it receives and stores data. However, it can also act as a client (input device) towards other brokers and forward data to all subscribed subscribers. Such a subscriber can be, for example, a web service, an application, or another broker.

End devices send data to specified broker addresses, subscribers subscribe to brokers (just like customers sign up to receive e-mail newsletters). When a broker receives a message with a Topic corresponding to a subscription, the message is stored and distributed to the subscribers.

Topic

The MQTT topic is always a text string. The slash (/) sign can be used to form a tree structure. The topic can look like this:

Poseidon/1-Wire/temperature/856275
GTS/nagano/room1/temperature

A subscriber can subscribe to a particular topic, to a tree branch, or to the entire tree.
The following wildcard characters can be used in the topic: “#”, “+” and “$”.

• “+” stands for a whole level (Poseidon/+/temperature/856275).
• “#” stands for several levels (Poseidon/#);
  „#“ can only be used at the end of the string.
• Topics that begin with a “$” (dollar sign) are special – usually system topics.
• When a topic begins with “$”, it is a special topic (such as $SYS/broker/uptime).

The Topic also includes a QoS flag that specifies whether the message must be delivered. 0 means that successful delivery is not required; 1 allows duplicate delivery (if there is no acknowledgement, the message is resent); and 2 indicates that successful delivery is required but without any duplicity.

Payload

MQTT payload is the actual message content. The message content is normally assumed to be textual. However, the MQTT protocol is not restrictive and it is up to the broker and the subscribers to handle the payload. So, the payload can be binary, or can consist e.g. of images. Message size and type are specified by the broker. Many brokers prefer XML or JSON because these formats are less resource-consuming for larger volumes of data than many short “topic” messages.

Security

By default, the MQTT protocol communicates via TCP at port 1883. Security can be enhanced with SSL/TLS; in this case, the communication takes place at port 8883.

MQTT in Poseidon2 and Damocles2

Poseidon2 and Damocles2 units include a MQTT client implementation with optional SSL support.

• MQTT enable – Enables or disables MQTT support in Poseidon2 and Damocles2 devices.
• Server – IP address or domain name of the MQTT broker (server).
• Port – TCP port where the broker listens.
• Username – Username for authenticating TCP communication.
• Password – Password for authenticating TCP communication.
• Secure SSL mode – Enables/disables SSL mode.                           
• Client ID – ID of the client for use in MQTT. Users enter their IDs themselves in their profile. A user can use multiple IDs in order to filter messages in their account.                        
• Publish Period – Period for transmitting measured data. In this the interval (in seconds) Poseidon2 periodically connects to the broker to transmit the values.
• Topic Prefix Name – Topic prefix. The entire Topic is then formed by concatenating the prefix + the topic below.
• Publish – Selects information to be sent.
• User Topic umožňuje vytvoření uživatelského topicu (zprávy) obsahujícího data jaké požaduje uživatelská aplikace (JSON, XML, CSV a pod.). K tomu slouží makropříkazy uvedené níže
  • User Topic Enable – zapne zasílání uživatelské zprávy
  • Topic Name - Název zprávy
  • Topic Value – šablona uživatelské zprávy
  • Topic Test – náhled výsledné zprávy po přeložení maker

Macros for User topic:

%ID_IN_*% - Start of sequence of the inputs with firmly defined ID’s %ID_IN_END% - End of the fixed sequence of the inputs
%LOOP_IN% - Beginning of the sequence of the inputs that passes all ID’s %LOOP_IN_END% - End of the complete sequence of the inputs
%ID_OUT_*% - Start sequence of the outputs with firmly defined ID’s %ID_OUT_END% - End of fixed sequence of the outputs
%LOOP_OUT% - Start sequence outputs that passes all ID’s
%LOOP_OUT_END% - End of the complete sequence of the outputs
%ID_SENSOR_*% - Start sequence with sensors firmly defined ID’s %ID_SENSOR_END% - End of fixed sequence sensors
%LOOP_SENSOR% - Start sequence of sensors that passes all ID’s %LOOP_SENSOR_END% - End of the complete sequence of sensors
%VAL_ID% - Variable ID item
%VAL_NAME% variable name item
%VAL_VALUE% - variable values of the item
%VAL_STATE% - state variables of the item

Username and password are optional. For example, broker.mqttdashboard.com does not require them yet.

MQTT in practice

There are many public MQTT brokers where data can be sent and topics can be subscribed to. A list of the most well-known ones is available at: https://github.com/mqtt/mqtt.github.io/wiki/public_brokers

For our example, we have chosen broker.mqttdashboard.com. First, configure the Poseidon2 device:

Fill in the Server address, Port, Client ID (any value) and Topic Prefix Name (anything that can be used to distinguish the device). Using the Publish checkboxes, select the data to be published.
Then, Poseidon2 or Damocles2 needs to be restarted.  

Start the TT3 tool. It is essentially a MQTT Broker. It is available at: https://github.com/mqtt/mqtt.github.io/wiki/public_brokers

Set the broker (Server) address and Port (both values must be the same as in the Poseidon2), and a Client ID (must be different from the Poseidon Client ID). Then click Connect. The green status field in the lower right-hand corner will show Connected.

Then, in the Topic field, fil in the address that interests you. For example, “Poseidon2/#” means all messages whose Topic begins with Poseidon2/. Click Subscribe to start receiving messages.