LaMetric/FHEM/70_LaMetric.pm

# $id$
############################################################################
#
#     70_LaMetric.pm
#    
#     Copyright (C) 2017 by Michael Förster <mfo1009@googlemail.com>
#
#     API-Doc:  http://lametric-documentation.readthedocs.io/en/latest/
#     API-Keys: https://developer.lametric.com/user/devices
#    
#     This program is free software; you can redistribute it and/or modify
#     it under the terms of the GNU General Public License as published by
#     the Free Software Foundation; either version 2 of the License, or 
#     (at your option) any later version.
#    
#     This program is distributed in the hope that it will be useful,
#     but WITHOUT ANY WARRANTY; without even the implied warranty of
#     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
#     GNU General Public License for more details.
#    
#     You should have received a copy of the GNU General Public License
#     along with fhem.  If not, see <http://www.gnu.org/licenses/>.
#
############################################################################

package main;
use strict;
use warnings;
#use HttpUtils;
use Switch;
use JSON;
use Data::Dumper qw(Dumper);

#** @method public LaMetric_Initialize($hash)
# This method will initialize a LaMetric modul in FHEM framework. 
# 
# @link https://wiki.fhem.de/wiki/DevelopmentModuleIntro#X_Initialize
# @param hash - required hash (device hash)
#*
sub LaMetric_Initialize($) {
	my ($hash) = @_;

	# define FHEM functions
	$hash->{DefFn}    = "LaMetric_Define";
	$hash->{UndefFn}  = "LaMetric_Undef";
	$hash->{SetFn}    = "LaMetric_Set";
	$hash->{GetFn}    = "LaMetric_Get";
	$hash->{MODULE_VERSION} = "1.0.1";

	# set attrList
	no warnings 'qw';
	my @attrList = qw(
		disable:0,1 
		LaMetric_icon 
		LaMetric_info_type:none,info,alert 
		LaMetric_priority:info,warning,critical 
		LaMetric_cycles:1,2,3,4,5,6,7,8,9,10 
		LaMetric_lifetime:1,2,3,4,5,6,7,8,9,10 
		LaMetric_sound_repeat:1,2,3 
		LaMetric_sound:none,bicycle,car,cash,cat,dog,dog2,energy,knock-knock,letter_email,lose1,lose2,negative1,negative2,negative3,negative4,negative5,notification,notification2,notification3,notification4,open_door,positive1,positive2,positive3,positive4,positive5,positive6,statistic,thunder,water1,water2,win,win2,wind,wind_short 
		LaMetric_AppPushEndpoint
		LaMetric_AppPushToken

	);
	#		LaMetric_alarm:alarm1,alarm2,alarm3,alarm4,alarm5,alarm6,alarm7,alarm8,alarm9,alarm10,alarm11,alarm12,alarm13
	use warnings 'qw';

	$hash->{AttrList} = join(" ", @attrList ) . " " . $readingFnAttributes;

	#$hash->{parseParams} = 1; # not possible due to legacy msg command schema
	$hash->{'.msgParams'} = { parseParams => 1, };
}

#** @method public LaMetric_Define($hash, $def)
# This method will define a LaMetric device in FHEM framework. 
# 
# @link https://wiki.fhem.de/wiki/DevelopmentModuleIntro#X_Define
# @param hash - required hash (device hash)
# @param def  - required string (define parameters)
#*
sub LaMetric_Define($$) {
	my ($hash, $def) = @_;
	my @a    = split("[ \t]+", $def);
	my $name = shift @a;
	my $type = shift @a;

	Log3 $name, 3, "Load LaMetric $name";
	Log3 $name, 5, "LaMetric $name: called function LaMetric_Define()";

	# test of correct number of define parameters
	return "Invalid number of arguments: "
	  . "define <name> LaMetricAler <Api Key> <LaMetric IP>"
	  if (int(@a) < 2);
	  
	# get parameters and assign them to device internals
	my ($host, $APIkey) = @a;

	if (defined($host) && defined($APIkey)) {
		$hash->{HOST}   = $host;
		$hash->{APIKEY} = $APIkey;

		# initialize timer
		InternalTimer(gettimeofday() + 2, "LaMetric_GetUpdate", $hash, 0);
		return undef;
	}
	else {
		return "LaMetric IP or Api Key missing.";
	}
	return undef;
}

#** @method public LaMetric_Undef($hash, $name)
# This method will undefine a LaMetric device in FHEM framework. 
# 
# @link https://wiki.fhem.de/wiki/DevelopmentModuleIntro#X_Undef
# @param hash - required hash (device hash)
# @param name - required string (name of the device)
#*
sub LaMetric_Undef($$) {
	my ($hash, $name) = @_;
	RemoveInternalTimer($hash);
	return undef;
}

