Zum Ende der Metadaten springen
Zum Anfang der Metadaten

$response = msudp_send($msno, $udpport, $prefix, $sendstring/%LabelsAndValues);

 

Sends one or multiple values to the specified Loxone Miniserver via UDP.

You should prefer the function LoxBerry::IO::msudp_send_mem to take care for the Miniserver.

LoxBerry Compatibility

This feature first is available with LoxBerry 1.2.4. Set your LB_MINIMUM version in your plugin.cfg accordingly.

The function sends UDP messages to a specified Miniserver, and supports several methods for simple and extended use. 

The first parameter specifies the Miniserver number to use (numbers are equal to LoxBerry::System::get_miniservers, starting with 1).

The second parameter specifies the UDP port the messages should be sent.

The third parameter is a prefix for every UDP message, to identify the specific message in the command recognition of Virtual Inputs. If you don't want to prefix your message, use "" or undef for this parameter. When using the prefix, the prefix is sent as "$prefix: " (using a colon and blank). 

The forth parameter can be a full string that is sent to the Miniserver, or a hash with label/value pairs. See the examples below.

  • In the case of a full string, 
    • the string will be prefixed (if not omitted) 
    • and be sent untouched to the Miniserver. Keep  an eye on encoding.
  • In the case of a hash, 
    • Every line is prefixed (if not omitted)
    • the messages are sent as label=value label=value ...
    • The function will combine multiple pairs to one line, but will send multiple lines, if the values do not fit into one line (Miniserver limit of ~255 bytes per message). Every line is prefixed.



Parameter

ParameterRequiredBeschreibung
$msnoxNumber of the Miniserver


$udpportxUDP port the Miniserver is listening to
$prefixxA string as a prefix for every message
$sendstring / %LabelsAndValuesxA full string that is sent, or
a hash holding labels and values

Return value

The return value is undef, if an error occured, or any value, if the transmittion was successful.

Keep in mind, that UDP is not a stateful transmission protocol. The function may return OK, but that does not guarantee that the message was received from the Miniserver.

Usage

Single string

use LoxBerry::IO;

my $response = msudp_send(1, 10001, "MyPlugin", "Temperature=24.5°C Humidity=69% Rain=5mm");
if (! $response) {
	print STDERR "Error sending to Miniserver";
} else {
	print STDERR "Sent ok.";
}

# UDP message is:
# MyPlugin: Temperature=24.5°C Humidity=69% Rain=5mm

The return code is defined to be undef, if the call was not successful. If the code is not undef, it was successful.

Single label / value pair

use LoxBerry::IO;

my $response = msudp_send(1, 10001, "MyPlugin", "Temperature", "24.5");

# UDP message is:
# MyPlugin: Temperature=24.5

The return code is defined to be undef, if the call was not successful. If the code is not undef, it was successful.

Multiple values

use LoxBerry::IO;

my %data_to_send;
$data_to_send{'Temperature'} = 24.5;
$data_to_send{'Humidity'} = 69;
$data_to_send{'Rain'} = 5;

my $response = msudp_send(1, 10001, "MyPlugin", %data_to_send);
if (! $response) {
	print STDERR "Error sending data";
} 
# UDP message is:
# MyPlugin: Temperature=24.5 Humidity=69 Rain=5


# Long message example
my %longmessage;
$longmessage{'Very_Long_UDP_Messages'} = 1;
$longmessage{'Are_Split_Apart'} = 2;
$longmessage{'If_They_Reach'} = 3;
$longmessage{'The_Miniserver_Limit'} = 4;
$longmessage{'Of_About_255_Characters'} = 5;
msudp_send(1, 10001, "A very long udp message", %longmessage);


# UDP message is (not the real 255 limit, but to demonstrate):
# A very long udp message: Very_Long_UDP_Messages=1 Are_Split_Apart=2 If_They_Reach=3 The_Miniserver_Limit=4
# A very long udp message: Of_About_255_Characters=5

The return code is defined to be undef, if the call was not successful. If the code is not undef, it was successful.

Command Recognition

When using an own string for sending udp messages, the command recognition depends on your string.

Using the label/pair method for single or multiple values, the command recognition for all of your labels should look like this:

MyPlugin:\iTemperature=\i\v
MyPlugin:\iHumidity=\i\v
MyPlugin:\iRain=\i\v

This syntax is necessary, because key/value pairs in a hash do not have a sort order, and the UDP message may be splitted. 


  • Keine Stichwörter