#** @method public LaMetric_Set($hash, $name, $cmd, @args)
# This method is called by FHEM set device command. 
# 
# @link https://wiki.fhem.de/wiki/DevelopmentModuleIntro#X_Set
# @param hash - required hash (device hash)
# @param name - required string (name of the device)
# @param cmd  - required string (command of the FHEM set function)
# @param args - required string (arguments of the FHEM set cmd function)
#*
#
sub LaMetric_Set($$$@) {
	my ($hash, $name, $cmd, @args) = @_;
	my ($a, $h) = parseParams(join " ", @args);

	Log3 $name, 5, "LaMetric $name: called function LaMetric_Set()";

	# test given command
	unless ($cmd =~ /^(msg|privatemsg|audio_volume|display_brightness|display_brightness_mode|nextapp|prevapp)$/i) {
		my $usage = "Unknown argument $cmd, choose one of msg audio_volume:slider,0,1,100 display_brightness:slider,0,1,100 display_brightness_mode:auto,manual nextapp:noArg prevapp:noArg";
		return $usage;
	}

	# call command based methods
	return LaMetric_SetAppNextPrev($hash, 'next')                   if ( $cmd eq 'nextapp' );
	return LaMetric_SetAppNextPrev($hash, 'prev')                   if ( $cmd eq 'prevapp' );
	return LaMetric_SendMessage($hash, $cmd, $a, $h)                if ( $cmd eq 'msg' );
	return LaMetric_PrivateAppPush($hash, $cmd, $a, $h)             if ( $cmd eq 'privatemsg' );
	return LaMetric_SetAudioVolume($hash, $cmd, $a, $h)             if ( $cmd eq 'audio_volume' );
	return LaMetric_SetDisplayBrightnesse($hash, $cmd, $a, $h)      if ( $cmd eq 'display_brightness' );
	return LaMetric_SetDisplayBrightnesseMode($hash, $cmd, $a, $h)  if ( $cmd eq 'display_brightness_mode' );

	return undef;
}

#** @method public LaMetric_Get($hash, $name, $cmd, @args)
# This method is called by FHEM get device command. 
# 
# @link https://wiki.fhem.de/wiki/DevelopmentModuleIntro#X_Get
# @param hash - required hash (device hash)
# @param name - required string (name of the device)
# @param opt  - required string (option of the FHEM get function)
# @param args - required string (arguments of the FHEM get opt function)
#*
#
sub LaMetric_Get($$$@) {
	my ($hash, $name, $opt, @args) = @_;
	
	Log3 $name, 5, "LaMetric $name: called function LaMetric_Get()";

	# test given command
	unless ($opt =~ /^(status)$/i) {
		my $usage = "Unknown argument $opt, choose one of status:noArg";
		return $usage;
	}

	# call command based methods
	return LaMetric_DeviceInfo($hash, $name)  if ($opt eq 'status');

	return undef;
}

#** @method public LaMetric_GetUpdate($hash)
# This method is called from internal FHEM Timer to get status update from LaMetric device.
# 
# @link https://wiki.fhem.de/wiki/DevelopmentModuleAPI#InternalTimer
# @param hash - required hash (device hash)
#*
#
sub LaMetric_GetUpdate($) {
	my ($hash) = @_;
	my $name = $hash->{NAME};
	Log3 $name, 5, "LaMetric $name: called function LaMetric_Get()";
	
	# get device info and set new timer
	LaMetric_DeviceInfo($hash, $name);
	InternalTimer(gettimeofday() + 300, "LaMetric_GetUpdate", $hash, 1);
}

#** @method public LaMetric_PrivatePush($hash, $cmd, $a, $h)
# This method sends a nottification to the LaMetric device.
# 
# @link http://lametric-documentation.readthedocs.io/en/latest/reference-docs/device-notifications.html#display-notification
# @param hash - required hash (device hash)
# @param cmd  - required string (command of the FHEM set function)
# @param a    - required array (of all unnamed parameters)
# @param h    - required reference (of all named parameters)
#*
#

sub LaMetric_PrivateAppPush($$$$) {
	my ($hash, $cmd, $a, $h) = @_;
	my $name    = $hash->{NAME};
	my %values  = ();
	my $message = join ' ', @$a;
	my $json;

	my $endpoint = "/api/v1/dev/widget/update/" . AttrVal($hash->{NAME}, "LaMetric_AppPushEndpoint", "");
	my $token = AttrVal($hash->{NAME}, "LaMetric_AppPushToken", "");
 	
 	$values{LaMetric_icon} = AttrVal( $hash->{NAME}, "LaMetric_icon", "i620" );

 	if ($h->{icon}) { $values{LaMetric_icon} = $h->{icon}; }
	if ($message eq "") { $message ="???";}

	if ($h->{icon} eq "none") { 
		$json = sprintf('{ "frames": [{ "index": 0, "text": "%s" }] }', $message),
	} else {
		$json = sprintf('{ "frames": [{ "index": 0, "text": "%s", "icon": "%s" }] }', $message, $values{LaMetric_icon}),
	}

	# sends a html request
	HttpUtils_NonblockingGet({ 
		url         => "https://".$hash->{HOST}.":4343".$endpoint, 
		#auth        => "dev:".$hash->{APIKEY},
		user        => "dev",
		pwd         => $hash->{APIKEY},
		hash        => $hash,  
		data        => $json,
		method      => "POST",
		httpversion => "1.1",
		timeout     => 3,
		loglevel    => AttrVal($name, "httpLoglevel", 4),
		header      => {
			'Agent'          => 'FHEM-LaMetric/1.0.0',
			'User-Agent'     => 'FHEM-LaMetric/1.0.0',
			'Accept-Charset' => 'UTF-8',
			'Accept-Charset' => 'application/json',
			'Cache-Control'  => 'no-cache',
			'X-Access-Token' => $token,
		},
		# upodate status and device info on response
		callback    => sub(){ 
			#mf#Log3 $name, 5, "LaMetric $name: ". $_[0]->{httpheader};
			#LaMetric_Status($hash, $_[0]->{code});
			#LaMetric_DeviceInfo($hash, $name);
		}
	});
}

#** @method public LaMetric_SendMessage($hash, $cmd, $a, $h)
# This method sends a nottification to the LaMetric device.
# 
# @link http://lametric-documentation.readthedocs.io/en/latest/reference-docs/device-notifications.html#display-notification
# @param hash - required hash (device hash)
# @param cmd  - required string (command of the FHEM set function)
# @param a    - required array (of all unnamed parameters)
# @param h    - required reference (of all named parameters)
#*
#
sub LaMetric_SendMessage($$$$) {
	my ($hash, $cmd, $a, $h) = @_;
	my $name    = $hash->{NAME};
	my %values  = ();
	my $message = join ' ', @$a;
	my $json;

	Log3 $name, 5, "LaMetric $name: called function LaMetric_SendMessage()";

	# set defaults
	$values{LaMetric_sound}        = AttrVal( $hash->{NAME}, "LaMetric_sound", "notification" );
	$values{LaMetric_sound_repeat} = AttrVal( $hash->{NAME}, "LaMetric_sound_repeat", "1" );
	$values{LaMetric_cycles}       = AttrVal( $hash->{NAME}, "LaMetric_cycles", "1" );
	$values{LaMetric_icon}         = AttrVal( $hash->{NAME}, "LaMetric_icon", "i620" );
	$values{LaMetric_info_type}    = AttrVal( $hash->{NAME}, "LaMetric_info_type", "none" );
	$values{LaMetric_alarm}        = AttrVal( $hash->{NAME}, "LaMetric_alarm", "alarm1" );
	$values{LaMetric_priority}     = AttrVal( $hash->{NAME}, "LaMetric_priority", "warning" );
	$values{LaMetric_lifetime}     = AttrVal( $hash->{NAME}, "LaMetric_lifetime", "120" ) * 1000;

	# override default settings, while option is in text
	if ($h->{sound})     { $values{LaMetric_sound}     = $h->{sound}; }
	if ($h->{icon})      { $values{LaMetric_icon}      = $h->{icon}; }
	if ($h->{cycle})     { $values{LaMetric_cycles}    = $h->{cycle}; }
	if ($h->{priority})  { $values{LaMetric_priority}  = $h->{priority}; }
	if ($h->{info_type}) { $values{LaMetric_info_type} = $h->{info_type}; }

	# set default message if empty
	if ($message eq "") { 
		$message ="???";
	}

	if ($values{LaMetric_icon} eq "none") { 
		$values{LaMetric_icon} = "null";
	}

	# create json request
	if ($values{LaMetric_sound} eq "none") {
		# without sound
		$json = '
			{
				"priority": "'.$values{LaMetric_priority}.'",
				"icon_type":"'.$values{LaMetric_info_type}.'",
				"lifeTime":'.$values{LaMetric_lifetime}.',
				"model": {
					"frames": [
						{
							"icon": "'.$values{LaMetric_icon}.'",
							"text": "'.$message.'"
						}
					],
				"cycles": '.$values{LaMetric_cycles}.'
			  }
			}
		';
	} else {
		# with sound
		$json = '
			{
				"priority": "'.$values{LaMetric_priority}.'",
				"icon_type":"'.$values{LaMetric_info_type}.'",
				"lifeTime":'.$values{LaMetric_lifetime}.',
				"model": {
					"frames": [
						{
							"icon": "'.$values{LaMetric_icon}.'",
							"text": "'.$message.'"
						}
					],
				"sound": {
					"category": "notifications",
					"id": "'.$values{LaMetric_sound}.'",
					"repeat": '.$values{LaMetric_sound_repeat}.'
				},
				"cycles": '.$values{LaMetric_cycles}.'
			  }
			}
		';
	}

	# send nottification to the device
	LaMetric_SendHTMLRequest($hash, "POST", "/api/v2/device/notifications", $json);

	# update readings
	readingsBeginUpdate($hash);
	readingsBulkUpdateIfChanged($hash, "lastMessage", $message);
	readingsBulkUpdateIfChanged($hash, "lastSound", $values{LaMetric_sound});
	readingsBulkUpdateIfChanged($hash, "lastIcon", $values{LaMetric_icon});
	readingsEndUpdate($hash, 1);

	return;
}

#** @method public LaMetric_SetAudioVolume($hash, $cmd, $a, $h)
# This method sets the audio volume of the LaMetric device.
# 
# @link http://lametric-documentation.readthedocs.io/en/latest/reference-docs/device-audio.html#update-audio-state
# @param hash - required hash (device hash)
# @param cmd  - required string (command of the FHEM set function)
# @param a    - required array (of all unnamed parameters)
# @param h    - required reference (of all named parameters)
# 
# @note volume (Integer): <0-100>
#*
#
sub LaMetric_SetAudioVolume($$$$) {
	my ($hash, $cmd, $a, $h) = @_;
	my $name = $hash->{NAME};
	my $volume = join ' ', @$a;
	my $json = '{"volume":'. $volume .'}';

	Log3 $name, 5, "LaMetric $name: called function LaMetric_SetAudioVolume($volume) $json";

	# test parameter and send json command
	if ($volume =~ /^[1-9][0-9]?$|^100$/){
		LaMetric_SendHTMLRequest($hash, "PUT", "/api/v2/device/audio", $json);
	} else {
		readingsSingleUpdate($hash, "state", "bad volume value", 1);
	}
	return;
}

#** @method public LaMetric_SetDisplayBrightnesse($hash, $cmd, $a, $h)
# This method sets the display brightness of the LaMetric device.
# 
# @link http://lametric-documentation.readthedocs.io/en/latest/reference-docs/device-display.html#update-display-state
# @param hash - required hash (device hash)
# @param cmd  - required string (command of the FHEM set function)
# @param a    - required array (of all unnamed parameters)
# @param h    - required reference (of all named parameters)
# 
# @note brightness (Integer): <0-100>
#*
#
sub LaMetric_SetDisplayBrightnesse($$$$) {
	my ($hash, $cmd, $a, $h) = @_;
	my $name = $hash->{NAME};
	my $brightness = join ' ', @$a;
	my $json = '{"brightness":'. $brightness .'}';

	Log3 $name, 5, "LaMetric $name: called function LaMetric_SetDisplayBrightnesse($brightness) $json";
	
	# test parameter and send json command
	if ($brightness =~ /^[1-9][0-9]?$|^100$/){
		LaMetric_SendHTMLRequest($hash, "PUT", "/api/v2/device/display", $json);
	} else {
		readingsSingleUpdate($hash, "state", "bad brightness value", 1);
	}
	return;
}

#** @method public LaMetric_SetDisplayBrightnesseMode($hash, $cmd, $a, $h)
# This method sets the display brightness mode of the LaMetric device.
# 
# @link http://lametric-documentation.readthedocs.io/en/latest/reference-docs/device-display.html#update-display-state
# @param hash - required hash (device hash)
# @param cmd  - required string (command of the FHEM set function)
# @param a    - required array (of all unnamed parameters)
# @param h    - required reference (of all named parameters)
# 
# @note brightness_mode (string): "[auto|manual]"
#*
#
sub LaMetric_SetDisplayBrightnesseMode($$$$) {
	my ($hash, $cmd, $a, $h) = @_;
	my $name = $hash->{NAME};
	my $brightness_mode = join ' ', @$a;
	my $json = '{"brightness_mode":"'. $brightness_mode .'"}';

	Log3 $name, 5, "LaMetric $name: called function LaMetric_SetDisplayBrightnesseMode($brightness_mode) $json";

	# test parameter and send json command
	if ($brightness_mode =~ /^(auto|manual)$/){
		LaMetric_SendHTMLRequest($hash, "PUT", "/api/v2/device/display", $json);
	} else {
		readingsSingleUpdate($hash, "state", "bad brightness_mode value", 1);
	}
	return;
}

#** @method public LaMetric_SetAppNextPrev($hash, $mode)
# This method sets the display brightness mode of the LaMetric device.
# 
# @link http://lametric-documentation.readthedocs.io/en/latest/reference-docs/device-display.html#update-display-state
# @param hash - required hash (device hash)
# @param cmd  - required string (command of the FHEM set function)
# @param a    - required array (of all unnamed parameters)
# @param h    - required reference (of all named parameters)
# 
# @note brightness_mode (string): "[auto|manual]"
#*
#
sub LaMetric_SetAppNextPrev($$) {
	my ($hash, $mode) = @_;
	my $name = $hash->{NAME};

	Log3 $name, 5, "LaMetric $name: called function LaMetric_SetAppNextPrev($mode)";

	# test parameter and send json command
	if ($mode =~ /^(next|prev)$/){
		LaMetric_SendHTMLRequest($hash, "PUT", "/api/v2/device/apps/".$mode, "");
	} else {
		readingsSingleUpdate($hash, "state", "bad app select value", 1);
	}
	return;
}

#** @method public LaMetric_SendHTMLRequest($hash, $method, $endpoint, $json)
# This method sends a html POST|PUT request to the LaMetric device.
# 
# @param hash     - required hash (device hash)
# @param method   - required string (html method eg. POST,PUT)
# @param endpoint - required string (api endpoint of the LaMetric device)
# @param json     - required reference (json command string)
#*
#
sub LaMetric_SendHTMLRequest ($$$$) {
	my ($hash, $method, $endpoint, $json) = @_;
	my $name   = $hash->{NAME};

	# sends a html request to the given endpoint and send json command
	HttpUtils_NonblockingGet({ 
		url         => "https://".$hash->{HOST}.":4343".$endpoint, 
		#auth        => "dev:".$hash->{APIKEY},
		user        => "dev",
		pwd         => $hash->{APIKEY},
		hash        => $hash,  
		data        => $json,
		method      => $method,
		httpversion => "1.1",
		timeout     => 3,
		loglevel    => AttrVal($name, "httpLoglevel", 4),
		header      => {
			'Agent'          => 'FHEM-LaMetric/1.0.0',
			'User-Agent'     => 'FHEM-LaMetric/1.0.0',
			'Accept-Charset' => 'UTF-8',
			'Accept-Charset' => 'application/json',
		},
		# upodate status and device info on response
		callback    => sub(){ 
			Log3 $name, 5, "LaMetric $name: ". $_[0]->{httpheader};
			LaMetric_Status($hash, $_[0]->{code});
			LaMetric_DeviceInfo($hash, $name);
		}
	});
}

#** @method public LaMetric_DeviceInfo($hash, $name)
# This method gets the state from the LaMetric device.
#
# @link http://lametric-documentation.readthedocs.io/en/latest/reference-docs/device-state.html#get-device-state
# @param hash     - required hash (device hash)
# @param name - required string (name of the device)
#*
#
sub LaMetric_DeviceInfo($$) {
	my ($hash, $name) = @_;
	Log3 $name, 5, "LaMetric $name: called function LaMetric_DeviceInfo()";

	# sends a html request to the device status endpoint
	HttpUtils_NonblockingGet({ 
		url         => "https://".$hash->{HOST}.":4343/api/v2/device", 
		#auth        => "dev:".$hash->{APIKEY},
		user        => "dev",
		pwd         => $hash->{APIKEY},
		hash        => $hash,
		httpversion => "1.1",
		timeout     => 3,
		loglevel    => AttrVal($name, "httpLoglevel", 4),
		# upodate device readings on response
		callback    => sub(){ 
			my $status = $_[0]->{code};

			if (defined $status && length $status > 0) {
				$status = "";
			}
			eval {
				my $response = JSON->new->utf8->decode($_[2]);
				#Log 5,"DATA:" . Dumper(\$response);
				readingsBeginUpdate($hash);
				readingsBulkUpdateIfChanged($hash, "device_model",            $response->{model});
				readingsBulkUpdateIfChanged($hash, "device_firmware",         $response->{os_version});
				readingsBulkUpdateIfChanged($hash, "device_mode",             $response->{mode});
				readingsBulkUpdateIfChanged($hash, "device_name",             $response->{name});
				#readingsBulkUpdateIfChanged($hash, "device_serial",           $response->{serial});
				readingsBulkUpdateIfChanged($hash, "audio_volume",            $response->{audio}->{volume});
				readingsBulkUpdateIfChanged($hash, "bluetooth_mac",           $response->{bluetooth}->{address});
				readingsBulkUpdateIfChanged($hash, "wifi_ssid",               $response->{wifi}->{essid});
				readingsBulkUpdateIfChanged($hash, "wifi_strength",           $response->{wifi}->{strength});
				readingsBulkUpdateIfChanged($hash, "wifi_encryption",         $response->{wifi}->{encryption});
				readingsBulkUpdateIfChanged($hash, "wifi_mac",                $response->{wifi}->{address});
				readingsBulkUpdateIfChanged($hash, "wifi_mode",               $response->{wifi}->{mode});
				readingsBulkUpdateIfChanged($hash, "display_height",          $response->{display}->{height});
				readingsBulkUpdateIfChanged($hash, "display_width",           $response->{display}->{width});
				readingsBulkUpdateIfChanged($hash, "display_brightness",      $response->{display}->{brightness});
				readingsBulkUpdateIfChanged($hash, "display_brightness_mode", $response->{display}->{brightness_mode});
				readingsBulkUpdateIfChanged($hash, "display_type",            $response->{display}->{type});
				readingsEndUpdate($hash, 1);
				1;
			} or do {
				Log3 $name, 5, "LaMetric $name: failed to decode JSON response. ";
				LaMetric_Status($hash, $status);
			} 
		}
	});

	return;
}

#** @method public LaMetric_Status($hash, $status)
# This method sets lastResult status to the LaMetric FHEM device.
#
# @param hash     - required hash (device hash)
# @param status - required string (name of the device)
#*
#
sub LaMetric_Status($$) {
	my ($hash, $status) = @_;

	# reading update of lastResult based on received status code
	readingsBeginUpdate($hash);
	switch ($status) { 
		case 200 { readingsBulkUpdateIfChanged( $hash, "lastResult", "200 OK" ); }
		case 201 { readingsBulkUpdateIfChanged( $hash, "lastResult", "201 Created" ); }
		case 400 { readingsBulkUpdateIfChanged( $hash, "lastResult", "400 Bad Request" ); }
		case 401 { readingsBulkUpdateIfChanged( $hash, "lastResult", "401 Unauthorized" ); }
		case 405 { readingsBulkUpdateIfChanged( $hash, "lastResult", "405 Method Not Allowed" ); }
		else     { 
			if (defined $status && length $status > 0) {
					readingsBulkUpdateIfChanged($hash, "lastResult", "result:⋅". $status);
			}
		}
	}
	readingsEndUpdate($hash, 1);
}


# Eval-Rückgabewert für erfolgreiches
# Laden des Moduls
1;


# Beginn der Commandref

=pod
=item device
=item summary Kurzbeschreibung in Englisch was MYMODULE steuert/unterstützt
=item summary_DE Kurzbeschreibung in Deutsch was MYMODULE steuert/unterstützt

=begin html
<a name="LaMetric"></a>
<h3>LaMetric</h3>
<ul>
  <a href="http://lametric.com">LaMetric</a> is a smart and hackable ticker device. The FHEM module use the local device nottification api to push messages to the device. 
  The display notification queue stores the messages and show them in order of incomming time and priority. Notifications with higher priority will be first in the list.<br><br>

  You have to <a href="https://developer.lametric.com">create an developer account</a> to get your device api key.<br>



<!-- Pushover is a service to receive instant push notifications on your
   phone or tablet from a variety of sources.<br>
   You need an account to use this module.<br>
   For further information about the service see <a href="https://pushover.net">pushover.net</a>.<br>
   <br>
   Installation of Perl module IO::Socket::SSL is mandatory to use this module (i.e. via 'cpan -i IO::Socket::SSL').<br>
   It is recommended to install Perl-JSON to make use of advanced functions like supplementary URLs.<br>
   <br>
   Discuss the module <a href="http://forum.fhem.de/index.php/topic,16215.0.html">here</a>.<br>
   <br> 
   <br> -->
   <a name="LaMetricDefine"></a>
   <p><b>define</b></p>
   <ul>
      <code>define &lt;name&gt; LaMetric &lt;IP&gt; &lt;api key&gt; </code><br><br>
      Example:
      <ul>
         <code>define LaMetric1 LaMetric 192.168.0.25 1c7e334c7ed461d34d86a9f0b1e4f90d30ceaf379b03644dce044bb01c111781</code>
      </ul>
   </ul>
   <br>

   <a name="LaMetricSet"></a>
   <p><b>set &lt;required&gt;</b></p>
   <ul>
      <li>
         <b><i>msg &lt;text&gt; [&lt;option1&gt;=&lt;value&gt; &lt;option2&gt;=&lt;value&gt; ...]</i></b><br><br>
         The following options may be used to adjust message content and delivery behavior:<br>
         <br>
         <code><b>sound</b>&nbsp;&nbsp;&nbsp;&nbsp;</code> - type: text - A LaMetric sound ID. See attr LaMetric_sound for available IDs<br>
         <code><b>icon</b>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code> - type: text - A LaMetric icon ID. You can unse a existing icon from <a href="https://developer.lametric.com/icons">LaMetric icon gallery</a> or create your own there.<br>
         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The icon number have to prefixed with a (animate) or i (static). Example: #1134 is i1134 or a1134<br>
         <code><b>cycle</b>&nbsp;&nbsp;&nbsp;&nbsp;</code> - type: integer - Number of times message should be displayed.<br>
         <code><b>priority</b>&nbsp;</code> - type: string - &lt;info|warning|critical&gt; see Attribute: LaMetric_priority for details.<br>
         <code><b>info_type</b></code> - type: string - &lt;none|info|alert&gt; see Attribute: LaMetric_info_type for details.<br>
         <br>
         Examples:
         <ul>
           <code>set LaMetric1 msg The lazy fox jumps over the quick brown dog</code><br>
           <code>set LaMetric1 msg "The lazy fox jumps over the quick brown dog with quptes"</code><br>
           <code>set LaMetric1 msg "The lazy fox jumps over the quick brown dog" sound=cat icon=i1134 cycle=2</code><br>
         </ul>
         <br>
      </li>


      <li>
         <b><i>privatemsg &lt;text&gt; icon=&lt;value&gt;</i></b><br><br>
         Send push nottification to private App. You have to create your own private App at the <a href="https://developer.lametric.com">LaMetric developer website</a>
         and set the Attributes LaMetric_AppPushEndpoint, LaMetric_AppPushToken to the matching values of your private App.<br><br>
         The following options may be used to adjust message content and delivery behavior:<br>
         <br>
         <code><b>icon</b>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code> - type: text - A LaMetric icon ID. You can unse a existing icon from <a href="https://developer.lametric.com/icons">LaMetric icon gallery</a> or create your own there.<br>
         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The icon number have to prefixed with a (animate) or i (static). Example: #1134 is i1134 or a1134<br>
         <br>
         Examples:
         <ul>
           <code>set LaMetric1 msg The lazy fox jumps over the quick brown dog icon=a7703</code><br>
           <code>set LaMetric1 msg "The lazy fox jumps without icon over the quick brown dog" icon=none</code><br>
         </ul>
         <br>
      </li>




      <li>
         <b><i>nextapp</i></b><br>
         Allows to switch to the next app on LaMetric. App order is controlled by the user via LaMetric Time app.<br>
         <br>
         Example:
         <ul>
           <code>set LaMetric1 audio_volume 50</code><br>
         </ul>
         <br>
      </li>
      <li>
         <b><i>prevapp</i></b><br>
         Allows to switch to the previous app on LaMetric. App order is controlled by the user via LaMetric Time app.<br>
         <br>
         Example:
         <ul>
           <code>set LaMetric1 audio_volume 50</code><br>
         </ul>
         <br>
      </li>

      <li>
         <b><i>audio_volume &lt;0-100&gt;</i></b><br>
         Sets the audio volume of the display. Volume must be an integer between 0 and 100.<br>
         <br>
         Example:
         <ul>
           <code>set LaMetric1 audio_volume 50</code><br>
         </ul>
         <br>
      </li>
      <li>
         <b><i>display_brightness &lt;0-100&gt;</i></b><br>
         Sets the display brightness of display. Brightness must be an integer between 0 and 100.<br>
         <br>
         Example:
         <ul>
           <code>set LaMetric1 display_brightness 75</code><br>
         </ul>
         <br>
      </li>
      <li>
         <b><i>display_brightness_mode &lt;auto|manual&gt;</i></b><br>
         Sets the display brightness mode of the display. If brightness_mode is set to “auto”, brightness value still can be changed but this will not affect the actual brightness of the display. Brightness mode have to be auto or manual.<br>
         <br>
         Examples:
         <ul>
           <code>set LaMetric1 display_brightness_mode auto</code><br>
           <code>set LaMetric1 display_brightness_mode manual</code><br>
         </ul>
         <br>
      </li>
   </ul>

   <a name="LaMetricGet"></a>
   <p><b>get &lt;required&gt;</b></p>
   <ul>
      <li>
         <b><i>status</i></b><br>
         Gets the LaMetric display status and update readings if changed.<br>
         <br>
         Example:
         <ul>
           <code>get LaMetric1 status</code><br>
         </ul>
         <br>
      </li>
   </ul>

   <a name="LaMetricAttribute"></a>
   <p><b>Attribute</b></p>
   <ul>
<!--
      <li>
         <b><i>LaMetric_alarm &lt;alarmId&gt;</i></b><br>
         alarm1,alarm2,alarm3,alarm4,alarm5,alarm6,alarm7,alarm8,alarm9,alarm10,alarm11,alarm12,alarm13<br>
         <br>
      </li>
-->
      <li>
         <b><i>LaMetric_cycles &lt;integer&gt;</i></b><br>
         The number of times message should be displayed. If cycles is set to 0, notification will stay on the screen until user dismisses it. By default it is set to 1.<br>
         <br>
      </li>
      <li>
         <b><i>LaMetric_icon &lt;iconId&gt;</i></b><br>
          A LaMetric icon ID. By default the value is set to i620.<br><br>
         You can unse a existing icon from <a href="https://developer.lametric.com/icons">LaMetric icon gallery</a> or create your own there.<br>
         <br>
      </li>
      <li>
         <b><i>LaMetric_info_type &lt;none|info|alert&gt;</i></b><br>
         Represents the nature of notification. By default the value is set to none.<br><br>
         <table>
            <tr><td valign="top"><code><b>none </b></code></td><td>No notification icon will be shown.</td></tr>
            <tr><td valign="top"><code><b>info </b></code></td><td>“i” icon will be displayed prior to the notification. Means that notification contains information, no need to take actions on it.</td></tr>
            <tr><td valign="top"><code><b>alert</b></code></td><td>”!!!” icon will be displayed prior to the notification. Use it when you want the user to pay attention to that notification as it indicates that something bad happened and user must take immediate action.</td></tr>
         </table>
         <br>
      </li>
      <li>
         <b><i>LaMetric_lifetime &lt;seconds&gt;</i></b><br>
         The time notification lives in queue to be displayed in seconds. Default lifetime is 2 minutes. If notification stayed in queue for longer than lifetime seconds – it will not be displayed.<br>
         <br>
      </li>
      <li>
         <b><i>LaMetric_priority &lt;info|warning|critical&gt;</i></b><br>
         Priority of the message. By default the value is set to warning<br><br>
         <table>
            <tr><td valign="top"><code><b>info    </b></code></td><td>This priority means that notification will be displayed on the same “level” as all other notifications on the device that come from apps (for example facebook app). This notification will not be shown when screensaver is active. By default message is sent with “info” priority. This level of notification should be used for notifications like news, weather, temperature, etc.</td></tr>
            <tr><td valign="top"><code><b>warning </b></code></td><td>Notifications with this priority will interrupt ones sent with lower priority (“info”). Should be used to notify the user about something important but not critical. For example, events like “someone is coming home” should use this priority when sending notifications from smart home.</td></tr>
            <tr><td valign="top"><code><b>critical</b></code></td><td>The most important notifications. Interrupts notification with priority info or warning and is displayed even if screensaver is active. Use with care as these notifications can pop in the middle of the night. Must be used only for really important notifications like notifications from smoke detectors, water leak sensors, etc. Use it for events that require human interaction immediately.</td></tr>
         </table>
         <br>
      </li>
      <li>
         <b><i>LaMetric_sound &lt;soundId&gt;</i></b><br>
         Set default nottification sound. Sound must be a LaMetric soundID. By default the value is set to notification.<br><br>
         Full list of sound Ids:<br>
         <table>
            <tr><td width="150"><code>none         </code></td><td width="150"><code>negative1     </code></td></td><td width="150"><code>positive3  </code></td></tr>
            <tr><td width="150"><code>bicycle      </code></td><td width="150"><code>negative2     </code></td></td><td width="150"><code>positive4  </code></td></tr>
            <tr><td width="150"><code>car          </code></td><td width="150"><code>negative3     </code></td></td><td width="150"><code>positive5  </code></td></tr>
            <tr><td width="150"><code>cash         </code></td><td width="150"><code>negative4     </code></td></td><td width="150"><code>positive6  </code></td></tr>
            <tr><td width="150"><code>cat          </code></td><td width="150"><code>negative5     </code></td></td><td width="150"><code>statistic  </code></td></tr>
            <tr><td width="150"><code>dog          </code></td><td width="150"><code>notification  </code></td></td><td width="150"><code>thunder    </code></td></tr>
            <tr><td width="150"><code>dog2         </code></td><td width="150"><code>notification2 </code></td></td><td width="150"><code>water1     </code></td></tr>
            <tr><td width="150"><code>energy       </code></td><td width="150"><code>notification3 </code></td></td><td width="150"><code>water2     </code></td></tr>
            <tr><td width="150"><code>knock-knock  </code></td><td width="150"><code>notification4 </code></td></td><td width="150"><code>win        </code></td></tr>
            <tr><td width="150"><code>letter_email </code></td><td width="150"><code>open_door     </code></td></td><td width="150"><code>win2       </code></td></tr>
            <tr><td width="150"><code>lose1        </code></td><td width="150"><code>positive1     </code></td></td><td width="150"><code>wind       </code></td></tr>
            <tr><td width="150"><code>lose2        </code></td><td width="150"><code>positive2     </code></td></td><td width="150"><code>wind_short </code></td></tr>
         </table>
         <br>
      </li>
      <li>
         <b><i>LaMetric_sound_repeat &lt;integer&gt;</i></b><br>
         Set default numer of times sound must be played. If set to 0 sound will be played until notification is dismissed. By default the value is set to 1.<br><br>
      </li>
      <li>
         <b><i>LaMetric_AppPushEndpoint &lt;Local Push URL&gt;</i></b><br>
         Used to push to private LaMetric App. Create your own app at the <a href="https://developer.lametric.com">LaMetric developer website</a>.<br>
         Must use in conjunction with LaMetric_AppPushToken.<br>
         <br>
         Example: attr LaMetric1 LaMetric_AppPushEndpoint com.lametric.1234567890abcefs1234567890abcdef<br><br>
      </li>
      <li>
         <b><i>LaMetric_AppPushToken &lt;Access token&gt;</i></b><br>
         Used to push to private LaMetric App. Create your own app at the <a href="https://developer.lametric.com">LaMetric developer website</a>.<br>
         Must use in conjunction with LaMetric_AppPushEndpoint.<br>
         <br>
         Example: attr LaMetric1 LaMetric_AppPushToken NmM2Mzc1NMEyNTgFiNWFmYYTM4ZGJlZjYWZjNTxZGI1ZzJ1NjkZDA4YmDhkNDY2NDFjZjQ2VjY3YTA0OTdiNzA==<br><br>
      </li>
   </ul>

   <a name="LaMetricReedings"></a>
   <p><b>Readings</b></p>
   <ul>
   <table>
      <tr><td><b><i>audio_volume</i></b></td><td>- Audio volume level of the display</td></tr>
      <tr><td><b><i>bluetooth_mac</i></b></td><td>- Bluetooth mac address of the display</td></tr>
      <tr><td><b><i>device_firmware</i></b></td><td>- Device firmware version</td></tr>
      <tr><td><b><i>device_mode</i></b></td><td>- Device mode</td></tr>
      <tr><td><b><i>device_model</i></b></td><td>- Device model number</td></tr>
      <tr><td><b><i>device_name</i></b></td><td>- Device name</td></tr>
      <tr><td><b><i>display_brightness</i></b></td><td>- Display brightness level of the display</td></tr>
      <tr><td><b><i>display_brightness_mode</i></b></td><td>- Display brightness mode of the display</td></tr>
      <tr><td><b><i>display_height</i></b></td><td>- Device display hight</td></tr>
      <tr><td><b><i>display_type</i></b></td><td>- Device display type</td></tr>
      <tr><td><b><i>display_width</i></b></td><td>- Device display width</td></tr>
      <tr><td><b><i>lastIcon</i></b></td><td>- Icon Id of the last send message</td></tr>
      <tr><td><b><i>lastMessage</i></b></td><td>- Last send message text</td></tr>
      <tr><td><b><i>lastResult</i></b></td><td>- Last response code of a display request</td></tr>
      <tr><td><b><i>lastSound</i></b></td><td>- Sound Id of the last send message</td></tr>
      <tr><td><b><i>state</i></b></td><td>- Device state</td></tr>
      <tr><td><b><i>wifi_encryption</i></b></td><td>- WiFi encryption type</td></tr>
      <tr><td><b><i>wifi_mac</i></b></td><td>- WiFi mac address</td></tr>
      <tr><td><b><i>wifi_mode</i></b></td><td>- WiFi mode of the display</td></tr>
      <tr><td><b><i>wifi_ssid</i></b></td><td>- WiFi ssid of the display</td></tr>
      <tr><td><b><i>wifi_strength</i></b></td><td>- Current WiFi strenght of the display</td></tr>
   </table>
   </ul>
=end html

=begin html_DE
 Deustche Commandref in HTML
=end html

# Ende der Commandref
=cut