Contents

Introduction
FHEM command types
Device specification
Attributes

FHEM commands
apptime   attr   backup   cancel   cmdalias   configdb   copy   count   createlog   CULflash   define   defmod   delete   deleteattr   deletereading   displayattr   fhemdebug   fheminfo   get   help   HMtemplate   IF   include   inform   JsonList2   KNX_scan   list   modify   MSG   notice   quit   reload   rename   rereadcfg   restore   save   search   set   setdefaultattr   setreading   setstate   setuuid   show   shutdown   sleep   template   trigger   update   uptime   usb   version   XmlList  

Device modules
global
AirUnit   alexa   ALL4027   allergy   AMADCommBridge   AMADDevice   AndroidDB   AndroidDBHost   AptToDate   Aqicn   ArduCounter   Arlo   Aurora   AutomowerConnect   AutoShuttersControl   BDKM   BEOK   BlinkCamera   BOSEST   BOTVAC   BRAVIA   Broadlink   BS   Calendar   CALVIEW   CanOverEthernet   CDCOpenData   CM11   CO20   COE_Node   ComfoAir   CUL   CUL_EM   CUL_FHTTK   CUL_HM   CUL_HOERMANN   CUL_IR   CUL_MAX   CUL_REDIRECT   CUL_RFR   CUL_TCM97001   CUL_TX   CUL_WS   dash_dhcp   DENON_AVR   DENON_AVR_ZONE   DFPlayerMini   DLNARenderer   DoorBird   Dooya   DUOFERN   DUOFERNSTICK   DWD_OpenData   EC3000   echodevice   ECMD   ECMDDevice   EGPM   EGPM2LAN   EleroDrive   EleroStick   EleroSwitch   ElsnerWS   EM   EMEM   EMGZ   EMT7110   EMWZ   ENECSYSGW   ENECSYSINV   ENIGMA2   EnOcean   EQ3BT   ESA2000   ESCVP21net   EseraAnalogInOut   EseraCount   EseraDigitalInOut   EseraDimmer   EseraIButton   EseraMulti   EseraOneWire   EseraShutter   EseraTemp   ESPEasy   ESPEInk   fakeRoku   FBAHA   FBAHAHTTP   FBDECT   FHT   FHT8V   FHZ   FLAMINGO   FRAMEBUFFER   FReplacer   FRITZBOX   FRM   FRM_AD   FRM_I2C   FRM_IN   FRM_OUT   FRM_PWM   FRM_RGB   FRM_ROTENC   FRM_SERVO   FRM_STEPPER   FS10   FS20   FTUISRV   FULLY   GAEBUS   GardenaSmartBridge   GardenaSmartDevice   gassistant   GFPROBT   GHoma   GOOGLECAST   harmony   HEATRONIC   HEOSGroup   HEOSMaster   HEOSPlayer   Hideki   HMCCU   HMCCUCHN   HMCCUDEV   HMCCURPCPROC   HMLAN   HMS   HMUARTLGW   holiday   HOMBOT   HP1000   HProtocolGateway   HProtocolTank   HTTPAPI   HTTPMOD   HTTPSRV   HUEBridge   HUEDevice   HusqvarnaAutomower   HVAC_DaikinAC   HXB   HXBDevice   HYDRAWISE   Hyperion   I2C_ADS1x1x   I2C_BH1750   I2C_BME280   I2C_BMP180   I2C_DS1307   I2C_EEPROM   I2C_EMC1001   I2C_HDC1008   I2C_K30   I2C_LCD   I2C_LM75A   I2C_MCP23008   I2C_MCP23017   I2C_MCP342x   I2C_MMA845X   I2C_PCA9532   I2C_PCA9685   I2C_PCF8574   I2C_SHT21   I2C_SHT3x   I2C_TSL2561   Iluminize   IOhomecontrol   IOhomecontrolDevice   IPCAM   IPWE   IT   Itach_IR   Itach_IRDevice   Jabber   JawboneUp   JeeLink   JSONMETER   JsonMod   KeyValueProtocol   Klafs   km200   KM273   KNX   KNXIO   KNXTUL   KODI   KOPP_FC   KOSTALPIKO   KS300   LaCrosse   LaCrosseGateway   LaMetric2   Level   LGTV_IP12   LGTV_WebOS   LIGHTIFY   LIRC   livetracking   LuftdatenInfo   LUXTRONIK2   M232   M232Counter   M232Voltage   mailcheck   MAX   MAX_Temperature   MAXLAN   MEDIAPORTAL   MieleAtHome   MilightBridge   MilightDevice   MOBILEALERTS   MOBILEALERTSGW   Modbus   ModbusAttr   ModbusElsnerWS   ModbusSET   ModbusTrovis5576   MPD   MQTT   MQTT2_CLIENT   MQTT2_DEVICE   MQTT2_SERVER   MQTT_DEVICE   MQTT_GENERIC_BRIDGE   MSGFile   MSGMail   MYSENSORS   MYSENSORS_DEVICE   N4HBUS   N4HMODULE   Nello   netatmo   NetIO230B   Netzer   NetzerI2C   Netzfrequenz   Neuron   NeuronPin   NEUTRINO   Nextion   Nmap   NotifyAndroidTV   npmjs   NUKIBridge   NUKIDevice   NUT   OBIS   OctoPrint   OilFox   ONKYO_AVR   ONKYO_AVR_ZONE   OPENWEATHER   OREGON   OW2S0SMSGUARD   OWAD   OWCOUNT   OWDevice   OWID   OWLCD   OWMULTI   OWServer   OWSWITCH   OWTHERM   OWVAR   OWX   OWX_ASYNC   OWX_CCC   OWX_FRM   OWX_SER   OWX_TCP   panStamp   PCA301   PHC   PHILIPS_AUDIO   PHTV   PIFACE   pilight   pilight_contact   pilight_ctrl   pilight_dimmer   pilight_raw   pilight_smoke   pilight_switch   pilight_temp   ping   PIONEERAVR   PIONEERAVRZONE   PiXtendV2   plex   Plugwise   POKEYS   PrecipitationSensor   PROPLANTA   Pushbullet   PushNotifier   Pushover   Pushsafer   PW_Circle   PW_Scan   PW_Sense   PW_Switch   PWM   PWMR   PylonLowVoltage   QRCode   Revolt   RFXCOM   RFXMETER   RFXX10REC   RHASSPY   Robonect   RPI_1Wire   RPI_GPIO   RPII2C   rssFeed   S7   S7_ARead   S7_AWrite   S7_Client   S7_DRead   S7_DWrite   S7_S5Client   S7_S7Client   SamsungAV   Schellenberg   SchellenbergHandle   SCIVT   SD_BELL   SD_GT   SD_RSL   SD_UT   SD_WS   SD_WS07   SD_WS09   SD_WS_Maverick   serviced   ShareMaster   Shares   SHC   SHCdev   Shelly   ShellyMonitor   Signalbot   SIGNALduino   SIGNALduino_un   siri   SIS_PMS   SISPM   SMAEM   SMAEVCharger   SMAInverter   SmartMeterP1   SMARTMON   SmartPi   SMASTP   SML   Snapcast   SolarEdgeAPI   SolarForecast   SOMFY   SONOS   SONOSPLAYER   speedtest   Spotify   SSCal   SSCam   SSCamSTRM   SSChatBot   SSFile   STACKABLE   STACKABLE_CC   STV   SVDRP   SWAP   SWAP_0000002200000003   SWAP_0000002200000008   SYSMON   SYSSTAT   systemd_watchdog   TA_CMI_JSON   tahoma   TBot_List   TCM   TechemHKV   TechemWZ   TEK603   TelegramBot   TellStick   TeslaPowerwall2AC   THINKINGCLEANER   THZ   Timer   todoist   TPLinkHS110   tradfri   TRAFFIC   TRX   TRX_ELSE   TRX_LIGHT   TRX_SECURITY   TRX_WEATHER   TUL   UbiquitiMP   UbiquitiOut   UBUS_CALL   UBUS_CLIENT   Unifi   UnifiClient   UnifiProtect   UnifiSwitch   UnifiVideo   UNIRoll   USBWX   USF1000   UWZ   Vallox   VBUSDEV   VBUSIF   VCLIENT   VCONTROL   Verkehrsinfo   VIERA   vitoconnect   VolumeLink   Weather   WifiLight   WINCONNECT   withings   WMBUS   WS2000   WS300   WS3600   WS980   Wunderground   WWO   X10   XiaomiBTLESens   XiaomiDevice   xs1Bridge   xs1Dev   YAMAHA_AVR   YAMAHA_BD   YAMAHA_MC   YAMAHA_NP   yowsup   ZM_Monitor   ZoneMinder   ZWave   ZWCUL   ZWDongle  

Helper modules
Alarm   alarmclock   allowed   archetype   Astro   at   autocreate   average   Babble   cloneDummy   configDB   CustomReadings   Dashboard   DbLog   DbRep   dewpoint   DOIF   DOIFtools   DSBMobile   dummy   ElectricityCalculator   eventTypes   expandJSON   FB_CALLLIST   FB_CALLMONITOR   feels_like   FHEM2FHEM   FHEMAPP   FhemTestUtils   FHEMWEB   FileLog   FLOORPLAN   freezemon   GasCalculator   GEOFANCY   GoogleAuth   GSI   GUEST   HCS   Heating_Control   HMinfo   HOMEMODE   HourCounter   InfluxDBLogger   InfoPanel   inotify   Installer   KM271   LightScene   Log2Syslog   logProxy   MaxScanner   MediaList   monitoring   msgConfig   msgDialog   notify   PachLog   PET   PID20   PostMe   powerMap   PRESENCE   PRESENCE2   rain   RandomTimer   readingsChange   readingsGroup   readingsHistory   readingsProxy   readingsWatcher   remotecontrol   RESIDENTS   ROLLO   ROOMMATE   RSS   sequence   SingleFileLog   SIP   SoftliqCloud   statistics   structure   SUNRISE_EL   SVG   Talk2Fhem   telnet   Text2Speech   THRESHOLD   TrashCal   Twilight   Utils   watchdog   Watches   WaterCalculator   weblink   WeekdayTimer   weekprofile   WOL   WUup   YAAHM  

Perl specials
Regexp
gnuplot file syntax

Introduction

FHEM is mainly used for home automation, but it is suitable for other tasks too, where notification, timers and logging plays an important role.

It supports different hardware devices to interface with certain protocols (e.g. FHZ1000PC to interface FS20 and HMS, CM11 to access X10), and logical devices like FS20 or FHT to digest the messages for a certain device type using this protocol.

FHEM is modular. The different devices are represented through modules which implement certain functions (e.g. define, get, set). Even seemingly integral parts of FHEM like triggers (notify) and timers (at) are implemented this way, giving the possibility to replace/extend this functionality.

FHEM is controlled through readable / ascii commands, which are specified in files (e.g. the configuration file), or issued over a TCP/IP connection, either directly in a telnet session, with a fhem.pl in client mode or from one of the web frontends.

When starting the server you have to specify a configuration file:

perl fhem.pl fhem.cfg

A reasonable minimal configuration file looks like:

    attr global logfile log/fhem.log
    attr global modpath .
    attr global statefile log/fhem.save
    define telnetPort telnet 7072 global
    define WEB FHEMWEB 8083 global

Note: the last two lines are optional and assume you wish to use the builtin telnet and WEB interface.

The web interface can be reached at
http://<fhemhost>:8083

TCP/IP communication with FHEM can either happen in a "session" (via telnet) or single client command (via fhem.pl). Example:
telnet <fhemhost> 7072
<NL> (This newline switches into "prompt" mode)
<command>...
quit

or
fhem.pl <fhemhost>:7072 "<fhem-command>" "..."

If a OS-user called fhem exists, and FHEM is started as root, FHEM will automatically change to to this user via setuid.

If FHEM is started with the -d option (perl fhem.pl -d fhem.cfg), then the verbose level is set to 5 and the logfile is redirected to the STDOUT.

The environment variable FHEM_GLOBALATTR is evaluated: it consists of space separated name=value pairs, where name is a global attribute. Values from this source override values set in the configuration file.

FHEM command types

There are three types of commands: "FHEM" commands (described in this document), shell commands (they must be enclosed in double quotes ") and perl expressions (enclosed in curly brackets {}). shell commands or perl expressions are needed for complex at or notify arguments, but can also issued as a "normal" command.

E.g. the following three commands all do the same when issued from a telnet prompt:

set lamp off
"fhem.pl 7072 "set lamp off""
{fhem("set lamp off")}


Shell commands will be executed in the background, perl expressions and FHEM commands will be executed in the main "thread". In order to make perl expressions easier to write, some special functions and variables are available. See the section Perl special for a description. To trigger FHEM commands from a shell script (this is the "other way round"), use the client form of fhem.pl (described above).

Multiple FHEM commands are separated by semicolon (;). In order to use semicolon in perl code or shell programs, they have to be escaped by the double semicolon (;;). See the Notes section of the notify chapter on command parameters and escape rules.
E.g. the following first command switches Lamp1 off at 07:00 and Lamp2 immediately (at the point of definition), the second one switches both lamps off at 07:00.

define lampoff at 07:00 set Lamp1 off; set Lamp2 off
define lampoff at 07:00 set Lamp1 off;; set Lamp2 off

For every further indirection you need to double the semicolons:, e.g. to switch on every day 2 devices at 7:00 for 10 minutes you have to write:

define onAt at 07:00 set Lamp1 on;;set Lamp2 on;; define offAt at +00:10 set Lamp1 off;;;;set Lamp2 off
Don't dispair, the previous example can also be written as
define onAt at 07:00 set Lamp1,Lamp2 on-for-timer 600

Commands can be either typed in plain, or read from a file (e.g. the configuration file at startup). The commands are either executed directly, or later if they are arguments to the at and notify FHEM commands.

A line ending with \ will be concatenated with the next one, so long lines (e.g. multiple perl commands) can be split in multiple lines. Some web fronteds (e.g. webpgm2) make editing of multiline commands transparent for you (i.e. there is no need for \) .
Note: mixing command types (FHEM/shell/perl) on one line is not supported, even if it might work in some cases.

Device specification (devspec)

The commands attr, deleteattr, displayattr, delete, get, list, set, setreading, setstate, trigger can take a more complex device specification as argument, which will be expanded to a list of devices. A device specification (short devspec) can be:
• a single device name. This is the most common case.
• a list of devices, separated by comma (,)
• a regular expression
• a NAME=VALUE pair, where NAME can be an internal value like TYPE, a Reading-Name or an attribute. VALUE is a regexp. To negate the comparison, use NAME!=VALUE. To restrict the search, use i: as prefix for internal values, r: for readings and a: for attributes. See the example below. Case sensitivity is being ignored using ~ or !~.
• if the spec is followed by the expression :FILTER=NAME=VALUE, then the values found in the first round are filtered by the second expression.
Examples:
set lamp1 on
set lamp1,lamp2,lamp3 on
set lamp.* on
set room=kitchen off
set room=kitchen:FILTER=STATE=on off
set room=kitchen:FILTER=STATE!=off off
list disabled=
list room~office
list TYPE=FS20 STATE
list i:TYPE=FS20 STATE

Notes:
• the spec may not contain space characters.
• if there is a device which exactly corresponds to the spec, then no special processing is done.
• first the spec is separated by comma, then the regular expression and filter operations are executed.
• the returned list can contain the same device more than once, so "set lamp3,lamp3 on" switches lamp3 twice.
• for more complex structuring demands see the structure device.

Attributes

All devices have attributes. These can be set by means of the attr command, displayed with the displayattr command, and deleted by the deleteattr command.

There are global attributes that are used by all devices and local attributes that apply to individual device classes only.

Some devices (like FHEMWEB) automatically define new global attributes on the first definition of a device of such type.

You can use the command

attr global userattr <attributelist>

for the global device to declare new global attributes and

attr <devicespec> userattr <attributelist>

for individual devices according to devspec to declare new local attributes. <attributelist> is a space-separated list which contains the names of the additional attributes. See the documentation of the attr command for examples.

Be careful not to overwrite additional global attributes previously defined by yourself or a device. Use the attr global userattr <attributelist> as early in your configuration as possible.

Device specific attributes

Device specific attributes are documented in the corresponding device section.

Global attributes used by all devices

• alias
  Used by FHEMWEB to display a device with another name e.g. when using special characters/spaces not accepted by device definition.


• comment
  Add an arbitrary comment.


• eventMap
  Replace event names and set arguments. The value of this attribute consists of a list of space separated values, each value is a colon separated pair. The first part specifies the "old" value, the second the new/desired value. If the first character is slash(/) or comma(,) then split not by space but by this character, enabling to embed spaces. You can specify a widgetOverride after an additional colon (e.g. on-for-timer:OnFor:texField), the default widget is :noArg to avoid extra input fields in cmdList. Examples:
  attr store eventMap on:open off:closed
attr store eventMap /on-for-timer 10:open/off:closed/
set store open
  The explicit variant of this attribute has the following syntax:
  attr store eventMap { dev=>{'on'=>'open'}, usr=>{'open'=>'on'} }
attr store eventMap { dev=>{'^on(-for-timer)?(.*)'=>'open$2'}, usr=>{'^open(.*)'=>'on$1'}, fw=>{'^open(.*)'=>'open'} }
  This variant must be used, if the mapping is not symmetrical, the first part (dev) representing the device to user mapping, i.e. if the device reports on 100 or on-for-timer 100, the user will see open 100. The second part (usr) is the other direction, if the user specified open 10, the device will receive on 10. On both occasions the key will be first compared directly with the text, and if it is not equal, then it will be tried to match it as a regexp. When using regexps in the usr part with wildcards, the fw part must be filled with the exact same keys to enable a correct display in the FHEMWEB set dropdown list in the detail view.


• genericDisplayType
  used by some frontends (but not FHEMWEB) to offer a default image or appropriate commands for this device. Currently the following values are supported: switch,outlet,light,blind,speaker,thermostat


• group
  Group devices. Recognized by web-pgm2 (module FHEMWEB), it makes devices in the same group appear in the same box). This is used to further group devices together. A device can appear in more than one group, in this case the groups have to be specified comma-separated.
  If this attribute is not set then the device type is used as the grouping attribute.


• overrideNotifydev
  if set (the argument is a devspec), the optimization for notifications is using this value instead of the module-set NOTIFYDEV internal. Use it only, if you know it better than the module maintainer. In order to be available, the global or the device userattr must be set first, to include it.


• room
  Filter/group devices in frontends. A device can appear in more than one room, in this case the rooms have to be specified comma-separated.
  Devices in the room hidden will not appear in the web output, or set the FHEMWEB attribute hiddenroom to selectively disable rooms for certain FHEMWEB instances. The -> string is considered as a structure separator for rooms, e.g. "1st. floor->Master bedroom".


• suppressReading
  Used to eliminate unwanted readings. The value is a regular expression, with ^ and $ added. Only necessary in exceptional cases.


• showtime
  Used in the webfrontend pgm2 to show the time of last activity instead of the state in the summary view. Useful e.g. for FS20 PIRI devices.


• verbose
  Set the verbosity level. Possible values:
  • 0 - server start/stop
  • 1 - error messages or unknown packets
  • 2 - major events/alarms.
  • 3 - commands sent out will be logged.
  • 4 - you'll see whats received by the different devices.
  • 5 - debugging.
  The value for the global device is a default for other devices without own verbose attribute set.

readingFnAttributes

The following global attributes are honored by the modules that make use of the standardized readings updating mechanism in fhem.pl. Check the module's attribute list if you want to know if a device supports these attributes.

• stateFormat
  Modifies the STATE of the device, shown by the list command or in the room overview in FHEMWEB. If not set, its value is taken from the state reading. If set, then every word in the argument is replaced by the value of the reading if such a reading for the current device exists. If the value of this attribute is enclosed in {}, then it is evaluated. This attribute is evaluated each time a reading is updated.
  The "set magic" described here is also applied.
  Note: some FHEM modules are setting STATE directly (against the guidelines), in this case the attribute may not work as expected.
• event-on-update-reading
  If not set, every update of any reading creates an event, which e.g. is handled by notify or FileLog. The attribute takes a comma-separated list of readings. You may use regular expressions in that list. If set, only updates of the listed readings create events.
• event-on-change-reading
  The attribute takes a comma-separated list of readings. You may use regular expressions in that list. If set, only changes of the listed readings create events. In other words, if a reading listed here is updated with the new value identical to the old value, no event is created. If an optional [:threshold] is given after a reading name events are only generated if the change is >= threshold.
The precedence of event-on-update-reading and event-on-change-reading is as follows:
1. If both attributes are not set, any update of any reading of the device creates an event.
2. If any of the attributes is set, no events occur for updates or changes of readings not listed in any of the attributes.
3. If a reading is listed in event-on-update-reading, an update of the reading creates an event no matter whether the reading is also listed in event-on-change-reading.
• timestamp-on-change-reading
  The attribute takes a comma-separated list of readings. You may use regular expressions in that list. If set, the listed readings will not be changed (or created) if event-on-change-reading is also set and it would not create an event for this reading.
• event-aggregator The primary uses of this attribute are to calculate (time-weighted) averages of readings over time periods and to throttle the update rate of readings and thus the amount of data written to the logs.

  This attribute takes a comma-separated list of reading:interval:method:function:holdTime quintuples. You may use regular expressions for reading. If set, updates for the listed readings are ignored and associated events are suppressed for a black-out period of at least interval seconds (downsampling). After the black-out period has expired, the reading is updated with a value that is calculated from the values and timestamps of the previously ignored updates within the black-out period as follows:

  function	description
  v	the last value encountered
  v0	the first value encountered
  min	the smallest value encountered
  max	the largest value encountered
  mean	the arithmetic mean of all values
  sd	the standard deviation from the mean
  median	the median of all values (requires holdTime and method none)
  integral	the arithmetic sum (if not time-weighted) or integral area (if time-weighted) of all values
  n	number of samples
  t	timestamp of the last value
  t0	timestamp of the first value

  If method is none, then that's all there is. If method is const or linear, the time-weighted series of values is taken into account instead. The weight is the timespan between two subsequent updates. With the const method, the value is the value of the reading at the beginning of the timespan; with the linear method, the value is the arithmetic average of the values at the beginning and the end of the timespan. Rollovers of black-out periods are handled as one would expect it.

  One would typically use the linear method with the mean function for quantities continuously varying over time like electric power consumption, temperature or speed. For cumulative quantities like energy consumed, rain fallen or distance covered, the none method with the v function is used. The constant method is for discrete quantities that stay constant until the corresponding reading is updated, e.g. counters, switches and the like.

  If the holdTime in seconds is defined, the samples will be kept in memory allowing the calculation of floating statistics instead of blocked statistics. With holdTime defined the interval can be kept undefined so that the readings update rate is unchanged or it can be set to a value less then holdTime for downsampling as described above with a full history of the readings in memory. Note that the historic samples are not persistent and will be lost when restarting FHEM.

  The event aggregator only takes into consideration those updates that remain after preprocessing according to the event-on-update-reading and event-on-change-reading directives. Besides which, any update of a reading that occurs within a timespan from the preceding update that is smaller than the resolution of FHEM's time granularity is ditched.

  When more than one function should be calculated for the same reading, the original reading must be multiplied (e.g. by using a notify) before applying the event-aggregator to the derived readings.

  Examples:
  attr myPowerMeter event-aggregator EP_POWER_METER:300:linear:mean,EP_ENERGY_METER:300:none:v
attr myBadSensor event-aggregator TEMP::none:median:300
attr mySunMeter event-aggregator SUN_INTENSITY_24H::const:integral:86400

• event-min-interval
  This attribute takes a comma-separated list of reading:minInterval pairs. You may use regular expressions for reading. Events will only be generated, if at least minInterval seconds elapsed since the last reading of the matched type. If event-on-change-reading is also specified, they are combined with OR: if one of them is true, the event is generated.
• oldreadings
  This attribute takes a comma-separated list of readings. You may use regular expressions in that list. For each reading in the list FHEM will internaly store the previous value if the readings value changes. To access the storead value use the OldReadings.* functions. If the previous value is always to be stored (even if it didn't changed), then set the last value of the comma-separated list to oldreadingsAlways.
• userReadings
  A comma-separated list of definitions of user-defined readings. Each definition has the form:
  <reading>[:<trigger>] [<modifier>] { <perl code> }
  After a single or bulk readings update, the user-defined readings are set by evaluating the perl code { <perl code> } for all definitions and setting the value of the respective user-defined reading <reading> to the result. If <trigger> is given, then all processing for this specific user reading is only done if one of the just updated "reading: value" combinations matches <trigger>, which is treated as a regexp.
  Examples:
  
  attr myEnergyMeter userReadings energy { ReadingsVal("myEnergyMeter","counters.A",0)/1250.0;; }
attr myMultiMeter userReadings energy1:counters.A.* { ReadingsVal("myMultiMeter","counters.A",0)/1250.0;; }, energy2:counters.B.* { ReadingsVal("myMultiMeter","counters.B",0)/1250.0;; }
  <modifier> can take one of these values:
  • none: the same as it would not have been given at all.
  • difference: the reading is set to the difference between the current and the previously evaluated value.
  • differential: the reading is set to the difference between the current and the previously evaluated value divided by the time in seconds between the current and the previous evaluation. Granularity of time is one second. No value is calculated if the time past is below one second. Useful to calculate rates.
  • integral: reverse function of differential. The result is incremented by the product of the time difference between the last two readings and the avarage of the last two readings.
    result += (time - timeold) * (oldval + value) / 2
  • offset: if the current evaluated value is smaler than the previously evaluated value the reading is incremented by the previous value. the reading can then be used as an offset correct for a counter that is reset for example due to a power loss.
  • monotonic: if the difference between the current and the previously evaluated value is positive the reading is incremented by this difference. this allows to derive a monotonic growing counter from an original counter even if the original will be rest by a power loss
  Example:
  
  attr myPowerMeter userReadings power differential { ReadingsVal("myPowerMeter","counters.A",0)/1250.0;; }
  Notes:
  • user readings with modifiers difference and differential store the calculated values internally. The user reading is set earliest at the second evaluation. Beware of stale values when changing definitions!
  • the name of the defined Readings consists of alphanumeric characters with underscore (_) and the minus (-) sign.

Common attributes

The following local attributes are used by a wider range of devices:

• IODev
  Set the IO or physical device which should be used for sending signals for this "logical" device. An example for the physical device is an FHZ or a CUL. Note: Upon startup FHEM assigns each logical device (FS20/HMS/KS300/etc) the last physical device which can receive data for this type of device. The attribute IODev needs to be used only if you attached more than one physical device capable of receiving signals for this logical device.


• disable
  Disables the corresponding device. Note: it can be toggled by issuing the following command:
  
  attr <device> disable toggle


• disabledForIntervals HH:MM-HH:MM HH:MM-HH:MM ...
  Space separated list of HH:MM or D@HH:MM tupels. If the current time is between the two time specifications, the current device is disabled. Instead of HH:MM you can also specify HH or HH:MM:SS. D is the day of the week, with 0 indicating Sunday and 3 indicating Wednesday. Specifying the day for the "from" part does _not_ specify it for the "to" part, i.e. 1@00-24 will disable from monday to the end of the week, but not on sunday (as 1@00 is greater than any time on sunday). To specify an interval spawning midnight, you have to specify two intervals, e.g.:
  23:00-24:00 00:00-01:00
  If parts of the attribute value are enclosed in {}, they are evaluated:
  {sunset_abs()}-24 {sunrise_abs()}-08

attr

attr [-a|-r|-silent] <devspec> <attrname> [<value>]

Set an attribute for a device defined by define. The value is optional, and is set to 1 if missing. You can define your own attributes too to use them in other applications. Use "attr <name> ?" to get a list of possible attributes. See the Device specification section for details on <devspec>. After setting the attribute, the global event "ATTR" will be generated.
If the option -a is specified, append the given value to the currently existing value. Note: if the value does not start with a comma (,), then a space will be added automatically to the old value before appending the new.
With the -r option one can remove a part of an attribute value.
With the -silent option the command is not recorded in the "save -?" list.

Examples:
attr global verbose 3
attr lamp room kitchen
attr lamp group lights
attr lamp loglevel 6
attr weatherstation event-on-update-reading wind,temperature,humidity
attr weatherstation event-on-change-reading israining
attr weatherstation event-on-change-reading israining,state
attr heating stateFormat Temp:measured-temp, Valve:actuator
attr -a TYPE=SVG room ,SvgRoom
attr -r TYPE=SVG room ,SvgRoom


Notes:

• See deleteattr to delete attributes.

cancel

cancel [<id> [quiet]]

List named sleeps or cancel a named sleep.

define

define [option] <name> <type> <type-specific>

Define a device. You need devices if you want to manipulate them (e.g. set on/off), and the logfile is also more readable if it contains e.g. "lamp off" instead of "Device 5673, Button 00, Code 00 (off)".
After definition, the global event "DEFINED" will be generated, see the notify section for details.


Each device takes different additional arguments at definition, see the corresponding device section for details.

Options:

• -temporary
  Add the TEMPORARY flag to the definition, which will prevent saving the device to fhem.cfg.


• -ignoreErr
  Reduce the number of errors displayed when a certain FHEM-module cannot be loaded. Used by fhem.cfg.demo, as using the RSS example requires the installation of several uncommon perl modules.


• -silent
  Do no enter the command in the "save ?" list.

defmod

defmod [option] <name> <type> <type-specific>

Define a device or modify it, if it already exists. E.g. to switch off a lamp 10 Minutes after the last message from the motion detector, you may use
define mdNtfy notify motionDetector defmod mdOff at +00:10 set lamp off
Using define here for the mdOff will generate an error if the motion detector triggers within the 10 minutes after the first event, as the mdOff at definition still exists.
For the options see the define documentation.

delete

delete <devspec>

Delete something created with the define command. See the Device specification section for details on <devspec>.
After deletion, the global event "DELETED" will be generated, see the notify section for details.
Examples:
delete lamp

deleteattr

deleteattr [-silent] <devspec> [<attrname>]

Delete either a single attribute (see the attr command) or all attributes for a device (if no <attrname> is defined). See the Device specification section for details on <devspec>.
<attrname> is in fact a regexp, complemented with ^ and $ as usual, so a range of attributes can be deleted with one command.
After deleting the attribute, the global event "DELETEATTR" will be generated.
Examples:
deleteattr lamp follow-on-for-timer
deleteattr lamp

deletereading

deletereading <devspec> <readingname> [<older-than-seconds>]

Delete the reading <readingname> for a device. <readingname> is a perl regular expression that must match the whole name of the reading. Use with greatest care! FHEM might crash if you delete vital readings of a device. See the Device specification section for details on <devspec>.

Examples:
deletereading mySensor temp1
deletereading mySensor temp\d+

displayattr

displayattr <devspec> [<attrname>]

Display either the value of a single attribute (see the attr command) or all attributes for a device (if no <attrname> is defined). See the Device specification section for details on <devspec>.
If more then one device is specified, then the device name will also included in the output.
Examples:
fhem> di WEB
menuEntries AlarmOn,/fhem?cmd=set%20alarm%20on
room Misc.
fhem> di WEB room
Misc.


get

get <devspec> <type-specific>

Ask a value directly from the device, and wait for an answer. In general, you can get a list of possible parameters by
get <device> ?
See the Device specification section for details on <devspec>.

Each device has different get parameters, see the corresponding device section for details.

include

include <filename>

Read in the file, and process every line as a FHEM command. Note: only experts should use this command.

inform

inform {on|onWithState|off|raw|timer|log|status} [regexp]

Monitor events via a telnet client. This command is the telnet equivalent of the FHEMWEB Event monitor, but can also be used by other programs/modules to receive a notification. Options:

• on
  switch the inform mechanism on
• onWithState
  show the additional state event too
• off
  switch the inform mechanism off (both events and logs, see below)
• raw
  show only raw events from physical devices
• timer
  prepend a timestamp to each event
• log
  show messages written by the FHEM Log interface
• status
  show the current status

list

list [devspec] [value ...]
or
list {-r|-R} devspec


Output a list of all definitions, all notify settings and all at entries. This is one of the few commands which return a string in a normal case. See the Device specification section for details on <devspec>.
If <value> is specified, then output this property (internal, reading or attribute) for all devices from the devspec. <value> can be restricted with prefix i: for internals, r: for readings and a: for attributes.

Example:

  fhem> list

  Type list <name> for detailed info.

  Internal:
    global               (Internal)

  FHZ:
    FHZ                  (fhtbuf: 23)

  FS20:
    Btn4                 (on-old-for-timer)
    Roll1                (on)
    Stehlampe            (off)

  FHT:
    fl                   (measured-temp: 21.1 (Celsius))

  KS300:
    out1                 (T: 2.9  H: 74  W: 2.2  R: 8.2  IR: no)

  at:
    at_rollup            (Next: 07:00:00)

  notify:
    ntfy_btn4            (active)

  FileLog:
    avglog               (active)

  

If specifying name, then a detailed status for name will be displayed, e.g.:

  fhem> list fl

  Internals:
    CODE       5102
    DEF        5102
    NAME       fl
    NR         15
    STATE      measured-temp: 21.1 (Celsius)
    TYPE       FHT
    IODev      FHZ
  Attributes:
    room       Heizung
  Readings:
    2006-11-02 09:45:56   actuator        19%
    [...]
  

With the -r (raw) option output the device definition in a format suitable for inclusion in fhem.cfg and fhem.state. -R returns the definition of the device itself, together with the definition of probably associated devices. Note: the algorithm to select associated devices is known to be imperfect.

modify

modify [-silent] <name> <type-dependent-options>

Used to modify some definitions. Useful for changing some at or notify definitions. If specifying one argument to an at type definition, only the time part will be changed. In case of a notify type definition, only the regex part will be changed. All other values (state, attributes, etc) will remain intact. After modify, the global event "MODIFIED" will be generated.
With the -silent option the command is not recorded in the "save -?" list.

Example:
define lampon at 19:00 set lamp on
modify lampon *19:00
modify lampon 19:00 set lamp on-for-timer 16

quit

quit

If used in a TCP/IP session, terminate the client session.
If used in a script, terminate the parsing of the current script.

Example:
quit

reload

reload <module>

Reload the given module from the module directory. It is a convenient way to test modules whithout restarting the program.

Example:
reload 99_PRIV

rename

rename <oldname> <newname>

Rename a device from the <oldname> to <newname>, together with its attributes. The global event RENAMED will be generated, see the notify section for details.

Example:
rename FHT_1234 fht.kitchen

rereadcfg

rereadcfg [fhem-config-file]

Re-read the active configuration file, or the optionally specified file.
The sequence: the statefile will be saved first, then all devices will be deleted, then the currently active config file (or the specified file) will be read and at last the statefile will be reloaded.
Upon completion it triggers the global:REREADCFG event. All existing connections up to the one issuing the rereadcfg will be closed.

Example:
rereadcfg

save

save [<configfile>]

Save first the statefile, then the configfile information. If a parameter is specified, it will be used instead the global configfile attribute.

Notes:
• save only writes out definitions and attributes, but no (set/get) commands which were previously part of the config file. If you need such commands after the initialization (e.g. FHTcode), you should trigger them via notify, when receiving the INITIALIZED event.
• save tries to preserve comments (lines starting with #) and include structures, but it won't work correctly if some of these files are not writeable.
• before overwriting the files, the old version will be saved, see the restoreDirs global attribute for details.

set

set <devspec> <type-specific>

Set parameters of a device / send signals to a device. You can get a list of possible parameters by
set <name> ?
See the Device specification section for details on <devspec>. The set command returns only a value on error.

Each device has different set parameters, see the corresponding device section for details.


From featurelevel 5.7 on the set and setreading command replaces:
• [device:name] with the reading, internal or attribute of the device, if both device and the reading, internal or attribute exists.
  • You can use the r:, i: or a: prefix to restrict the search to one type, analogue to the devspec filtering.
  • The suffix :d retrieves the first number
  • The suffix :i retrieves the integer part of the first number.
  • The suffix :r<n> retrieves the first number and rounds it to <n> decimal places. If <n> is missing, then rounds it to one decimal place.
  • The suffix :t returns the timestamp (works only for readings)
  • The suffix :sec returns the number of seconds since the reading was set.
  Example:
  set Lamp blink [blinkDummy:number] [r:blinkDummy:duration:d]
• [device:name:d] same as above, but only the number is retrieved
• [device:name:sec] same as above, but only the number is retrieved
• {(perlExpression)} with the result of perlExpression. The $DEV variable is additionally available, designating the set device name.
These replacements are also known as "set magic".

Some modules support a common list of set extensions, and point in their documentation to this section. If the module itself implements one of the following commands, then the module-implementation takes precedence.
• on-for-timer <seconds>
  Issue the on command for the device, and after <seconds> the off command. For issuing the off command an internal timer will be scheduled, which is deleted upon a restart. To delete this internal timer without restart specify 0 as argument.
• off-for-timer <seconds>
  see on-for-timer above.
• on-till <timedet>
  Issue the on command for the device, and create an at definition with <timedet> (in the form HH:MM[:SS]) to set it off. This definition is visible, and its name is deviceName+"_till". To cancel the scheduled off, delete the at definition. Note: on-till is not active, if the specified time is after the current time, in order to make things like
  define morningLight at *06:00 set Lamp on-till {sunrise()}
  easy.
• on-till-overnight <timedet>
  Like on-till, but wont compare the current time with the timespec, so following will work:
  define nightLight at *{sunset()} set Lamp on-till-overnight 01:00
• off-till <timedet>
  see on-till above.
• off-till-overnight <timedet>
  see on-till-overnight above.
• blink <number> <blink-period>
  set the device on for <blink-period> then off for <blink-period> and repeat this <number> times. To stop blinking specify "0 0" as argument.
• intervals <from1>-<till1> <from2>-<till2>...
  set the device on for the specified intervals, which are all timespecs in the form HH:MM[:SS]. The intervals are space separated.
• toggle
  Issue the off command, if the current STATE is on, else the on command. dim XX is also interpreted as on, if XX is not 0.
Examples:
set switch on-for-timer 12.5
set switch on-till {sunset()}
set switch blink 3 1
set switch intervals 08:00-12:00 13:00-18:00



attrTemplate
with this command a set of predefined attributes may be set at once. The template files containing the entries are in FHEM/lib/AttrTemplate directory. Template entries can be module specific, and may require further parameters to be specified.

setdefaultattr

setdefaultattr [<attrname> [<value>]]

Add a default attribute. Each device defined from now on will receive this attribute.
If no attrname is specified, then the default attribute list will be deleted.

Example to set the attribute "room kitchen" and "loglevel 4" to each of the lamps:
setdefaultattr room kitchen
setdefaultattr loglevel 4
define lamp1 FS20 1234 11
define lamp2 FS20 1234 12
define lamp3 FS20 1234 13
setdefaultattr


Notes:

• There is no way to delete a single default-attribute from the list

setreading

setreading <devspec> [YYYY-MM-DD HH:MM:SS] <reading> <value>

Set the reading <reading> for the device <name> to <value> without sending out commands to the device, but triggering events and eventMap/stateFormat transformations as usual. See the set command documentation for replacement description.
If the timespec is omitted (default) the current time will be used.

Examples:
setreading lamp state on
Note: setreading won't generate an event for device X, if it is called from a notify for device X. Use "sleep 0.1; setreading X Y Z" in this case.

setstate

setstate <devspec> <value>

Set the STATE entry for the device specified by <devspec>, which is used for displaying the device state in different frontends. No signals will be sent to the device, no events will be generated, and no eventMap or stateFormat translation will be done either. This command is also used in the statefile. See the Device specification section for details on <devspec>.

Examples:
setstate lamp on
Note: this command is also used to store the readings in the statefile, in this case the timestamp will preceed the value. As a side-effect there is no way to save a state correctly if it starts with a timestamp in the YYYY-MM-DD HH:MM:SS form.

setuuid

setuuid <device> <uuid>

System command, used to set the FUUID internal value. Not intended to be used by an end user.

show

show <devspec>

show a temporary room with devices from <devspec>. The command ist only available through FHEMWEB.
See the Device specification section for details on <devspec>.

Example:
show TYPE=CUL_HM

shutdown

shutdown [restart|exitValue]

Shut down the server (after saving the state information ). It triggers the global:SHUTDOWN event. If the optional restart parameter is specified, FHEM tries to restart itself. exitValue may be important for start scripts.

Example:
shutdown
shutdown restart
shutdown 1

sleep

sleep <sec|timespec|regex> [<id>] [quiet]

sleep followed by another command is comparable to a nameless at or notify, it executes the following commands after waiting for the specified time or an event matching <regex>. The delay can be given
• in seconds, with millisecond accuracy, as you can specify decimal places,
• as a timespec (HH:MM or HH:MM:SS or {perlfunc})
• or as a regex (devicename or devicename:event)

A sleep with an <id> will replace a sleep with the same <id> and can be canceled by cancel. When called in a notify/at/etc, then nonempty return values of the following commands are logged to the global logfile with loglevel 2.
If quiet is specified, then skip this logging.

Example:
define n3 notify btn3.* set lamp on;;sleep 1.5;;set lamp off
define a3 at +*00:05 set Windsensor 1w_measure;; sleep 2 quiet;; get Windsensor 1w_temp

Note: a sleep not followed by any command will block FHEM, is deprecated, and it issues a WARNING in the FHEM log.

trigger

trigger <devspec> <state>

Trigger a notify definition. See the Device specification section for details on <devspec>.

Example:
trigger btn3 on

global

The global device is used to set different global attributes. It will be automatically defined, it cannot be deleted or renamed and has no set or get parameters

Define
N/A

Set
N/A

Get
N/A

Internals
• init_errors
  contains configuration errors and security issues collected at FHEM startup.



Attributes
• altitude
  Specifies the mean sea level in meters. Default is 0.


• archivedir
• archivecmd
• nrarchive
• archivesort
  archivesort may be set to the (default) alphanum or timestamp, and specifies how the last files are computed for the nrarchive attribute.


• autoload_undefined_devices
  If set, automatically load the corresponding module when a message of this type is received. This is used by the autocreate device, to automatically create a FHEM device upon receiving a corresponding message.


• autosave
  enable some modules to automatically trigger save after a configuration change, e.g. after a new device was created. Default is 1 (true), you can deactivate this feature by setting the value to 0. Configration errors at startup automatically deactivate this value.
• backupcmd
  You could pass the backup to your own command / script by using this attribute. If this attribute is specified, then it will be started as a shell command and passes a space separated list of files / directories as one argument to the command, like e.g.:
  
  "/etc/fhem.cfg /var/log/fhem/fhem.save /usr/share/fhem/contrib /usr/share/fhem/FHEM /usr/share/fhem/foo /usr/share/fhem/foobar /usr/share/fhem/www"
  Note: Your command / script has to return the string "backup done" or everything else to report errors, to work properly with update!
  This Attribute is used by the backup command.
  Example:
  
  attr global backupcmd /usr/local/bin/myBackupScript.sh


• backupdir
  A folder to store the compressed backup file. This Attribute is used by the backup command.
  Example:
  
  attr global backupdir /Volumes/BigHD


• backupsymlink
  If this attribute is set to everything else as "no", the archive command tar will support symlinks in your backup. Otherwise, if this attribute is set to "no" symlinks are ignored by tar. This Attribute is used by the backup command.
  Example:
  
  attr global backupsymlink yes


• blockingCallMax
  Limit the number of parallel running processes started by the BlockingCall FHEM helper routine. Useful on limited hardware, default is 32. If the limit is reached, further calls are delayed.


• configfile
  Contains the name of the FHEM configuration file. If save is called without argument, then the output will be written to this file.


• commandref
  If set to "full", then a full commandref will be generated after each update. If set to modular (default since FHEM 6.1), there is only a short description at the beginning, and the module documentation is loaded from FHEM dynamically.


• disableFeatures
  comma separated list of values. Currently following values are recognized:
  • attrTemplate: to avoid loading the AttrTemplates (which currently consumes about 1MB of memory and needs some seconds to load on a slow hardware)
  • securityCheck: to avoid checking if each Server port is secured by password. May make sense to avoid warnings, if you know it better.
  
  
• dnsHostsFile
  If dnsServer is set, check the contents of the file specified as argument. To use the system hosts file, set it to /etc/hosts on Linux/Unix/OSX and C:\windows\system32\drivers\etc\hosts on Windows. Note: only IPv4 is supported.


• dnsServer
  Contains the IP address of the DNS Server. If some of the modules or user code calls the HttpUtils_NonblockingGet function, and this attribute is set, then FHEM specific nonblocking code will be used to resolve the given address. If this attribute is not set, the blocking OS implementation (inet_aton and gethostbyname) will be used.


• encoding
  Set the internal encoding used for storing strings. Possible values: bytestream (default) and unicode.
  Notes:
  • Since not all modules were checked, if they work correctly with the internal unicode encoding, this feature is experimental.
  • Changing the attribute value triggers a save and a shutdown restart


• featurelevel
  Enable/disable old or new features, based on FHEM version. E.g. the $value hash for notify is only set for featurelevel up to 5.6, as it is deprecated, use the Value() function instead.


• holiday2we
  If this attribute is set, then the $we variable will be true, if it is either saturday/sunday, or the value of the holiday variable referenced by this attribute is not none.
  If it is a comma separated list, then it is true, if one of the referenced entities is not none.
  Example:
  
  attr global holiday2we he
  Note: if one of the elements in the list is named weekEnd, then the check for saturday/sunday is skipped If the name is noWeekEnd, and its Value is not none, than $we is 0.


• httpcompress
  the HttpUtils module is used by a lot of FHEM modules, and enables compression by default. Set httpcompress to 0 to disable this feature.


• ignoreRegexp
  Do not log messages matching the value into the FHEM log. Note: the usual ^ and $ will be appended to the regexp, like in notify or FileLog.


• keyFileName
  FHEM modules store passwords and unique IDs in the file FHEM/FhemUtils/uniqueID. In order to start multiple FHEM instances from the same directory, you may set this attribute, whose value will appended to FHEM/FhemUtils/


• latitude
  Used e.g. by SUNRISE_EL to calculate sunset/sunrise.
  Default is Frankfurt am Main, Germany (50.112).


• longitude
  Used e.g. by SUNRISE_EL to calculate sunset/sunrise.
  Default is Frankfurt am Main, Germany (8.686).


• logdir
  If set, the %L attribute in the logfile attribute (or in the FileLog modules file definition) is replaced wth the value of the attribute. Note: changing the value won't result in moving the files and may cause other problems.


• logfile
  Specify the logfile to write. You can use "-" for stdout, in this case the server won't background itself.
  The logfile name can also take wildcards for easier logfile rotation, see the FileLog section. Just apply the archivecmd / archivedir / nrarchive attributes to the global device as you would do for a FileLog device.
  You can access the current name of the logfile with { $currlogfile }.


• maxChangeLog
  FHEM stores the structural change history which is displayed by "save ?" or in FHEMWEB by clicking on the red question mark. By default this list is limited to 10 entries, this attribute changes the limit.
  The length of each stored line is limited to 40 characters. This value can be changed with the (optional, space separated) second number.
  Example: attr global myxChangeLog 20 200


• maxShutdownDelay
  Some modules need some time at shutdown to finish the cleanup, but FHEM restricts the delay to 10 seconds. Use this attribute to modify the maximum delay.


• modpath
  Specify the path to the modules directory FHEM. The path does not contain the directory FHEM. Upon setting the attribute, the directory will be scanned for filenames of the form NN_<NAME>.pm, and make them available for device definition under <NAME>. If the first device of type <NAME> is defined, the module will be loaded, and its function with the name <NAME>_Initialize will be called. Exception to this rule are modules with NN=99, these are considered to be utility modules containing only perl helper functions, they are loaded at startup (i.e. modpath attribute definition time).


• motd
  Message Of The Day. Displayed on the homescreen of the FHEMWEB package, or directly after the telnet logon, before displaying the fhem> prompt. In addition, the content of the internal value init_errors will be displayed. To avoid displaying messages set its value to none.


• mseclog
  If set, the timestamp in the logfile will contain a millisecond part.


• nofork
  If set and the logfile is not "-", do not try to background. Needed on some Fritzbox installations, and it will be set automatically for Windows.


• perlSyntaxCheck
  by setting the global attribute perlSyntaxCheck, a syntax check will be executed upon definition or modification, if the command is perl and FHEM is already started.


• pidfilename
  Write the process id of the perl process to the specified file. The server runs as a daemon, and some distributions would like to check by the pid if we are still running. The file will be deleted upon shutdown.


• proxy
  IP:PORT of the proxy server to be used by HttpUtils.


• proxyAuth
  Base64 encoded username:password


• proxyExclude
  regexp for hosts to exclude when using a proxy


• restoreDirs
  update saves each file before overwriting it with the new version from the Web. For this purpose update creates a directory restoreDir/update in the global modpath directory, then a subdirectory with the current date, where the old version of the currently replaced file is stored. The default value of this attribute is 3, meaning that 3 old versions (i.e. date-directories) are kept, and the older ones are deleted.
  fhem.cfg and fhem.state will be also copied with this method before executing save into restoreDir/save/YYYY-MM-DD. To restore the files, you can use the restore FHEM command.
  
  If the attribute is set to 0, the feature is deactivated.


• sendStatistics
  
• statefile
  Set the filename where the state and certain at information will be saved before shutdown. If it is not specified, then no information will be saved.


• title
  
• useInet6
  try to use IPv6 in HttpUtils for communication. If the server does not have an IPv6 address, fall back to IPv4. Note: IO::Socket::INET6 is required.


• userattr
  A space separated list which contains the names of additional attributes for all devices. Without specifying them you will not be able to set them (in order to prevent typos).
  userattr can also specified for other devices, in this case these additional attribute names are only valid for this device.


• dupTimeout
  Define the timeout for which 2 identical events from two different receiver are considered a duplicate. Default is 0.5 seconds.


• showInternalValues
  Show data used for internal computations. If the name of an internal value, reading or attribute starts with dot (.), then it is normally hidden, and will only be visible, if this attribute is set to 1. The attribute is checked by the list command, by the FHEMWEB room overview and by xmllist.


• sslVersion
  Specifies the accepted cryptography algorithms by all modules using the TcpServices helper module. The current default TLSv12:!SSLv3 is thought to be more secure than the previously used SSLv23:!SSLv3:!SSLv2, but it causes problems with some not updated web services.


• stacktrace
  if set (to 1), dump a stacktrace to the log for each "PERL WARNING".


• restartDelay
  set the delay for shutdown restart, default is 2 (seconds).



Events:
• INITIALIZED
  after initialization is finished.
• REREADCFG
  after the configuration is reread.
• SAVE
  before the configuration is saved.
• SHUTDOWN
  before FHEM is shut down.
• DEFINED <devname>
  after a device is defined.
• DELETED <devname>
  after a device was deleted.
• RENAMED <old> <new>
  after a device was renamed.
• UNDEFINED <defspec>
  upon reception of a message for an undefined device.
• MODIFIED <defspec>
  after a device modification.
• UPDATE
  after an update is completed.
• CANNOT_FORK
  if BlockingCall encounters this problem.

ALL4027

Note: this module needs the HTTP::Request and LWP::UserAgent perl modules.

Define
define <name> ALL4027 <ip-address> <port> <relay_nr> <delay>

Defines an Allnet 4027 device (Box with 8 relays) connected to an ALL4000 via its ip address. The status of the device is also pooled (delay interval), because someone else is able to change the state via the webinterface of the device.

Examples:
define lamp1 ALL4027 192.168.8.200 0 7 60


Set
set <name> <value>

where value is one of:


    off
    on
    on-for-timer <Seconds>
    toggle
    

Examples:
set poolpump on


Notes:
• Toggle is special implemented. List name returns "on" or "off" even after a toggle command

AMADCommBridge

AMAD - Automagic Android Device
AMADCommBridge - Communication bridge for all AMAD devices
This module is the central point for the successful integration of Android devices in FHEM. It also provides a link level between AMAD supported devices and FHEM. All communication between AMAD Android and FHEM runs through this interface.
Therefore, the initial setup of an AMAD device is also performed exactly via this module instance.

In order to successfully establish an Android device in FHEM, an AMADCommBridge device must be created in the first step.

Define

define <name> AMADCommBridge

Example:

define AMADBridge AMADCommBridge


This statement creates a new AMADCommBridge device named AMADBridge.

The APP Automagic or Tasker can be used on the Android device.

For Autoremote:
In the following, only the Flowset has to be installed on the Android device and the Flow 'First Run Assistant' run. (Simply press the Homebutton)
The wizard then guides you through the setup of your AMAD device and ensures that at the end of the installation process the Android device is created as an AMAD device in FHEM.

For Tasker:
When using Tasker, the Tasker-project must be loaded onto the Android device and imported into Tasker via the import function.
For the initial setup on the Android device there is an Tasker input mask (Scene), in which the required parameters (device name, device IP, bridgeport etc.)
can be entered, these fields are filled (if possible) automatically, but can also be adjusted manually.
To do this, run the "AMAD" task.
For quick access, a Tasker shortcut can also be created on the home screen for this task.
Information on the individual settings can be obtained by touching the respective text field.
If all entries are complete, the AMAD Device can be created via the button "create Device".
For control commands from FHEM to Tasker, the APP "Autoremote" or "Tasker Network Event Server (TNES)" is additionally required.

Readings


• JSON_ERROR - JSON Error message reported by Perl
• JSON_ERROR_STRING - The string that caused the JSON error message
• receiveFhemCommand - is set the fhemControlMode attribute to trigger, the reading is set as soon as an FHEM command is sent. A notification can then be triggered.
  If set instead of trigger setControl as value for fhemControlMode, the reading is not executed but the set command executed immediately.
• receiveVoiceCommand - The speech control is activated by AMAD (set DEVICE activateVoiceInput), the last recognized voice command is written into this reading.
• receiveVoiceDevice - Name of the device from where the last recognized voice command was sent
• state - state of the Bridge, open, closed


Attributes


• allowFrom - Regexp the allowed IP addresses or hostnames. If this attribute is set, only connections from these addresses are accepted.
  Attention: If allowfrom is not set, and no kind allowed instance is defined, and the remote has a non-local address, then the connection is rejected. The following addresses are considered local:
  IPV4: 127/8, 10/8, 192.168/16, 172.16/10, 169.254/16
  IPV6: ::1, fe80/10
• debugJSON - If set to 1, JSON error messages are written in readings. See JSON_ERROR * under Readings
• fhemControlMode - Controls the permissible type of control of FHEM devices. You can control the bridge in two ways FHEM devices. Either by direct FHEM command from a flow, or as a voice command by means of voice control (set DEVICE activateVoiceInput)
  • trigger - If the value trigger is set, all FHEM set commands sent to the bridge are written to the reading receiveFhemCommand and can be executed using notify. Voice control is possible; readings receiveVoice * are set. On the Android device several voice commands can be linked by means of "and". Example: turn on the light scene in the evening and turn on the TV
  • setControl - All set commands sent via the flow are automatically executed. The triggering of a reading is not necessary. The control by means of language behaves like the value trigger
  • thirdPartControl - Behaves as triggered, but in the case of voice control, a series of voice commands by means of "and" is not possible. Used for voice control via modules of other module authors ((z.B. 39_TEERKO.pm)


If you have problems with the wizard, an Android device can also be applied manually, you will find in the Commandref to the AMADDevice module.

AMADDevice

AMAD - Automagic Android Device
This module integrates Android devices into FHEM and displays several settings using the Android app "Automagic" or "Tasker". Automagic is comparable to the "Tasker" app for automating tasks and configuration settings. But Automagic is more user-friendly. The "Automagic Premium" app currently costs EUR 2.90.
Any information retrievable by Automagic/Tasker can be displayed in FHEM by this module. Just define your own Automagic-"flow" or Tasker-"task" and send the data to the AMADCommBridge. One even can control several actions on Android devices.
To be able to make use of all these functions the Automagic/Tasker app and additional flows/Tasker-project need to be installed on the Android device. The flows/Tasker-project can be retrieved from the FHEM directory, the app can be bought in Google Play Store.

How to use AMADDevice?
• first, make sure that the AMADCommBridge in FHEM was defined
• Using Automagic
• install the "Automagic Premium" app from the PlayStore
• install the flowset 74_AMADDeviceautomagicFlowset$VERSION.xml file from the $INSTALLFHEM/FHEM/lib/ directory on the Android device
• activate the "installation assistant" Flow in Automagic. If one now sends Automagic into the background, e.g. Homebutton, the assistant starts and creates automatically a FHEM device for the android device
• Using Tasker
• install the "Tasker" app from the PlayStore
• install the Tasker-project 74_AMADtaskerset_$VERSION.prj.xml file from the $INSTALLFHEM/FHEM/lib/ directory on the Android device
• run the "AMAD" task in Tasker and make your initial setup, by pressing the "create Device" button it will automatically create the device in FHEM


Define a AMADDevice device by hand.

Define

define <name> AMADDevice <IP-ADRESSE> <AMAD_ID> <REMOTESERVER>

Example:

define WandTabletWohnzimmer AMADDevice 192.168.0.23 123456 Automagic


In this case, an AMADDevice is created by hand. The AMAD_ID, here 123456, must also be entered exactly as a global variable in Automagic/Tasker.



Readings
• airplanemode - on/off, state of the aeroplane mode
• androidVersion - currently installed version of Android
• automagicState - state of the Automagic or Tasker App (prerequisite Android >4.3). In case you have Android >4.3 and the reading says "not supported", you need to enable Automagic/Tasker inside Android / Settings / Sound & notification / Notification access
• batteryHealth - the health of the battery (1=unknown, 2=good, 3=overheat, 4=dead, 5=over voltage, 6=unspecified failure, 7=cold) (Automagic only)
• powerPercent - state of battery in %
• batterytemperature - the temperature of the battery (Automagic only)
• bluetooth - on/off, bluetooth state
• checkActiveTask - state of an app (needs to be defined beforehand). 0=not active or not active in foreground, 1=active in foreground, see note below (Automagic only)
• connectedBTdevices - list of all devices connected via bluetooth (Automagic only)
• connectedBTdevicesMAC - list of MAC addresses of all devices connected via bluetooth (Automagic only)
• currentMusicAlbum - currently playing album of mediaplayer (Automagic only)
• currentMusicApp - currently playing player app (Amazon Music, Google Play Music, Google Play Video, Spotify, YouTube, TuneIn Player, Aldi Life Music) (Automagic only)
• currentMusicArtist - currently playing artist of mediaplayer (Automagic only)
• currentMusicIcon - cover of currently play album Not yet fully implemented (Automagic only)
• currentMusicState - state of currently/last used mediaplayer (Automagic only)
• currentMusicTrack - currently playing song title of mediaplayer (Automagic only)
• daydream - on/off, daydream currently active
• deviceState - state of Android devices. unknown, online, offline.
• doNotDisturb - state of do not Disturb Mode
• dockingState - undocked/docked, Android device in docking station
• flow_SetCommands - active/inactive, state of SetCommands flow
• flow_informations - active/inactive, state of Informations flow
• flowsetVersionAtDevice - currently installed version of the flowsets on the Android device
• incomingCallerName - Callername from last Call
• incomingCallerNumber - Callernumber from last Call
• incomingWhatsAppMessage - last WhatsApp message
• incomingTelegramMessage - last telegram message
• incomingSmsMessage - last SMS message
• intentRadioName - name of the most-recent streamed intent radio
• intentRadioState - state of intent radio player
• keyguardSet - 0/1 keyguard set, 0=no 1=yes, does not indicate whether it is currently active
• lastSetCommandError - last error message of a set command
• lastSetCommandState - last state of a set command, command send successful/command send unsuccessful
• lastStatusRequestError - last error message of a statusRequest command
• lastStatusRequestState - ast state of a statusRequest command, command send successful/command send unsuccessful
• nextAlarmDay - currently set day of alarm
• nextAlarmState - alert/done, current state of "Clock" stock-app
• nextAlarmTime - currently set time of alarm
• nfc - state of nfc service on/off
• nfcLastTagID - nfc_id of last scan nfc Tag / In order for the ID to be recognized correctly, the trigger NFC TagIDs must be processed in Flow NFC Tag Support and the TagId's Commase-separated must be entered. (Automagic only)
• powerPlugged - 0=no/1,2=yes, power supply connected
• screen - on locked,unlocked/off locked,unlocked, state of display
• screenBrightness - 0-255, level of screen-brightness
• screenBrightnessMode - Adaptive brightness on,off
• screenFullscreen - on/off, full screen mode
• screenOrientation - Landscape/Portrait, screen orientation (horizontal,vertical)
• screenOrientationMode - auto/manual, mode for screen orientation
• state - current state of AMAD device
• userFlowState - current state of a Flow, established under setUserFlowState Attribut (Automagic only)
• volume - media volume setting
• volumeNotification - notification volume setting
• wiredHeadsetPlugged - 0/1 headset plugged out or in

Prerequisite for using the reading checkActivTask the package name of the application to be checked needs to be defined in the attribute checkActiveTask. Example: attr Nexus10Wohnzimmer checkActiveTask com.android.chrome für den Chrome Browser.




Set
• activateVoiceInput - start voice input on Android device
• bluetooth - on/off, switch bluetooth on/off
• clearNotificationBar - All/Automagic, deletes all or only Automagic/Tasker notifications in status bar
• closeCall - hang up a running call
• currentFlowsetUpdate - start flowset/Tasker-project update on Android device
• installFlowSource - install a Automagic flow on device, XML file must be stored in /tmp/ with extension xml. Example: set TabletWohnzimmer installFlowSource WlanUebwerwachen.xml (Automagic only)
• doNotDisturb - sets the do not Disturb Mode, always Disturb, never Disturb, alarmClockOnly alarm Clock only, onlyImportant only important Disturbs
• mediaPlay - play command to media App
• mediaStop - stop command to media App
• mediaNext - skip Forward command to media App
• mediaBack - skip Backward to media App
• nextAlarmTime - sets the alarm time. Only valid for the next 24 hours.
• notifySndFile - plays a media-file which by default needs to be stored in the folder "/storage/emulated/0/Notifications/" of the Android device. You may use the attribute setNotifySndFilePath for defining a different folder.
• openCall - initial a call and hang up after optional time / set DEVICE openCall 0176354 10 call this number and hang up after 10s
• screenBrightness - 0-255, set screen brighness
• screenBrightnessMode - turn Adaptive brightness on,off
• screenMsg - display message on screen of Android device
• sendintent - send intent string Example: set $AMADDEVICE sendIntent org.smblott.intentradio.PLAY url http://stream.klassikradio.de/live/mp3-192/stream.klassikradio.de/play.m3u name Klassikradio, first parameter contains the action, second parameter contains the extra. At most two extras can be used.
• sendSMS - Sends an SMS to a specific phone number. Bsp.: sendSMS Dies ist ein Test|555487263
• startDaydream - start Daydream
• statusRequest - Get a new status report of Android device. Not all readings can be updated using a statusRequest as some readings are only updated if the value of the reading changes.
• timer - set a countdown timer in the "Clock" stock app. Only minutes are allowed as parameter.
• ttsMsg - send a message which will be played as voice message (to change laguage temporary set first character &en; or &de;)
• userFlowState - set Flow/Tasker-profile active or inactive,set Nexus7Wohnzimmer Badezimmer:inactive vorheizen or set Nexus7Wohnzimmer Badezimmer vorheizen,Nachtlicht Steven:inactive
• userFlowRun - executes the specified flow/task
• vibrate - vibrate Android device
• volume - set media volume. Works on internal speaker or, if connected, bluetooth speaker or speaker connected via stereo jack
• volumeNotification - set notifications volume

Set (depending on attribute values)
• changetoBtDevice - switch to another bluetooth device. Attribute setBluetoothDevice needs to be set. See note below! (Automagic only)
• nfc - activate or deactivate the nfc Modul on/off. attribute root
• openApp - start an app. attribute setOpenApp
• openURL - opens a URLS in the standard browser as long as no other browser is set by the attribute setOpenUrlBrowser.Example: attr Tablet setOpenUrlBrowser de.ozerov.fully|de.ozerov.fully.MainActivity, first parameter: package name, second parameter: Class Name
• screen - on/off/lock/unlock, switch screen on/off or lock/unlock screen. In Automagic "Preferences" the "Device admin functions" need to be enabled, otherwise "Screen off" does not work. attribute setScreenOnForTimer changes the time the display remains switched on! (Tasker supports only "on/off" command)
• screenFullscreen - on/off, activates/deactivates full screen mode. attribute setFullscreen
• screenLock - Locks screen with request for PIN. attribute setScreenlockPIN - enter PIN here. Only use numbers, 4-16 numbers required. (Automagic only)
• screenOrientation - Auto,Landscape,Portait, set screen orientation (automatic, horizontal, vertical). attribute setScreenOrientation
• system - issue system command (only with rooted Android devices). reboot,shutdown,airplanemodeON (can only be switched ON) attribute root, in Automagic "Preferences" "Root functions" need to be enabled.
• takePicture - take a camera picture Attribut setTakePictureResolution
• takeScreenshot - take a Screenshot picture Attribut setTakeScreenshotResolution


Attribut
• setAPSSID - set WLAN AccesPoint SSID('s) to prevent WLAN sleeps (Automagic only), more than one ssid can comma seperate
• setNotifySndFilePath - set systempath to notifyfile (default /storage/emulated/0/Notifications/
• setTtsMsgSpeed - set speaking speed for TTS (For Automagic: Value between 0.5 - 4.0, 0.5 Step, default: 1.0)(For Tasker: Value between 1 - 10, 1 Step, default: 5)
• setTtsMsgLang - set speaking language for TTS, de or en (default is de)
• setTtsMsgVol - is set, change automatically the media audio end set it back
• set setTakePictureResolution - set the camera resolution for takePicture action (800x600,1024x768,1280x720,1600x1200,1920x1080)
• setTakePictureCamera - which camera do you use (Back,Front).

To be able to use "openApp" the corresponding attribute "setOpenApp" needs to contain the app package name.

To be able to switch between bluetooth devices the attribute "setBluetoothDevice" needs to contain (a list of) bluetooth devices defined as follows: attr <DEVICE> BTdeviceName1|MAC,BTDeviceName2|MAC No spaces are allowed in any BTdeviceName. Defining MAC please make sure to use the character : (colon) after each second digit/character.
Example: attr Nexus10Wohnzimmer setBluetoothDevice Logitech_BT_Adapter|AB:12:CD:34:EF:32,Anker_A3565|GH:56:IJ:78:KL:76


state
• initialized - shown after initial define.
• active - device is active.
• disabled - device is disabled by the attribute "disable".



Further examples and reading:

Wiki page for AMAD (german only)

AirUnit

AirUnit implements a FHEM device to control Danfoss AirUnits (a1,a2,w1,w2). Tested only with w2 (Feb 2021). With this module it is possible to control the most useful functions of your ventilation system.



possible Readings	units of values
Abluft_Grundstufe_Einstellung	percent
Abluft_Luefterdrehzahl	rpm
Abluft_Stufe	step
Abluft_Temperatur	degree
Aussenluft_Temperatur	degree
Bypass_aktiviert	on/off
Bypass_Dauer	hour
Feuerstaette_aktiviert	on/off
Fortluft_Temperatur	degree
Luefterstufe_manuell	step
Luftfeuchtigkeit	percent
Model	name
Modus	mode of operation
Nachtkuehlung_aktiviert	on/off
Raumluft_Temperatur_AirDail	degree
Seriennummer	number
Stosslueftung_aktiviert	on/off
Stosslueftung_Dauer	hour
Zuluft_Grundstufe_Einstellung	percent
Zuluft_Luefterdrehzahl	rpm
Zuluft_Stufe	step
Zuluft_Temperatur	degree
automatische_Stosslueftung	on/off
automatischer_Bypass	on/off
verbl.Batterielebensdauer_AirDial	percent
verbl.verbl.Filterlebensdaue	percent
Arbeitsstunden	hour



Define
define <name> AirUnit <IP-address[:Port]> [poll-interval]
If the poll interval is omitted, it is set to 300 (seconds). Smallest possible value is 30.
Usually, the port needs not to be defined.
Example: define myAirUnit AirUnit 192.168.0.12 600

Set

set <name> <option> <value>

You can set different values to any of the following options.

Options:
• Modus
  You can choose between
  "Bedarfsmodus", for automatic mode
  "Programm", you can define a programm in your AirDail-Controller and choose one.
  "Manuell", you can set the steps for the fans manually (only in manual mode). Bypass and Boost are in automatic mode.
  "Aus", the system is off for 24 hours, after this time, the system starts in automatic mode with fanstep 1.
• Luefterstufe
  You can set the steps for the fans manually. (only in manual mode)
• Stosslueftung
  You can activate/deactive the Boost-Option of your ventilation system. You can configure this mode in your AirDail-Controller, the standard fanstep 10 for 3 hours.
  It is useful if you need more Air e.g. in case of cooking or a party with more people.
• Stosslueftung_Dauer
  You can set the hours for the duration of Boost-Option manually.
• Bypass
  You can activate/deactive the Bypass-Option of you ventilations systems. Its a cooling function, the heat exchanger will be deactivated.
  You can configure this mode in your AirDail-Controller, the standard time is 3 hours.
  You can't activte it, if the outdoor temperature is under 5°C.
  This option is not available for w1-unit.
• Bypass_Dauer
  You can set the hours for the duration of Bypass-Option manually.
• Nachtkuehlung
  You can activate/deactive the nightcooling option of you ventilations systems. You can configure this in your AirDail-Controller.
  This option is not available for w1-unit.
• automatische_Stosslueftung
  You can activate/deactive the automatic Boost-Option of you ventilations systems. Its automaticly activated, if the humidity increase very strong, then it runs for 30min.
• automatischer_Bypass
  You can activate/deactive the automatic Bypass-Option of you ventilations systems. Its automaticly activated, if the outdoor temperature and room temperature are higher then the configured values.
  You can configure this mode in your AirDail-Controller.
• Intervall
  You can setup the refresh intervall of your readings. Minimum 30 seconds.
• Feuerstaette
  You can activate/deactive the Fireplace-Option.

Get

set <name> <option> <value>

You can set different values to any of the following options.

Options:
• update
  You can refresh all values manually.

Attributes
attr <name> <attribute> <value>

Attributes:
• disable 0|1
  When you set disable to "1", the connection and the refresh intervall will be disabled. (takes a while)
  This feature gives you the possibility to use an external connection (e.g. the Danfoss-Windows-Tool) without deletion of the device.
  

additional information
• PC-Tool
  You can donwload the Danfoss-Windows-Tool HERE.
  You can start this tool with 3 different options: enduser, service or installer.
  You need only to change the "HRVPCTool.exe.config" in the installation directory.
  
  • enduser {47464213-F94A-495e-81A0-486E54CB4F64}
  • service {FC0CB02C-1695-4064-BCD9-FC0A5D77ED3D}
  • installer {E4C3938B-9F3E-427e-85CF-A42FE350326D}

Alarm

FHEM module to set up a house alarm system with 8 different alarm levels

Usage

See German Wiki page


Define

define <name> Alarm
Defines the Alarm system.

Notes:
• This module uses the global attribute language to determine its output data
  (default: EN=english). For German output set attr global language DE.
• This module needs the JSON package.

Set

• set <name> canceled <level>
  cancels an alarm of level <level>, where <level> = 0..7
• set <name> armed <level>
set <name> disarmed <level>
  sets the alarm of level <level> to armed (i.e., active) or disarmed (i.e., inactive), where <level> = 0..7
• set <name> locked
set <name> unlocked
  sets the lockstate of the alarm module to locked (i.e., alarm setups may not be changed) resp. unlocked (i.e., alarm setups may be changed>)
• set <name> save|restore
  Manually save/restore the arm states to/from the external file AlarmFILE (save done automatically at each state modification, restore at FHEM start)

Get

• get <name> version
  Display the version of the module

Attributes

• attr <name> hiddenroom <string>
  Room name for hidden alarm room (containing only the Alarm device), default: AlarmRoom
• attr <name> publicroom <string>
  Room name for public alarm room (containing sensor/actor devices), default: Alarm
• attr <name> lockstate locked|unlocked
  locked means that alarm setups may not be changed, unlocked means that alarm setups may be changed>
• attr <name> testbutton 0|1
  1 means that a test button is displayed for every actor field
• attr <name> statedisplay simple,color,table,none
  defines how the state of all eight alarm levels is shown. Example for the case when alarm no. 0 is disarmed and only alarm no. 2 is raised:
  • simple = OXOOOOO
  • color = 0 1 2 3 4 5 6 7
  • table = HTML mini table with colored fields for alarms
  • none = no state display
• attr <name> noicons 0|1
  when set to 1, animated icons are suppressed
• attr <name> iconmap list
  comma separated list of alarm levels for which the main icon/widget is set to disarmed/mixed/armed. No default=icon static
• attr <name> disarmcolor|armwaitcolor|armcolor|alarmcolor color
  four color specifications to signal the states disarmed (default lightgray), armwait (default #ffe658), armed (default #53f3c7) and alarmed (default #fd5777)
• attr <name> armdelay mm:ss
  time until the arming of an alarm becomes operative (0:00 - 9:59 allowed)
• attr <name> armwait action
  FHEM action to be carried out immediately after the arm event
• attr <name> armact action
  FHEM action to be carried out at the arm event after the delay time
• attr <name> disarmact action
  FHEM action to be carried out on the disarming of an alarm
• attr <name> cancelact action
  FHEM action to be carried out on the canceling of an alarm
• For each of the 8 alarm levels, several attributes hold the alarm setup. They should not be changed by hand, but through the web interface to avoid confusion: level<level>cond, level<level>start, level<level>end, level<level>autocan, level<level>msg, level<level>onact, level<level>offact
• Standard attributes alias, comment, event-on-update-reading, event-on-change-reading, room, eventMap, loglevel, webCmd

AndroidDB

The module allows to control an Android device by using the Android Debug Bridge (ADB). Before one can define an Android device, an AndroidDBHost I/O device must exist.

Dependencies: 89_AndroidDBHost

Define


define <name> AndroidDB <NameOrIP>[<Port>] The parameter NameOrIP is the hostname or the IP address of the Android device. The parameter Port specifies the TCP port to be used for the device connection. The default port is 5555.

Set

• set <Name> createRemote <Layout>
  Create a remote control device for the Android device. Create a notify device for the remote control to send button events to the AndroidDB device.
br/>
• set <Name> exportPresets <Filename>
  Export the currently loaded presets to file. This file can be modified and assigned again by using attribute 'preset'.


• set <name> reboot
  Reboot the device.


• set <name> remoteControl <MacroName>
  Send key codes associated with 'MacroName' to the Android device. Either attribute 'macros' or 'preset' must be set to make this command available. Macro names defined in attribute 'macros' are overwriting macros with the same name in a preset selected by attribute 'preset'.


• set <name> rollHorz <DeltaX>
  Scroll display horizontally. Not supported on all types of Android devices.


• set <name> rollVert <DeltaY>
  Scroll display vertically. Not supported on all types of Android devices.


• set <name> sendKey [longpress] <KeyCode> [...]
  Send a key code to the Android device. If option 'longpress' is specified, only one KeyCode is allowed.


• set <name> sendNumKeys <Number>
  Send digits of Number to the Android device. Number must be in range 0-9999.


• set <name> sendText <Text>
  Send Text to the Android device.


• set <name> shell <Command> [<Arguments>]
  Execute shell command on Android device.


• set <name> tap <X> <Y>
  Simulate a tap on a touchscreen (only available an devices having a touchscreen).

Get

• set <Name> keyPreset <PresetName>
  List key preset definition.
br/>
• set <Name> cmdPreset <PresetName>
  List command preset definition.
br/>

Attributes

• connect 0|1
  If set to 1, a connection to the Android device will be established during FHEM start. Note: Set this attribute for one Android device only!


• createReadings <command-expression>
  Create readings for shell command-expression. Output must contain lines in format key=value.
  Example: attr myDev createReadings dumpsys


• macros <MacroDef>[;...]
  Define a list of keycode macros to be sent to an Android device with 'remoteControl' command or define shortcuts for remote commands.
  A 'MacroDef' is using the following syntax:
  MacroName:KeyCode[,...]
  or
  MacroName:Command
  
  Parameter Command is a adb command.
  Example, define a command 'set listpackages':
  

  attr myDev macros listpackages:shell pm list packages -f

  
  Several macro definitions can be specified by seperating them using a semicolon.


• preset <PresetName>
  Select a preset of keycode macros.


• presetFile <Filename>
  Load a set of macros from a preset defintion file. If the same macro name is defined in the selected preset and in attribute 'macros', the definition in the 'macros' attribute overwrites the definition in the preset.
  A preset defintion file is using the following format:
  

          # Comment
          PresetName1
          MacroDef1
          MacroDef2
          ...
          PresetName2
          ...
          

  A 'MacroDef' is using the following syntax:
  MacroName:KeyCode[,...]
  or
  MacroName:Command:Parameters
  
  Usually Command is 'shell'.

AndroidDBHost

Provides I/O device for AndroidDB devices.

Dependencies: Perl module IPC::Open3, Android Platform Tools

Android DB Platform Tools installation:

• Debian/Raspbian: apt-get install android-sdk-platform-tools
• Windows/MacOSX/Linux x86: Android Developer Portal

Define


define <name> AndroidDBHost [server=<host>}[:<port>]] [adb=<path>]

The parameter 'host' is the hostname of the system, where the ADB server is running. Default is 'localhost'. Parameter 'adb' can be used to specify the path to the adb command (must include 'adb' or 'adb.exe').
Note: The adb command must be executable by the account under which FHEM is running.

Set

• set <name> command <Command> [<Args>]
  Execute ADB command.


• set <name> disconnectAll
  Disconnect all devices.


• set <name> start
  Start ADB server.


• set <name> stop
  Stop ADB server.

Get

• get <name> status
  Get status of ADB server.

Apt Update Information

AptToDate - Retrieves apt information about Debian update state state
With this module it is possible to read the apt update information from a Debian System.
It's required to insert "fhem ALL=NOPASSWD: /usr/bin/apt-get" via "visudo".

Define

define <name> AptToDate <HOST>

Example:

define fhemServer AptToDate localhost


This statement creates a AptToDate Device with the name fhemServer and the Host localhost.
After the device has been created the Modul is fetch all information about update state. This will need a moment.


Readings
• state - update status about the server
• os-release_ - all information from /etc/os-release
• repoSync - status about last repository sync.
• toUpgrade - status about last upgrade
• updatesAvailable - number of available updates


Set
• repoSync - fetch information about update state
• toUpgrade - to run update process. this will take a moment




Get
• showUpgradeList - list about available updates
• showUpdatedList - list about updated packages, from old version to new version
• showWarningList - list of all last warnings
• showErrorList - list of all last errors




Attributes
• disable - disables the device
• upgradeListReading - add Upgrade List Reading as JSON
• distupgrade - change upgrade prozess to dist-upgrade
• disabledForIntervals - disable device for interval time (13:00-18:30 or 13:00-18:30 22:00-23:00)

Air Quality Index

This modul fetch Air Quality data from http://aqicn.org.

Define

define <name> Aqicn token=<TOKEN-KEY>

Example:

define aqicnMaster Aqicn token=12345678


This statement creates the Aqicn Master Device.
After the device has been created, you can search Aqicn Station by city name and create automatically the station device.


Readings
• APL - Air Pollution Level
• AQI - Air Quality Index (AQI) of the dominant pollutant in city. Values are converted from µg/m³ to AQI level using US EPA standards. For more detailed information: https://en.wikipedia.org/wiki/Air_quality_index and https://www.airnow.gov/index.cfm?action=aqi_brochure.index.
• CO-AQI - AQI of CO (carbon monoxide). An AQI of 100 for carbon monoxide corresponds to a level of 9 parts per million (averaged over 8 hours).
• NO2-AQI - AQI of NO2 (nitrogen dioxide). See also https://www.airnow.gov/index.cfm?action=pubs.aqiguidenox
• PM10-AQI - AQI of PM10 (respirable particulate matter). For particles up to 10 micrometers in diameter: An AQI of 100 corresponds to 150 micrograms per cubic meter (averaged over 24 hours).
• PM2.5-AQI - AQI of PM2.5 (fine particulate matter). For particles up to 2.5 micrometers in diameter: An AQI of 100 corresponds to 35 micrograms per cubic meter (averaged over 24 hours).
• O3-AQI - AQI of O3 (ozone). An AQI of 100 for ozone corresponds to an ozone level of 0.075 parts per million (averaged over 8 hours). See also https://www.airnow.gov/index.cfm?action=pubs.aqiguideozone
• SO2-AQI - AQI of SO2 (sulfur dioxide). An AQI of 100 for sulfur dioxide corresponds to a level of 75 parts per billion (averaged over one hour).
• temperature - Temperature in degrees Celsius
• pressure - Atmospheric pressure in hectopascals (hPa)
• humidity - Relative humidity in percent
• state- Current AQI and air pollution level
• status - condition of the data
• pubDate- Local time of publishing the data
• pubUnixTime - Unix time stamp of local time but converted wrongly, if local time is e.g. 1300 GMT+1, the time stamp shows 1300 UTC.
• pubTimezone - Time zone of the city (UTC)
• windspeed - Wind speed in kilometer per hour
• windDirection - Wind direction
• dominatPoll - Dominant pollutant in city
• dewpoint - Dew in degrees Celsius
• healthImplications - Information about Health Implications
• htmlStyle - can be used to format the STATE and FHEMWEB (Example: stateFormate htmlStyle

get
• stationSearchByCity - search station by city name and open the result in seperate popup window
• update - fetch new data every x times

Attribute
• interval - interval in seconds for automatically fetch data (default 3600)

ArduCounter

This module implements an Interface to an Arduino, ESP8266 or ESP32 based counter for pulses on any input pin of an Arduino Uno, Nano, Jeenode, NodeMCU, Wemos D1, TTGO T-Display or similar device.
The device connects to Fhem either through USB / serial or via Wifi / TCP if an ESP board is used.
ArduCounter does not only count pulses but also measure pulse lenghts and the time between pulses so it can filter noise / bounces and gives better power/flow (Watts or liters/second) readings than systems that just count in fixed time intervals.
The number of pulses per kWh or liter is defineable and counters continue even when Fhem or the device restarts so you don't need additional user readings to make such calculations
The typical use case is an S0-Interface on an energy meter or water meter, but also reflection light barriers to monitor old ferraris counters or analog water meters are supported
Counters are configured with attributes that define which GPIO pins should count pulses and in which intervals the board should report the current counts.
The sketch that works with this module uses pin change interrupts so it can efficiently count pulses on all available input pins. The module has been tested with 14 inputs of an Arduino Uno counting in parallel and pulses as short as 3 milliseconds.
The module creates readings for pulse counts, consumption and optionally also a pin history with pulse lengths and gaps of the last pulses.
If an ESP8266 or ESP32 is used, the device can be flashed and configured over Wifi (it opens its own temporary Hotspot / SSID for configuration so you can set which existing SSID to connect to and which password to use). For TTGO T-Display boards (ESP32 with TFT display) the local display on the device itself can also display Wifi status and current consumption.

Prerequisites


• This module requires an Arduino Uno, Nano, Jeenode, NodeMCU, Wemos D1, TTGO T-Display or similar device based on an Atmel 328p, ESP8266 or ESP32 running the ArduCounter sketch provided with this module
  In order to flash an arduino board with the corresponding ArduCounter firmware from within Fhem, avrdude needs to be installed.
  To flash ESP32 or ESP8266 boards form within Fhem, Python and the scripts esptool.py / espota.py need to be installed.
  For old ferraris counters a reflection light barrier which in the simpest case can consist of a photo transistor (connected to an anlalog input of the Arduino / ESP) and an led or a laser module (connected to a digital output), both with a resistor in line are needed. To drive a laser module with 5V, another transistor is typically needed to switch 5V from a 3.3V GPIO output.

Define

define <name> ArduCounter <device>
or
define <name> ArduCounter <ip:port>

<device> specifies the serial port to communicate with the Arduino.
<ip:port> specifies the ip address and tcp port to communicate with an esp8266 / ESP32 where port is typically 80.
The name of the serial device depends on your distribution and serial adapter.
You can also specify a baudrate for serial connections if the device name contains the @ character, e.g.: /dev/ttyUSB0@115200
The default baudrate of the ArduCounter firmware is 115200 since sketch version 4 and used to be 38400 since sketch version 1.4
The latest version of this module will however try different baudrates automatically if communication with the counting device seems not possible.
Example:


define AC ArduCounter /dev/ttyUSB2@115200
define AC ArduCounter 192.168.1.134:80

Configuration of ArduCounter digital counters


Specify the pins where impulses should be counted e.g. as attr AC pinX falling pullup min 25
The X in pinX can be an Arduino / ESP GPIO pin number with or without the letter D e.g. pin4, pinD5, pin6, pinD7 ...
After the pin you can use the keywords falling or rising to define if a logical one / 5V (rising) or a logical zero / 0V (falling) should be treated as pulse.
The optional keyword pullup activates the pullup resistor for the given Pin.
The last argument is also optional but recommended and specifies a minimal pulse length in milliseconds.
An energy meter with S0 interface is typically connected to GND and an input pin like D4.
The S0 pulse then pulls the input down to 0V.
Since the minimal pulse lenght of an S0 interface is specified to be 30ms, the typical configuration for an s0 interface is
attr AC pinX falling pullup min 25
Specifying a minimal pulse length is recommended since it filters bouncing of reed contacts or other noise. The keyword min before 25 is optional.

Example:


        define AC ArduCounter /dev/ttyUSB2
        attr AC pulsesPerUnit 1000
        attr AC interval 60 300
        attr AC pinD4 falling pullup min 5
        attr AC pinD5 falling pullup min 25
        attr AC pinD6 rising
        

This defines a counter that is connected to Fhem via serial line ttyUSB2 with three counters connected to the GPIO pins D4, D5 and D5.
D4 and D5 have their pullup resistors activated and the impulses draw the pins to zero.
For D4 and D5 the board measures the time in milliseconds between the falling edge and the rising edge. If this time is longer than the specified 5 (or 25 for pin D5) milliseconds then the impulse is counted.
If the time is shorter then this impulse is regarded as noise and added to a separate reject counter.
For pin D6 the board uses a default minimal length of 2ms and counts every time when the signal changes from 1 (rising pulse) back to 0.

Configuration of ArduCounter analog counters


This module and the corresponding ArduCounter sketch can be used to read water meters or old analog ferraris energy counters.
Therefore a reflection light barrier needs to be connected to the board. This might simply consist of an infra red photo transistor (connected to an analog input) and an infra red led (connected to a digital output), both with a resistor in line. The idea comes from Martin Kompf (https://www.kompf.de/tech/emeir.html) and has been adopted for ArduCounter to support old ferraris energy counters or water meters.
The configuration is then similar to the one for digital counters:


        define WaterMeter ArduCounter 192.168.1.110:80
        attr ACF pinA0 rising pullup min 4 analog out 27 threshold 120,220
        attr ACF interval 5,60,2,15,10,3
        attr ACF pulsesPerUnit 35
        attr ACF stateFormat {sprintf("%.3f l/min", ReadingsVal($name,"powerA0",0))}
        

In this case an analog GPIO pin is used as input and the normal configuration parameters are followed by the keyword analog out or simply out, the gpio number of a GPIO output that connects a light source and the thresholds that decide when an analog input value is regarded as "low" or "high". In the example an ESP32 is used via Wifi connection. GPIO pin A0 is used as analog input and is connected to a photo transistor that senses the intensity of light. GPIO 27 is used as LED output and switched on/off in a high frequency. On GPIO A0 the reflected light is measured and the difference in a measurement between when the LED is off and when the LED is on is compared to the thresholds defined in the pinA0-attribute. When the measured light difference is above 220, then a pulse starts (since rising is specified). When the measured difference is below 120 then the pulse ends.

The attribute interval has the following meaning in the above example: The device reports the current counts and the time difference beween the first and the last pulse if at least 2 pulses have been counted and if they are more than 15 milliseconds apart form each other. If not, then the device continues counting. If after 60 seconds these conditions are stil not met, then the device will report the current count anyways and use the current time as the end of the interval.
The last two numbers of the interval attribute define that the device will read the analog input 3 times and then work with the average. Between each analog measurement series there will be a delay of 10 milliseconds.

The attribute pulsesPerUnit 35 defines that 35 pulses correspond to one unit (e.g. liter) and the reading calcCounterA0 is increased by the reported raw counts divided by 35.
To find out the right analog thresholds you can set the attribute enableHistory to 1 which will ask the firmware of your counting board to report the average difference measurements before they are compared to a threshold. The ArduCounter module will count how often each value is reported and you can then query these analog level counts with get levels. After a few measuremets the result of get levels might look like this:


            observed levels from analog input:
            94: 21
            95: 79
            96: 6
            97: 2
            98: 3
            99: 2
            100: 2
            101: 1
            102: 3
            105: 2
            106: 1
            108: 2
            109: 1
            110: 1
            112: 1
            113: 3
            115: 4
            116: 9
            117: 14
            118: 71
            119: 103
            120: 118
            121: 155
            122: 159
            123: 143
            124: 147
            125: 158
            126: 198
            127: 249
            128: 220
            129: 230
            130: 201
            131: 140
            132: 147
            133: 153
            134: 141
            135: 119
            136: 105
            137: 109
            138: 114
            139: 83
            140: 33
            141: 14
            142: 1      
        

This shows the measured values together with the frequency how often the individual value has been measured. It is obvious that most measurements result in values between 120 and 135, very few values are betweem 96 and 115 and another peak is around the value 95.
It means that in the example of a ferraris energy counter, when the red mark of the ferraris disc is under the sensor, the value is around 95 and while when the blank disc is under the sensor, the value is typically between 120 and 135. So a good upper threshold would be 120 and a good lower threshold would be for example 96.

Set-Commands

• raw
send the value to the board so you can directly talk to the sketch using its commands.
This is not needed for normal operation but might be useful sometimes for debugging
• flash [<file>]
flashes the ArduCounter firmware from the subdirectory FHEM/firmware onto the device.
Normally you can just specify set myDevice flash. The parameter <file> is optional and allows specifying an alternative firmware file. The attribute flashCommand can be used to override which command is executed. If the attribute flashCommand is not specified then the module selects an appropriate command depending on the board type (set with the attribute board) and depending on the connection (serial or Wifi).
For an arduino NANO for example the module would execute avrdude (which has to be installed of course) and flash the connected arduino with the updated hex file
(by default it looks for ArduCounter.hex in the FHEM/firmware subdirectory).
For an Arduino UNO for example the default is avrdude -p atmega328P -c arduino -P [PORT] -D -U flash:w:[HEXFILE] 2>[LOGFILE]
For an Arduino Nano based counter -b 57600 is added.
For an ESP32 connected via Wifi, the module would call espota.py which will upload the firmware over the air.
If the attribute flashCommand is not specified for an ESP32 based board connected via serial line, then the module uses the command esptool.py --chip esp32 --port [PORT] --baud 460800 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 FHEM/firmware/ArduCounter_ESP32_bootloader_dio_40m.bin 0x8000 FHEM/firmware/ArduCounter_ESP32_partitions.bin 0xe000 FHEM/firmware/ArduCounter_ESP32_boot_app0.bin 0x10000 FHEM/firmware/ArduCounter_ESP32_firmware.bin >[LOGFILE] 2>&1 for example which flashes the whole ESP32 with all the partitions.
For over the air flashing it would use espota.py -i[IP] -p [NETPORT] -f [BINFILE] 2>[LOGFILE].
Of course esptool.py or espota.py as well as python would need to be installed on the system.
• resetWifi
reset Wifi settings of the counting device so the Wifi Manager will come up after the next reset to select a wireless network and enter the Wifi passphrase.
• reset
sends a command to the device which causes a hardware reset or reinitialize and reset of the internal counters of the board.
The module then reopens the counting device and resends the attribute configuration / definition of the pins.
• saveConfig
stores the current interval, analog threshold and pin configuration in the EEPROM of the counter device so it will automatically be retrieved after a reset.
• enable
sets the attribute disable to 0
• disable
sets the attribute disable to 1
• reconnect
closes the tcp connection to an ESP based counter board that is conected via TCP/IP and reopen the connection
• clearLevels
clears the statistics for analog levels. This is only relevant if you use the board to read via a reflective light barrier and you want to set the thresholds according to the statistics.
• clearCounters <pin>
resets all the counter readings for the specified pin to 0
• counter <pin>, <value>
set the calcCounter reading for the specified pin to the given value
• clearHistory
deletes all the cached pin history entries

Get-Commands

• info
send a command to the Arduino board to get current counts.
This is not needed for normal operation but might be useful sometimes for debugging
• levels
show the count for the measured levels if an analog pin is used to measure e.g. the red mark of a ferraris counter disc. This is useful for setting the thresholds for analog measurements.
• history <pin>
shows details regarding all the level changes that the counter device (Arduino or ESP) has detected and how they were used (counted or rejected)
If get history is issued with a pin name (e.g. get history D5) then only the history entries concerning D5 will be shown.
This information is sent from the device to Fhem if the attribute enableHistory is set to 1.
The maximum number of lines that the Arducounter module stores in a ring buffer is defined by the attribute maxHist and defaults to 1000.

Attributes


• do_not_notify
• readingFnAttributes


• pin[AD]?[0-9]+<rising|falling> [<pullup>] [min] <min length> [[analog] out <out pin> [threshold] <min, max>]
  Define a GPIO pin of the Arduino or ESP board as input. This attribute expects for digital inputs either rising or falling, followed by an optional pullup and the optional keyword min and an optional number as minimal length of pulses and gaps between pulses.
  The counter device will track rising and falling edges of each impulse and measure the length of a pulse in milliseconds.
  The minimal length specified here is the minimal duration of a pulse and a pause before a pulse. If one is too small, the pulse is not counted but added to a separate reject counter.
  Example:
  

              attr MyCounter pinD4 falling pullup 25
              

  For analog inputs with connected reflective light barries, you have to add analog out and the GPIO pin number of the pin where the light source (LED or laser) is connected, the keyword threshold followed by the lower and upper threshold separated by a komma.
  Example:
  

              attr MyCounter pinA0 rising pullup min 3 analog out 27 threshold 120,220
              

• interval <normal> <max> [<min> <min count> [<analog interval> <analog samples>]]
  Defines the parameters that affect the way counting and reporting works. This Attribute expects at least two and a maximum of six numbers as value. The first is the normal interval, the second the maximal interval, the third is a minimal interval and the fourth is a minimal pulse count. The last two numbers are only needed for counting with reflective light barriers. They specify the delay between the measurements and the number of samples for each measurement.
  
  In the usual operation mode (when the normal interval is smaller than the maximum interval), the Arduino board just counts and remembers the time between the first impulse and the last impulse for each pin.
  After the normal interval is elapsed the Arduino board reports the count and time for those pins where impulses were encountered.
  This means that even though the normal interval might be 10 seconds, the reported time difference can be something different because it observed impulses as starting and ending point.
  The Power (e.g. for energy meters) is then calculated based of the counted impulses and the time between the first and the last impulse.
  For the next interval, the starting time will be the time of the last impulse in the previous reporting period and the time difference will be taken up to the last impulse before the reporting interval has elapsed.
  
  The second, third and fourth numbers (maximum, minimal interval and minimal count) exist for the special case when the pulse frequency is very low and the reporting time is comparatively short.
  For example if the normal interval (first number) is 60 seconds and the device counts only one impulse in 90 seconds, the the calculated power reading will jump up and down and will give ugly numbers.
  By adjusting the other numbers of this attribute this can be avoided.
  In case in the normal interval the observed impulses are encountered in a time difference that is smaller than the third number (minimal interval) or if the number of impulses counted is smaller than the fourth number (minimal count) then the reporting is delayed until the maximum interval has elapsed or the above conditions have changed after another normal interval.
  This way the counter will report a higher number of pulses counted and a larger time difference back to fhem.
  Example:
  

              attr myCounter interval 60 600 5 2
              

  
  If this is seems too complicated and you prefer a simple and constant reporting interval, then you can set the normal interval and the mximum interval to the same number. This changes the operation mode of the counter to just count during this normal and maximum interval and report the count. In this case the reported time difference is always the reporting interval and not the measured time between the real impulses.
  
  For analog sampling the last two numbers define the delay in milliseconds between analog measurements and the number of samples that will be taken as one mesurement.
• board
  specify the type of the board used for ArduCounter like NANO, UNO, ESP32, ESP8266 or T-Display
  Example:

              attr myCounter board NANO
              

• pulsesPerUnit <number>
  specify the number of pulses that the meter is giving out per unit that sould be displayed (e.g. per kWh energy consumed).
  For many S0 counters this is 1000, for old ferraris counters this is 75 (rounds per kWh).
  This attribute used to be called pulsesPerKWh and this name still works but the new name should be used preferably since the old one could be removed in future versions.
  Example:

              attr myCounter pulsesPerUnit 75
              

• readingPulsesPerUnit[AD]?[0-9]+ <number>
  is the same as pulsesPerUnit but specified per GPIO pin individually in case you have multiple counters with different settings at the same time
  This attribute used to be called readingPulsesPerKWh[AD]?[0-9]+ and this name still works but the new name should be used preferably since the old one could be removed in future versions.
  
  Example:
  

              attr myCounter readingPulsesPerUnitA7 75
  
              attr myCounter readingPulsesPerUnitD4 1000
              

• readingFlowUnitTime[AD]?[0-9]+ <time>
  specified the time period in seconds which is used as the basis for calculating the current flow or power for the given pin.
  If the counter e.g. counts liters and you want to see the flow in liters per minute, then you have to set this attribute to 60.
  If you count kWh and you want to see the current power in kW, then specify 3600 (one hour).
  Since this attribute is just used for multiplying the consumption per second, you can also use it to get watts instead of kW by using 3600000 instead of 3600.
• flowUnitTime <time>
  like readingFlowUnitTimeXX but applies to all pins that have no explicit readingFlowUnitTimeXX attribute.
• readingNameCount[AD]?[0-9]+ <new name>
  Change the name of the counter reading pinX to something more meaningful.
  Example:

              attr myCounter readingNameCountD4 CounterHaus_internal
              

• readingNameLongCount[AD]?[0-9]+ <new name>
  Change the name of the long counter reading longX to something more meaningful.
  Example:

              attr myCounter readingNameLongCountD4 CounterHaus_long
              

• readingNameInterpolatedCount[AD]?[0-9]+ <new name>
  Change the name of the interpolated long counter reading InterpolatedlongX to something more meaningful.
  Example:

              attr myCounter readingNameInterpolatedCountD4 CounterHaus_interpolated
              

• readingNameCalcCount[AD]?[0-9]+ <new name>
  Change the name of the real unit counter reading CalcCounterX to something more meaningful.
  Example:

              attr myCounter readingNameCalcCountD4 CounterHaus_kWh
              

• readingNamePower[AD]?[0-9]+ <new name>
  Change the name of the power reading powerX to something more meaningful.
  Example:

              attr myCounter readingNamePowerD4 PowerHaus_kW
              

• readingStartTime[AD]?[0-9]+ [0|1]
  Allow the reading time stamp to be set to the beginning of measuring intervals. This is a hack where the timestamp of readings is artificially set to a past time and may have side effects so avoid it unless you fully understand how Fhem works with readings and their time.
• verboseReadings[AD]?[0-9]+ [0|1]
  create the additional readings lastMsg and pinHistory for each pin
  if verboseReafings is set to 1 for the specified pin.
  If set to -1 then the internal counter, the long counter and interpolated long counter readings will be hidden.
  Example:

              attr myCounter verboseReadingsD4 1
              

• enableHistory [0|1]
  tells the counting device to record the individual time of each change at each GPIO pin and send it to Fhem. This information is cached on the Fhem side and can be viewed with the command get history The optput of get history will look like this:

                  Seq  12627 2020-03-22 20:39:54 Pin D5   0.080 seconds at 0 -> pulse counted
                  Seq  12628 2020-03-22 20:39:55 Pin D5   1.697 seconds at 1 -> gap
                  Seq  12629 2020-03-22 20:39:56 Pin D5   0.080 seconds at 0 -> pulse counted
                  Seq  12630 2020-03-22 20:39:56 Pin D5   1.694 seconds at 1 -> gap
                  Seq  12631 2020-03-22 20:39:58 Pin D5   0.081 seconds at 0 -> pulse counted
                  Seq  12632 2020-03-22 20:39:58 Pin D5   1.693 seconds at 1 -> gap
                  Seq  12633 2020-03-22 20:40:00 Pin D5   0.081 seconds at 0 -> pulse counted
                  Seq  12634 2020-03-22 20:40:00 Pin D5   1.696 seconds at 1 -> gap
                  Seq  12635 2020-03-22 20:40:02 Pin D5   0.081 seconds at 0 -> pulse counted
                  Seq  12636 2020-03-22 20:40:02 Pin D5   1.699 seconds at 1 -> gap
                  Seq  12637 2020-03-22 20:40:03 Pin D5   0.079 seconds at 0 -> pulse counted
                  Seq  12638 2020-03-22 20:40:03 Pin D5   1.700 seconds at 1 -> gap
                  Seq  12639 2020-03-22 20:40:05 Pin D5   0.080 seconds at 0 -> pulse counted
                  Seq  12642 2020-03-22 20:40:05 Pin D5   1.699 seconds at 1 -> gap
                  Seq  12643 2020-03-22 20:40:07 Pin D5   0.080 seconds at 0 -> pulse counted
                  Seq  12644 2020-03-22 20:40:07 Pin D5   1.698 seconds at 1 -> gap            
              

• enableSerialEcho [0|1]
  tells the counting device to show diagnostic data over the serial line when connected via TCP
• enablePinDebug [0|1]
  tells the counting device to show every level change of the defined input pins over the serial line or via TCP
• enableAnalogDebug [0|1]
  tells the counting device to show every analog measurement of the defined analog input pins over the serial line or via TCP
• enableDevTime [0|1]
  tells the counting device to show its internal millis timer so a drift between the devices time and fhem time can be calculated and logged
• maxHist <max entries>
  specifies how many pin history lines hould be buffered for "get history".
  This attribute defaults to 1000.
• analogThresholds
  this Attribute is outdated. Please specify the analog thresholds for reflective light barrier input with the attribute "pin..."
• flashCommand <new shell command>
  overrides the default command to flash the firmware via Wifi (OTA) or serial line. It is recommended to not define this attribute.
  Example:

              
              attr myCounter flashCommand avrdude -p atmega328P -c arduino -b 57600 -P [PORT] -D -U flash:w:[HEXFILE] 2>[LOGFILE]
              

  [PORT] is automatically replaced with the serial port for this device as it is specified in the define command.
  [HEXFILE] or [BINFILE] are synonyms and are both automatically replaced with the firmware file appropriate for the device. For ESP32 boards [HEXFILE] would be replaced by ArduCounter-8266.bin for example.
  [LOGFILE] is automatically replaced ArduCounterFlash.log in the fhem log subdirectory.
  [NETPORT] is automatically replaced by the tcp port number used for OTA flashing. For ESP32 this usually is 3232 and for 8266 Bords it is 8266.
  
• keepAliveDelay <delay>
  defines an interval in which the module sends keepalive messages to a counter device that is conected via tcp.
  This attribute is ignored if the device is connected via serial port.
  If the device doesn't reply within a defined timeout then the module closes and tries to reopen the connection.
  The module tells the device when to expect the next keepalive message and the device will also close the tcp connection if it doesn't see a keepalive message within the delay multiplied by 3
  The delay defaults to 10 seconds.
  Example:

              attr myCounter keepAliveDelay 30
              

• keepAliveTimeout <seconds>
  defines the timeout when wainting for a keealive reply (see keepAliveDelay) The timeout defaults to 2 seconds.
  Example:

              attr myCounter keepAliveTimeout 3
              

• keepAliveRetries <max number of retries>
  defines how often sending a keepalive is retried before the connection is closed and reopened.
  It defaults to 2.
  Example:

              attr myCounter keepAliveRetries 3
              

• nextOpenDelay <delay>
  defines the time in seconds that the module waits before retrying to open a disconnected tcp connection.
  This defaults to 60 seconds.
  Example:

              attr myCounter nextOpenDelay 20
              

• openTimeout <timeout>
  defines the timeout in seconds after which tcp open gives up trying to establish a connection to the counter device. This timeout defaults to 3 seconds.
  Example:

              attr myCounter openTimeout 5
              

• silentReconnect [0|1]
  if set to 1, then it will set the loglevel for "disconnected" and "reappeared" messages to 4 instead of 3
  Example:

              attr myCounter silentReconnect 1
              

• deviceDisplay <pin> <unit> <flowUnit>
  controls the unit strings that a local display on the counting device will show.
  Example:

              attr myCounter deviceDisplay 36,l,l/m
              attr myCounter deviceDisplay 36,kWh,kW
              

• disable [0|1]
  if set to 1 then the module is disabled and closes the connection to a counter device.
  
• factor
  Define a multiplicator for calculating the power from the impulse count and the time between the first and the last impulse.
  This attribute is outdated and unintuitive so you should avoid it.
  Instead you should specify the attribute pulsesPerUnit or readingPulsesPerUnit[0-9]+ (where [0-9]+ stands for the pin number).
• readingFactor[AD]?[0-9]+
  Override the factor attribute for this individual pin.
  Just like the attribute factor, this is a rather cumbersome way to specify the pulses per kWh.
  Instead it is advised to use the attribute pulsesPerUnit or readingPulsesPerUnit[0-9]+ (where [0-9]+ stands for the pin number).
• runTime[AD]?[0-9]+
  if this attribute is set for a pin, then a new reading will be created which accumulates the run time for this pin while consumption is greater than 0.
  This allows e.g. to check if a water meter shows water consumption for a time longer than X without stop.
• runTimeIgnore[AD]?[0-9]+
  this allows to ignore consumption for the run time attribute while a certain other device is switched on.
• devVerbose
  this attribute is outdated and has been replaced with the attributes enableHistory, enableSerialEcho, enablePinDebug, enableAnalogDebug, enableDevTime
• configDelay
  specify the time to wait for the board to report its configuration before Fhem sends the commands to reconfigure the board
• helloSendDelay
  specify the time to wait for the board to report its type before Fhem sends the commands to ask for it
• helloWaitTime
  specify the time to wait for the board to report its type when Fhem has asked for it before a timeout occurs

Readings / Events

The module creates at least the following readings and events for each defined pin:
• calcCounter.*
This is recommended reading for counting units based on the pulses and the attribute pulsesPerUnit. It is similar to interpolated long count which keeps on counting up after fhem restarts but this counter will take the pulses per Unit attribute into the calculation und thus does not count pulses but real Units (kWh, liters or some other unit that is applicable)
The name of this reading can be changed with the attribute readingNameCalcCount[AD]?[0-9]+ where [AD]?[0-9]+ stands for the pin description e.g. D4.
Another reading with the same name but ending in _i (e.g. calcCounterD4_i) will show how many kWh (or other units) of the above value is interpolated.
• pin.* e.g. pinD4
the current internal count at this pin (internal to the Arduino / ESP device, starts at 0 when the device restarts).
The name of this reading can be changed with the attribute readingNameCount[AD]?[0-9]+ where [AD]?[0-9]+ stands for the pin description e.g. D4
• long.* e.g. longD5
long count which keeps on counting up after fhem restarts whereas the pin.* count is only a temporary internal count that starts at 0 when the arduino board starts.
The name of this reading can be changed with the attribute readingNameLongCount[AD]?[0-9]+ where [AD]?[0-9]+ stands for the pin description e.g. D4
• interpolatedLong.*
like long.* but when the Arduino restarts the potentially missed pulses are interpolated based on the pulse rate before the restart and after the restart.
The name of this reading can be changed with the attribute readingNameInterpolatedCount[AD]?[0-9]+ where [AD]?[0-9]+ stands for the pin description e.g. D4
• reject.*
counts rejected pulses that are shorter than the specified minimal pulse length.
• power.*
the current calculated power / flow at this pin.
The name of this reading can be changed with the attribute readingNamePower[AD]?[0-9]+ where [AD]?[0-9]+ stands for the pin description e.g. D4.
This reading depends on the attributes pulsesPerUnit as well as readingFlowUnitTime or flowUnitTime for calculation
• pinHistory.*
shows detailed information of the last pulses. This is only available when a minimal pulse length is specified for this pin. Also the total number of impulses recorded here is limited to 20 for all pins together. The output looks like -36/7:0C, -29/7:1G, -22/8:0C, -14/7:1G, -7/7:0C, 0/7:1G
The first number is the relative time in milliseconds when the input level changed, followed by the length in milliseconds, the level and the internal action.
-36/7:0C for example means that 36 milliseconds before the reporting started, the input changed to 0V, stayed there for 7 milliseconds and this was counted.

• countDiff.*
delta of the current count to the last reported one. This is used together with timeDiff.* to calculate the power consumption.
• timeDiff.*
time difference between the first pulse in the current observation interval and the last one. Used togehter with countDiff to calculate the power consumption.
• seq.*
internal sequence number of the last report from the board to Fhem.
• runTime.*
this reading will only be created when the attribute runTime[AD]?[0-9]+ is set for a given pin.
It contains the time in seconds that the consumption / flow observed at the specified pin has not ben zero.
If a water meter which outputs 10 impulses per liter on its digital output is for example connected to GPIO pin D6, then if the attribute runTimeD6 is set to 1, the reading runTimeD6 will show for how many seconds the water has been flowing without a stop longer than the observation interval specifie in the interval-attribute. This is helpful when you want to create alerts in case someone forgot to close a water tap.

Arlo

Arlo security cams are connected to the Arlo Cloud via base stations. The base stations and cameras can be controlled with a REST API. Events (like movement and state changes) are delivery by server-sent events (SSE).

Define

define Arlo_Cloud Arlo ACCOUNT <hans.mustermann@xyz.de> <myArloPassword> <myEmailPassword> <myEmailUsername>

Please replace hans.mustermann@xyz.de by the e-mail address you have registered at Arlo and myArloPassword by the password used there. For the 2 factor authentication you also have to set the password of the email account. The email server which receives the Arlo mails has to be set with attr Arlo_Cloud mailServer imap.gmx.net, where imap.gmx.net has to be replaced by the IMAP server of your mail provider. Only IMAP with encryption is supported. You can skip the parameter myEmailUsername if the username matches the email address.

After you have successfully created the account definition, you can call set Arlo_Cloud autocreate. Now the base station(s) and cameras which are assigned to the Arlo account will be created in FHEM. All new devices are created in the room Arlo.

In the background there is a permanent SSE connection to the Arlo server. If you temporary don't use Arlo in FHEM, you can stop this SSE connection by setting the attribute "disable" at the Arlo_Cloud device to 1.

Set

• autocreate (subtype ACCOUNT)
  Reads all devices which are assigned to the Arlo account and creates FHEM devices, if the devices don't exist in FHEM.
• reconnect (subtype ACCOUNT)
  Connect or reconnect to the Arlo server. First FHEM logs in, then a SSE connection is established. This method is only used if the connection to the Arlo server was interrupted.
• readModes (subtype ACCOUNT)
  Reads the modes of the base stations (iincl. custom modes). Is called automatically, normally you don't have to call this manually.
• updateReadings (subtype ACCOUNT)
  The data of all base stations and cameras are retrieved from the Arlo cloud. This is done every hour automatically, if you don't set the attribute disable=1 at the Cloud device. The interval can be changed by setting the attribute updateInterval (in seconds, e.g. 600 for 10 minutes, 7200 for 2 hours).
• arm (subtype BASESTATION, BRIDGE, ARLOQ and BABYCAM)
  Activates the motion detection.
• disarm (subtype BASESTATION, BRIDGE, ARLOQ and BABYCAM)
  Deactivates the motion detection.
• mode (subtype BASESTATION and BRIDGE)
  Set a custom mode (parameter: name of the mode).
• siren (subtype BASESTATION)
  Activates or deactivates the siren of the base station (attention: the siren is loud!).
• subscribe (subtype BASESTATION, ARLOQ and BABYCAM)
  Subscribe base station for the SSE connection. Normally you don't have to do this manually, this is done automatically after login.
• unsubscribe (subtype BASESTATION, ARLOQ and BABYCAM)
  Unsubscribe base station for the current SSE connection.
• brightness (subtype CAMERA, ARLOQ and BABYCAM)
  Adjust brightness of the camera (possible values: -2 to +2).
• on (Subtype CAMERA)
  Switch on camera (deactivate privacy mode).
• off (subtype CAMERA)
  Switch off camera (activate privacy mode).
• snapshot (subtype CAMERA, ARLOQ and BABYCAM)
  Take a snapshot. The snapshot url is written to the reading snapshotUrl. This command only works if the camera has the state on.
• startRecording (subtype CAMERA, ARLOQ and BABYCAM)
  Start recording. This command only works if the camera has the state on.
• stopRecording (subtype CAMERA, ARLOQ and BABYCAM)
  Stops an active recording. The recording url is stored in the reading lastVideoUrl, a frame of the recording in lastVideoImageUrl and a thumbnail of the recording in lastVideoThumbnailUrl.
• nightlight (Subtype BABYCAM)
  Switch nightlight on or off.
• nightlight-brightness (Subtype BABYCAM)
  Set brightness of nightlight.
• nightlight-color (Subtype BABYCAM)
  Set color of nightlight.

Attributes

Common attributes:
DbLogInclude
DbLogExclude
alias
comment
devStateIcon
devStateStyle
event-aggregator
event-min-interval
event-on-change-reading
event-on-update-reading
eventMap
group
icon
room
sortby
stateFormat
userReadings
userattr
verbose
webCmd
widgetOverride



downloadDir

If this attribute is set at the cloud device (subtype ACCOUNT), the files which are stored at the Arlo Cloud (videos / images) will also be downloaded to the given directory. If you want to access these files via FHEM http you have to use a subdirectory of /opt/fhem/www. Attention: the fhem user has to have write access to the directory.

downloadLink

If the attribute downloadDir is set and the files will be downloaded from Arlo Cloud, you can set this attribute to create a correct URL to the last video, last snapshot and so on. A correct value is like http://hostname:8083/fhem/subdirectory-of-www

disable

Subtype ACCOUNT: Deactivates the SSE connection to Arlo Cloud.

Subtype BASESTATION: Deactivates the periodic update of the readings from Arlo Cloud.

expiryTime

Subtype ACCOUNT: If all base stations have the status "disarmed" the connection to the cloud will be closed after this time. A new connection will be established if needed. Unit is seconds, default 600 (10 minutes). If you set the value to 0 the connection will not be closed.

mailServer

Subtype ACCOUNT: Name of the IMAP mail server which receives the Arlo 2FA code mail. The passwort for the mail server has to be set in the define of Arlo_Cloud device.

videoDownloadFix

Subtype ACCOUNT: Set this attribute to 1 if videos are not downloaded automatically. Normally the server sents a notification when there is a new video available but sometimes this doesn't work. Default is 0.

pingInterval

Subtype ACCOUNT: Set the interval in seconds for the heartbeat-ping. Without a heartbeat-ping the session in Arlo Cloud would expire and FHEM wouldn't receive any more events. Default is 90.

updateInterval

Subtype ACCOUNT: Set the interval in seconds how often the readings of base statations and cameras will be updated. Default is 3600 = 1 hour.

ssePollingInterval

Subtype ACCOUNT: Set the interval in seconds how often the SSE events are checked. Default is 2 seconds.

Astro

FHEM module with a collection of various routines for astronomical data

Define

define <name> Astro [global]
Defines the Astro device (only one is needed per FHEM installation).
Optional parameter 'global' will mark this device for global configuration options, see SUNRISE_EL compatibility mode below for details.

Readings with prefix Sun refer to the sun, with prefix Moon refer to the moon. The suffixes for these readings are:

• Age = angle (in degrees) of body along its track
• Az,Alt = azimuth and altitude angle (in degrees) of body above horizon
• Dec,Ra = declination (in degrees) and right ascension (in HH:MM) of body position
• HrsVisible,HrsInvisible = Hours of visiblity and invisiblity of the body
• Lat,Lon = latitude and longituds (in degrees) of body position
• Diameter = virtual diameter (in arc minutes) of body
• Distance,DistanceObserver = distance (in km) of body to center of earth or to observer
• PhaseN,PhaseS = Numerical and string value for phase of body
• Sign,SignN = Circadian sign for body along its track
• Rise,Transit,Set = times (in HH:MM) for rise and set as well as for highest position of body

Readings with prefix Obs refer to the observer. In addition to some of the suffixes gives above, the following may occur:

• Date,Dayofyear = date
• JD = Julian date
• Time,Timezone,TimezoneS = obvious meaning
• IsDST = 1 if running on daylight savings time, 0 otherwise
• GMST,LMST = Greenwich and Local Mean Sidereal Time (in HH:MM)

An SVG image of the current moon phase may be obtained under the link <ip address of fhem>/fhem/Astro_moonwidget?name='<device name>'. Optional web parameters are [&size='<width>x<height>'][&mooncolor=<color>][&moonshadow=<color>]

Notes:

• Calculations are only valid between the years 1900 and 2100
• Attention: Timezone is taken from the local Perl settings, NOT automatically defined for a location
• This module uses the global attribute language to determine its output data
  (default: EN=english). For German output, set attr global language DE.
  If a local attribute on the device was set for language it will take precedence.
• The time zone is determined automatically from the local settings of the
  operating system. If geocordinates from a different time zone are used, the results are
  not corrected automatically.
• Some definitions determining the observer position are used
  from the global device, i.e.
  
  attr global longitude <value>
attr global latitude <value>
attr global altitude <value> (in m above sea level)
  These definitions are only used when there are no corresponding local attribute settings on the device.
• It is not necessary to define an Astro device to use the data provided by this module.
  To use its data in any other module, you just need to put LoadModule("Astro");
  at the start of your own code, and then may call, for example, the function
  
  Astro_Get( SOME_HASH_REFERENCE,"dummy","text", "SunRise","2019-12-24");
  to acquire the sunrise on Christmas Eve 2019. The hash reference may also be undefined or an existing device name of any type. Note that device attributes of the respective device will be respected as long as their name matches those mentioned for an Astro device. attribute=value pairs may be added in text format to enforce settings like language that would otherwise be defined by a real device.
  You may also add parameters to customize your request:
  
  Astro_Get( SOME_HASH_REFERENCE, ["dummy","text"], {html=>1} );
Astro_Get( SOME_HASH_REFERENCE, ["dummy","text","SunRise,SunSet,SunAz,SunDistanceObserver"], {html=>1, long=>2} );
• Functions that can replace those from SUNRISE_EL are available under the same name and adding a as a prefix in front of it (for example, use asunrise() instead of sunrise()). A single Astro device can act as a global configuration device for such functions if it was created using the global define parameter. If you don't want to create any Astro device at all, you may put LoadModule("Astro"); into your 99_myUtils.pm to only load the SUNRISE_EL replacement functions.

Set

• set <name> update
  trigger to recompute values immediately.

Get

Attention: Get-calls are NOT written into the readings of the device. Readings change only through periodic updates.

• get <name> json [<reading>,[<reading>]] [-1|yesterday|+1|tomorrow]
get <name> json [<reading>,[<reading>]] MM-DD [-1|yesterday|+1|tomorrow]
get <name> json [<reading>,[<reading>]] YYYY-MM-DD [-1|yesterday|+1|tomorrow]
get <name> json [<reading>,[<reading>]] HH:MM[:SS] [-1|yesterday|+1|tomorrow]
get <name> json [<reading>,[<reading>]] YYYY-MM-DD HH:MM[:SS] [-1|yesterday|+1|tomorrow]
  returns the complete set of an individual reading of astronomical data either for the current time, or for a day and time given in the argument. yesterday, tomorrow or any other integer number may be given at the end to get data relative to the given day and time.
  Formatted values as described below may be generated in a subtree text by adding text=1 to the request.
• get <name> text [<reading>,[<reading>]] [-1|yesterday|+1|tomorrow]
get <name> text [<reading>,[<reading>]] MM-DD [-1|yesterday|+1|tomorrow]
get <name> text [<reading>,[<reading>]] YYYY-MM-DD [-1|yesterday|+1|tomorrow]
get <name> text [<reading>,[<reading>]] HH:MM[:SS] [-1|yesterday|+1|tomorrow]
get <name> text [<reading>,[<reading>]] YYYY-MM-DD HH:MM[:SS] [-1|yesterday|+1|tomorrow]
  returns the complete set of an individual reading of astronomical data either for the current time, or for a day and time given in the argument. yesterday, tomorrow or any other integer number may be given at the end to get data relative to the given day and time.
  The return value may be formatted and/or labeled by adding one or more of the following key=value pairs to the request:
  • unit=1 = Will add a unit to numerical values. Depending on attribute lc_numeric, the decimal separator will be in regional format as well.
  • long=1 = A describtive label will be added to the value.
  • long=2 = Same as long=1 but the label will be separated from the value by a colon.
  • long=3 = Same as long=2 but Sun or Moon will be added as a prefix.
  • long=4 = Same as long=3 but the separator will be used to separate Sun/Moon instead.
• get <name> version
  Display the version of the module

Attributes

• <interval>
  Update interval in seconds. The default is 3600 seconds, a value of 0 disables the periodic update.
• <language>
  A language may be set to overwrite global attribute settings.
• <lc_numeric>
  Set regional settings to format numerical values in textual output. If not set, it will generate the locale based on the attribute language (if set).
• <lc_time>
  Set regional settings to format time related values in textual output. If not set, it will generate the locale based on the attribute language (if set).
• <recomputeAt>
  Enforce recomputing values at specific event times, independant from update interval. This attribute contains a list of one or many of the following values:
  
  • MoonRise,MoonSet,MoonTransit = for moon rise, set, and transit
  • NewDay = for 00:00:00 hours of the next calendar day
  • SunRise,SunSet,SunTransit = for sun rise, set, and transit
  • *TwilightEvening,*TwilightMorning = for the respective twilight stage begin
• <timezone>
  A timezone may be set to overwrite global and system settings. Format may depend on your local system implementation but is likely in the format similar to Europe/Berlin.
• Some definitions determining the observer position:
  
  attr <name> longitude <value>
attr <name> latitude <value>
attr <name> altitude <value> (in m above sea level)
  attr <name> horizon <value> custom horizon angle in degrees, default 0. Different values for morning/evening may be set as <morning>:<evening>
  These definitions take precedence over global attribute settings.
• <disable>
  When set, this will completely disable any device update.
• Standard attributes alias, comment, event-on-update-reading, event-on-change-reading, room, eventMap, loglevel, webCmd

Aurora

Define
define <name> Aurora <ip> [<interval>]

Defines a device connected to a Aurora.

The device status will be updated every <interval> seconds. 0 means no updates. Groups are updated only on definition and statusRequest

Examples:
define aurora Aurora 10.0.1.xxx 10


Readings
• colormode
  the current colormode
• ct
  the colortemperature in mireds and kelvin
• hue
  the current hue
• pct
  the current brightness in percent
• onoff
  the current on/off state as 0 or 1
• sat
  the current saturation
• state
  the current state

Notes:
• not all readings show the actual device state. all readings not related to the current colormode have to be ignored.



Set
• on [<ramp-time>]
• off [<ramp-time>]
• toggle [<ramp-time>]
• statusRequest
  Request device status update.
• pct <value> [<ramp-time>]
  dim to <value>
  Note: the FS20 compatible dimXX% commands are also accepted.
• color <value>
  set colortemperature to <value> kelvin.
• dimUp [delta]
• dimDown [delta]
• ct <value> [<ramp-time>]
  set colortemperature to <value> in mireds (range is 154-500) or kelvin (rankge is 2000-6493).
• ctUp [delta]
• ctDown [delta]
• hue <value> [<ramp-time>]
  set hue to <value>; range is 0-65535.
• humUp [delta]
• humDown [delta]
• sat <value> [<ramp-time>]
  set saturation to <value>; range is 0-254.
• satUp [delta]
• satDown [delta]
• effect <name>
• previousEffect
• nextEffect
• rgb <rrggbb>
  set the color to (the nearest equivalent of) <rrggbb>


• set extensions are supported.

Note:
• <ramp-time> is given in seconds
• multiple paramters can be set at once separated by :
  Examples:
  set LC on : transitiontime 100
set bulb on : pct 100 : color 4000
  

Get
• rgb
• RGB
• devStateIcon
  returns html code that can be used to create an icon that represents the device color in the room overview.

Attributes
• color-icon
  1 -> use lamp color as icon color and 100% shape as icon shape
  2 -> use lamp color scaled to full brightness as icon color and dim state as icon shape
• transitiontime
  default transitiontime for all set commands if not specified directly in the set.
• delayedUpdate
  1 -> the update of the device status after a set command will be delayed for 1 second. usefull if multiple devices will be switched.
• devStateIcon
  will be initialized to {(Aurora_devStateIcon($name),"toggle")} to show device color as default in room overview.
• webCmd
  will be initialized to a device specific value

AutoShuttersControl

AutoShuttersControl (ASC) provides a complete automation for shutters with comprehensive configuration options, e.g. open or close shutters depending on the sunrise or sunset, by outdoor brightness or randomly for simulate presence.
So that ASC can drive the blinds on the basis of the astronomical times, it is very important to correctly set the location (latitude, longitude) in the device "global".

After telling ASC which shutters should be controlled, several in-depth configuration options are provided. With these and in combination with a resident presence state, complex scenarios are possible: For example, shutters could be opened if a resident awakes from sleep and the sun is already rosen. Or if a closed window with shutters down is tilted, the shutters could be half opened for ventilation. Many more is possible.

Define

define <name> AutoShuttersControl

Usage:
define myASControl AutoShuttersControl


This creates an new AutoShuttersControl device, called myASControl.
Now was the new global attribute ASC added to the FHEM installation. Each shutter that is to be controlled by AutoShuttersControl must now have the attribute ASC set to 1 or 2. The value 1 is to be used with devices whose state is given as position (i.e. ROLLO or Siro, shutters openend is 0, shutters closed is 100), 2 with devices whose state is given as percent closed (i.e. HomeMatic, shutters opened is 100, closed is 0).

After setting the attributes to all devices who should be controlled, the automatic scan at the main device can be started for example with
set myASControl scanForShutters


Readings

Within the ASC device:

• ..._nextAstroTimeEvent - Next astro event: sunrise, sunset or fixed time
• ..._PosValue - current position
• ..._lastPosValue - shutters last position
• ..._lastDelayPosValue - last specified order, will be executed with the next matching event
• partyMode on|off - is working mode set to part?y
• ascEnable on|off - are the associated shutters control by ASC completely?
• controlShading on|off - are the associated shutters controlled for shading by ASC?
• hardLockOut on|off - switch for preventing a global hard lock out
• room_... - list of every found shutter for every room: room_Sleeping: Patio
• selfDefense - state of the self defense mode
• state - state of the ASC device: active, enabled, disabled or other state information
• sunriseTimeWeHoliday on|off - state of the weekend and holiday support
• userAttrList - ASC sets some user defined attributes (userattr) for the shutter devices. This readings shows the current state of the given user attributes to the shutter devices.

Within the shutter devices:

• ASC_Enable on|off - shutter is controlled by ASC or not
• ASC_Time_DriveUp - if the astro mode is used, the next sunrise is shown. If the brightness or time mode is used, the value from ASC_Time_Up_Late is shown.
• ASC_Time_DriveDown - if the astro mode is used, the next sunset is shown. If the brightness or time mode is used, the value from ASC_TASC_Time_Down_Late is shown.
• ASC_ShuttersLastDrive - initiator for the last action


Set
• advDriveDown - execute all moves delayed by ASC_Adv on.
• ascEnable on|off - enable or disable the global control by ASC
• controlShading on|off - enable or disable the global shading control by ASC
• createNewNotifyDev - re-creates the internal structure for NOTIFYDEV. Is only present if the ASC_Expert attribute is set to 1.
• hardLockOut on|off -
• hardLockOut - on/off - Aktiviert den hardwareseitigen Aussperrschutz für die Rollläden, bei denen das Attributs ASC_LockOut entsprechend auf hard gesetzt ist. Mehr Informationen in der Beschreibung bei den Attributen für die Rollladengeräten.
• partyMode on|off - controls the global party mode for shutters. Every shutters whose ASC_Partymode attribute is set to on, is not longer controlled by ASC. The last saved working command send to the device, i.e. by a event, created by a window or presence event, will be executed once the party mode is disabled.
• renewTimer - resets the sunrise and sunset timers for selected shutter device and creates new internal FHEM timers.
• renewAllTimer - resets the sunrise and sunset timers for all shutter device and creates new internal FHEM timers.
• scanForShutters - scans the whole FHEM installation for (new) devices whose ASC attribute is set (to 1 or 2, see above).
• selfDefense on|off - controls the self defense function. This function listens for example on a residents device. If this device is set to absent and a window is still open, ASC will close the shutter for a rudimentary burglary protection.
• shutterASCenableToggle on|off - controls if the ASC controls are shown at a associated shutter device.
• sunriseTimeWeHoliday on|off - controls the weekend and holiday support. If enabled, the ASC_Time_Up_WE_Holiday attribute is considered.
• wiggle - wiggles a device for a given value (default 5%, controlled by ASC_WiggleValue) up or down and back after a minute. Useful as a deterrence in combination with alarm system.


Get
• showNotifyDevsInformations - shows the generated NOTIFYDEV structure. Useful for debugging and only shown if the ASC_expert attribute is set to 1.


Attributes

At the global ASC device:

• ASC_autoAstroModeEvening - REAL, CIVIL, NAUTIC, ASTRONOMIC or HORIZON
• ASC_autoAstroModeEveningHorizon - Height above the horizon. Is only considered if the ASC_autoAstroModeEvening attribute is set to HORIZON. Defaults to 0.
• ASC_autoAstroModeMorning - REAL, CIVIL, NAUTIC, ASTRONOMIC or HORIZON
• ASC_autoAstroModeMorningHorizon - Height above the horizon. Is only considered if the ASC_autoAstroModeMorning attribute is set to HORIZON. Defaults to 0.
• ASC_autoShuttersControlComfort - on|off - Controls the comfort functions: If a three state sensor, like the HmIP-SRH window handle sensor, is installed, ASC will open the window if the sensor signals open position. The ASC_ComfortOpen_Pos attribute has to be set for the shutter to on, defaults to off.
• ASC_autoShuttersControlEvening - on|off - Enables the automatic control by ASC at the evenings.
• ASC_autoShuttersControlMorning - on|off - Enables the automatic control by ASC at the mornings.
• ASC_blockAscDrivesAfterManual 0|1 - If set to 1, ASC will not automatically control a shutter if there was an manual control to the shutter. To be considered, the ASC_ShuttersLastDrive reading has to contain the value manual and the shutter is in an unknown (i.e. not otherwise configured in ASC) position.
• ASC_brightnessDriveUpDown - VALUE-MORNING:VALUE-EVENING - Drive the shutters by brightness. VALUE-MORNING sets the brightness threshold for the morning. If the value is reached in the morning, the shutter will go up. Vice versa in the evening. This is a global setting and can be overwritte per device with the ASC_BrightnessSensor attribute (see below).
• ASC_debug - Extendend logging for debugging purposes
• ASC_expert - Switches the export mode on. Currently, if set to 1, get and set will contain additional functions regarding the NOTIFYDEFs.
• ASC_freezeTemp - Temperature threshold for the freeze protection. The freeze protection prevents the shutter to be operated by ASC. Last operating order will be kept.
• ASC_advStartDate - Begin of Advent Season, selected FirstAdvent or DeadSunday.
• ASC_advEndDate - End of Advent Season, selected CandlemasDay 6. January or EpiphanyDay 2. February.
• ASC_rainSensor DEVICENAME[:READINGNAME] MAXTRIGGER[:HYSTERESE] [CLOSEDPOS] - Contains settings for the rain protection. DEVICNAME specifies a rain sensor, the optional READINGNAME the name of the reading at the DEVICENAME. The READINGNAME should contain the values rain and dry or a numeral rain amount. MAXTRIGGER sets the threshold for the amount of rain for when the shutter is driven to CLOSEDPOS as soon the threshold is reached. HYSTERESE sets a hysteresis for MAXTRIGGER.
• ASC_residentsDev DEVICENAME[:READINGNAME] - DEVICENAME points to a device for presence, e.g. of type RESIDENTS. READINGNAME points to a reading at DEVICENAME which contains a presence state, e.g. rgr_Residents:state. The target should contain values alike the RESIDENTS family.
• ASC_GuestRoom on|off - (not functionality implemented yet?).
• ASC_shuttersDriveDelay - Maximum random drive delay in seconds for calculating the operating time. 0 equals to no delay.
• ASC_TempSensor DEVICENAME[:READINGNAME] - DEVICENAME points to a device with a temperature, READINGNAME to a reading located at the DEVICENAME, for example OUTDOOR_TEMP:measured-temp. READINGNAME defaults to temperature.
• ASC_twilightDevice - points to a DEVICENAME containing values regarding the sun position. Supports currently devices of type Twilight or Astro.
• ASC_windSensor DEVICENAME[:READINGNAME] - DEVICENAME points to a device containing a wind speed. Reads from the wind reading, if not otherwise specified by READINGNAME.



At shutter devices, controlled by ASC:

• ASC - 0|1|2
  • 0 - don't create attributes for ASC at the first scan and don't be controlled by ASC
  • 1 - inverse or venetian type blind mode. Shutter is open equals to 0, shutter is closed equals to 100, is controlled by position values.
  • 2 - HomeMatic mode. Shutter is open equals to 100, shutter is closed equals to 0, is controlled by pct values.
• ASC_Antifreeze - soft|am|pm|hard|off - Freeze protection.
  • soft - see ASC_Antifreeze_Pos.
  • hard / am / pm - freeze protection will be active (everytime, ante meridiem or post meridiem).
  • off - freeze protection is disabled, default value
• ASC_Antifreeze_Pos - Position to be operated if the shutter should be closed, but ASC_Antifreeze is not set to off. (Default: dependent on attributASC 85/15).
• ASC_AutoAstroModeEvening - Can be set to REAL, CIVIL, NAUTIC, ASTRONOMIC or HORIZON. Defaults to none of those.
• ASC_AutoAstroModeEveningHorizon - If this value is reached by the sun, a sunset is presumed. Is used if ASC_autoAstroModeEvening is set to HORIZON. Defaults to none.
• ASC_AutoAstroModeMorning - Can be set to REAL, CIVIL, NAUTIC, ASTRONOMIC or HORIZON. Defaults to none of those.
• ASC_AutoAstroModeMorningHorizon - If this value is reached by the sun, a sunrise is presumed. Is used if ASC_AutoAstroModeMorning is set to HORIZON. Defaults to none.
• ASC_Shutter_IdleDetection - indicates the Reading which gives information about the running status of the roller blind, as well as secondly the value in the Reading which says that the roller blind does not run.
• ASC_BlockingTime_afterManual - Time in which operations by ASC are blocked after the last manual operation in seconds. Defaults to 1200 (20 minutes).
• ASC_BlockingTime_beforDayOpen - Time in which no closing operation is made by ASC after opening at the morning in seconds. Defaults to 3600 (one hour).
• ASC_BlockingTime_beforNightClose - Time in which no closing operation is made by ASC before closing at the evening in seconds. Defaults to 3600 (one hour).
• ASC_BrightnessSensor - DEVICE[:READING] MORNING-VALUE:EVENING-VALUE - Drive this shutter by brightness. MORNING-VALUE sets the brightness threshold for the morning. If the value is reached in the morning, the shutter will go up. Vice versa in the evening, specified by EVENING-VALUE. Gets the brightness from DEVICE, reads by default from the brightness reading, unless READING is specified. Defaults to none.
• ASC_Closed_Pos - The closed position value from 0 to 100 percent in increments of 10. (Default: dependent on attributASC 100/0).
• ASC_ComfortOpen_Pos - The comfort opening position, ranging from 0 to 100 percent in increments of 10. (Default: dependent on attributASC 20/80).
• ASC_Down - astro|time|brightness|roommate - Drive the shutter depending on this setting:
  • astro - drive down at sunset
  • time - drive at ASC_Time_Down_Early
  • brightness - drive between ASC_Time_Down_Early and ASC_Time_Down_Late, depending on the settings of ASC_BrightnessSensor (see above).
  • roommate - no drive by time or brightness, roommate trigger only
  Defaults to astro.
• ASC_DriveUpMaxDuration - Drive up duration of the shutter plus 5 seconds. Defaults to 60 seconds if not set.
• ASC_Drive_Delay - maximum value for a random delay (in seconds) to add to the calculated drive times. (needs also ASC_Drive_DelayStart to be set!)
• ASC_Drive_DelayStart - delay in seconds to add to each calculated drive time.
• ASC_LockOut soft|hard|off - Configures the lock out protection for the current shutter. Values are:
  • soft - works if the global lock out protection lockOut soft is set and a sensor specified by ASC_WindowRec is set. If the sensor is set to open, the shutter will not be closed. Affects only commands issued by ASC.
  • hard - see soft, but ASC tries also to block manual issued commands by a switch.
  • off - lock out protection is disabled. Default.
• ASC_LockOut_Cmd inhibit|blocked|protection - Configures the lock out command for ASC_LockOut if hard is chosen as a value. Defaults to none.
• ASC_Mode_Down always|home|absent|off - When will a shutter be driven down:
  • always - ASC will drive always. Default value.
  • off - don't drive
  • home / absent - considers a residents status set by ASC_residentsDev. If no resident is configured and this attribute is set to absent, ASC will not operate the shutter.
• ASC_Mode_Up always|home|absent|off - When will a shutter be driven up:
  • always - ASC will drive always. Default value.
  • off - don't drive
  • home / absent - considers a residents status set by ASC_residentsDev. If no resident is configured and this attribute is set to absent, ASC will not operate the shutter.
• ASC_Open_Pos - The opening position value from 0 to 100 percent in increments of 10. (Default: dependent on attributASC 0/100).
• ASC_Sleep_Pos - The opening position value from 0 to 100 percent in increments of 10. (Default: dependent on attributASC 75/25).
• ASC_Partymode on|off - Party mode. If configured to on, driving orders for the shutter by ASC will be queued if partyMode is set to on at the global ASC device. Will execute the driving orders after partyMode is disabled. Defaults to off.
• ASC_Pos_Reading - Points to the reading name, which contains the current position for the shutter in percent. Will be used for set at devices of unknown kind.
• ASC_PrivacyDownValue_beforeNightClose - How many seconds is the privacy mode activated before the shutter is closed in the evening. For Brightness, in addition to the time value, the Brightness value must also be specified. 1800:300 means 30 min before night close or above a brightness value of 300. -1 is the default value.
• ASC_PrivacyDown_Pos - Position in percent for privacy mode, defaults to 50.
• ASC_PrivacyUpValue_beforeDayOpen - How many seconds is the privacy mode activated before the shutter is open in the morning. For Brightness, in addition to the time value, the Brightness value must also be specified. 1800:600 means 30 min before day open or above a brightness value of 600. -1 is the default value.
• ASC_PrivacyUp_Pos - Position in percent for privacy mode, defaults to 50.
• ASC_ExternalTrigger - DEVICE:READING VALUEACTIVE:VALUEINACTIVE POSACTIVE:[POSINACTIVE VALUEACTIVE2:POSACTIVE2], example: setting to "WohnzimmerTV:state on:off 66:100" will cause a "state:on" event to drive the shutter to position 66. "state:off" event will set it to position 100. If no POSINACTIVE is set, LastStatus position will be used as target position.
• ASC_WindProtection on|off - Shutter is protected by the wind protection. Defaults to off.
• ASC_RainProtection on|off - Shutter is protected by the rain protection. Defaults to off.
• ASC_Roommate_Device - Comma separated list of ROOMMATE devices, representing the inhabitants of the room to which the shutter belongs. Especially useful for bedrooms. Defaults to none.
• ASC_Roommate_Reading - Specifies a reading name to ASC_Roommate_Device. Defaults to state.
• ASC_GuestRoom on|off - (not functionality implemented yet?).
• ASC_Adv - on/off If on, from 1. advent to 6. January all closing commands will be delayed until set ASCDEVICE advDriveDown is issued.
• ASC_Self_Defense_Mode - absent/gone/off - which Residents status Self Defense should become active without the window being open. (default: gone) off exclude from self defense
• ASC_Self_Defense_AbsentDelay - time in seconds to wait after Residents went gone. (default: 300)
• ASC_ShuttersPlace window|terrace - If set to terrace, and the residents device is set to gone, and selfDefense is activated, the shutter will be closed. If set to window, will not. Defaults to window.
• ASC_Time_Down_Early - Will not drive before time is ASC_Time_Down_Early or later, even the sunset occurs earlier. To be set in military time. Defaults to 16:00.
• ASC_Time_Down_Late - Will not drive after time is ASC_Time_Down_Late or earlier, even the sunset occurs later. To be set in military time. Defaults to 22:00.
• ASC_Time_Up_Early - Will not drive before time is ASC_Time_Up_Early or earlier, even the sunrise occurs earlier. To be set in military time. Defaults to 05:00.
• ASC_Time_Up_Late - Will not drive after time is ASC_Time_Up_Late or earlier, even the sunrise occurs later. To be set in military time. Defaults to 08:30.
• ASC_Time_Up_WE_Holiday - Will not drive before time is ASC_Time_Up_WE_Holiday on weekends and holidays (holiday2we is considered). Defaults to 08:00. Warning! If ASC_Up set to brightness, the time for ASC_Time_Up_WE_Holiday must be earlier then ASC_Time_Up_Late.
• ASC_Up astro|time|brightness|roommate - Drive the shutter depending on this setting:
  • astro - drive up at sunrise
  • time - drive at ASC_Time_Up_Early
  • brightness - drive between ASC_Time_Up_Early and ASC_Time_Up_Late, depending on the settings of ASC_BrightnessSensor (see above).
  • roommate - no drive by time or brightness, roommate trigger only
  Defaults to astro.
• ASC_Ventilate_Pos - The opening position value for ventilation from 0 to 100 percent in increments of 10. (Default: dependent on attributASC 70/30).
• ASC_Ventilate_Window_Open on|off - Drive to ventilation position as window is opened or tilted, even when the current shutter position is lower than the ASC_Ventilate_Pos. Defaults to on.
• ASC_WiggleValue - How many percent should the shutter be driven if a wiggle drive is operated. Defaults to 5.
• ASC_WindParameters THRESHOLD-ON[:THRESHOLD-OFF] [DRIVEPOSITION] - Threshold for when the shutter is driven to the wind protection position. Optional THRESHOLD-OFF sets the complementary value when the wind protection is disabled. Disabled if THRESHOLD-ON is set to -1. Defaults to 50:20 ASC_Closed_Pos.
• ASC_WindowRec - WINDOWREC:[READING], Points to the window contact device, associated with the shutter. Defaults to none. Reading is optional
• ASC_WindowRec_subType - Model type of the used ASC_WindowRec:
  • twostate - optical or magnetical sensors with two states: opened or closed
  • threestate - sensors with three states: opened, tilted, closed
  Defaults to twostate.
• ASC_SlatPosCmd_SlatDevice - If your shutter is "venetian blind" type (with turnable slats, lamellas or similar), this is the place to set additional command and/or device info to control the slat level. Examples: attr ROLLO ASC_SlatPosCmd_SlatDevice slatPct or attr ROLLO ASC_SlatPosCmd_SlatDevice dim:ROLLOSLATDEVICE. Providing a device name for the slat device is only needed in case it's different to the shutter itself. If attribute is set, additional positioning values for the respective slat levels can be set in attributes ASC_Open_Pos, ASC_Closed_Pos, ASC_Ventilate_Pos, ASC_ComfortOpen_Pos, ASC_Shading_Pos and ASC_Sleep_Pos.
• ASC_CommandTemplate - FHEM or Perl command (Perl in braces as usual needs escaping semicolons etc.).
  This optional attribute will override the internally determined command to drive this shutter. Setting it, is only recommended in some rare and special cases,, in most cases there's no need to set this attribute! The parameters $name (name of the shutter device), $pos (target position for the respective drive command), $slatPos (target position for the (turnable) lammellas in venetion blinds) and $cause (internal label for the cause of the driving command) will be replaced by the appropirate values. You may have to take care to avoid unneeded driving commands. Examples:
  • attr ROLLO ASC_CommandTemplate set $name $pos - Address the position command directly to the main switch of the device
  • attr ROLLO ASC_CommandTemplate set $name pct $pos - Address the setter pct for positioning commands
  • attr ROLLO ASC_CommandTemplate set $name datapoint 4.LEVEL_2 $slatPos 4.LEVEL $pos - combined positioning command, e.g. appropriate for HM-IP-venetian blind type actors
  • attr ROLLO ASC_CommandTemplate { fhem("set $name ".($pos+1024)).";set $name 0")} - positioning command with Perl calculation and additional "execute" command, e.g. for an SPS type blind
  • attr ROLLO ASC_CommandTemplate { myPerlFn("$name",$pos,$slatPos,"$cause")} - call own Perl function (e.g. from 99_myUtils.pm)
• ASC_WindowRec_PosAfterDayClosed - open,lastManual / auf welche Position soll das Rollo nach dem schließen am Tag fahren. Open Position oder letzte gespeicherte manuelle Position (default: open)

Shading

Shading is only available if the following prerequests are met:

• The controlShading reading is set to on, and there is a device of type Astro or Twilight configured to ASC_twilightDevice, and ASC_TempSensor is set.
• ASC_BrightnessSensor is configured to any shutter device.
• All other attributes are optional and the default value for them is used, if they are not otherwise configured. Please review the settings carefully, especially the values for StateChange_Cloudy and StateChange_Sunny.

The following attributes are available:

• ASC_Shading_InOutAzimuth - Azimuth value from which shading is to be used when shading is exceeded and shading when undershooting is required. Defaults to 95:265.
• ASC_Shading_MinMax_Elevation - Shading starts as min point of sun elevation is reached and end as max point of sun elevation is reached, depending also on other sensor values. Defaults to 25.0:100.0.
• ASC_Shading_Min_OutsideTemperature - Shading starts at this outdoor temperature, depending also on other sensor values. Defaults to 18.0.
• ASC_Shading_Mode absent|always|off|home - see ASC_Mode_Down above, but for shading. Defaults to off.
• ASC_Shading_Pos - Shading position in percent. (Default: dependent on attribute ASC 85/15)
• ASC_Shading_StateChange_Cloudy - Shading ends at this outdoor brightness, depending also on other sensor values. Defaults to 20000.
• ASC_Shading_StateChange_SunnyCloudy - Shading starts/stops at this outdoor brightness, depending also on other sensor values. An optional parameter specifies how many successive brightness reading values should be used to average the brightness value. Defaults to 35000:20000 [3].
• ASC_Shading_WaitingPeriod - Waiting time in seconds before additional sensor values to ASC_Shading_StateChange_Sunny or ASC_Shading_StateChange_Cloudy are used for shading. Defaults to 120.
• ASC_Shading_BetweenTheTime - Limit the time slots for shading functionality. Example: 09:00-13:00 11:25-15:30

AutoShuttersControl API description

It's possible to access internal data of the ASC module by calling the API function.

Data points of a shutter device, controlled by ASC

{ ascAPIget('Getter','SHUTTERS_DEVICENAME') }

Getter	Description
FreezeStatus	1 = soft, 2 = daytime, 3 = hard
NoDelay	Was the offset handling deactivated (e.g. by operations triggered by a window event)
LastDrive	Reason for the last action caused by ASC
LastPos	Last position of the shutter
LastPosTimestamp	Timestamp of the last position
LastManPos	Last position manually set of the shutter
LastManPosTimestamp	Timestamp of the last position manually set
SunsetUnixTime	Calculated sunset time in seconds since the UNIX epoche
Sunset	1 = operation in the evening was made, 0 = operation in the evening was not yet made
SunriseUnixTime	Calculated sunrise time in seconds since the UNIX epoche
Sunrise	1 = operation in the morning was made, 0 = operation in the morning was not yet made
RoommatesStatus	Current state of the room mate set for this shutter
RoommatesLastStatus	Last state of the room mate set for this shutter
ShadingStatus	Value of the current shading state. Can hold in, out, in reserved or out reserved
ShadingStatusTimestamp	Timestamp of the last shading state
IfInShading	Is the shutter currently in shading (depends on the shading mode)
WindProtectionStatus	Current state of the wind protection. Can hold protection or unprotection
RainProtectionStatus	Current state of the rain protection. Can hold protection or unprotection
DelayCmd	Last operation order in the waiting queue. Set for example by the party mode
Status	Position of the shutter
ASCenable	Does ASC control the shutter?
PrivacyDownStatus	Is the shutter currently in privacyDown mode
outTemp	Current temperature of a configured temperature device, return -100 is no device configured

Übersicht für das Rollladen-Device mit Parameterübergabe
{ ascAPIget('Getter','ROLLODEVICENAME',VALUE) }


Getter	Erläuterung
QueryShuttersPos	Rückgabewert 1 bedeutet das die aktuelle Position des Rollos unterhalb der Valueposition ist. 0 oder nichts bedeutet oberhalb der Valueposition.

Data points of the ASC device

{ ascAPIget('Getter') }


Getter	Description
OutTemp	Current temperature of a configured temperature device, return -100 is no device configured
ResidentsStatus	Current state of a configured resident device
ResidentsLastStatus	Last state of a configured resident device
Azimuth	Current azimuth of the sun
Elevation	Current elevation of the sun
ASCenable	Is ASC globally activated?

AutomowerConnect

FHEM-FORUM: AutomowerConnect
FHEM-Wiki: AutomowerConnect: Wie erstellt man eine Karte des Mähbereiches?

Introduction


• This module allows the communication between the Husqvarna Cloud and FHEM to control Husqvarna Automower equipped with a Connect Module (SIM).
• It acts as Device for one mower. Use this Module for aditional mower registered in the API. Provide a different application key and application secret each mower
• The mower path is shown in the detail view.
• An arbitrary map can be used as background for the mower path.
• The map has to be a raster image in webp, png or jpg format.
• The property limits can be registered manually.
• The mowing area limits can be registered manually.
• The mowing area limits can be calculated, alternatively.
• It's possible to control everything the API offers, e.g. schedule, headlight, cutting height and actions like start, pause, park etc.
• Zones are definable.
• Cutting height can be set for each zone differently.
• All API data is stored in the device hash. Use {Dumper $defs{<name>}} in the commandline to find the data and build userReadings out of it.


Requirements


• To get access to the API an application has to be created in the Husqvarna Developer Portal. The application has to be connected with the AutomowerConnect API.
• During registration an application key (client_id) and an application secret (client secret) is provided. Use these for the module.
• The module uses client credentials as grant type for authorization.


• The module downloads third party software from external server necessary to calculate the hull of mowing area.



Define
define <device name> AutomowerConnect <application key> [<mower number>]
Example:
define myMower AutomowerConnect 123456789012345678901234567890123456 First device: the default mower number is 0.
It has to be set a client_secret. It's the application secret from the Husqvarna Developer Portal.
set myMower <client secret>



Hints
• The available setter, attributes, Readings and and the map depend on the mower capabilities ( cutting height, headlights, position, stay out zones, work areas ).


Button
• Mower Schedule
  The Button Mower Schedule opens GUI to maintain the mower schedule..
  Add/change entry: fill out the schedule fields and press ±.
  Delete entry: unselect each weekday and press ±.
  Reset entry: fill any time field with -- and press ±.
Set
• Park
  set <name> Park <number of minutes>
  Parks mower in charging station for <number of minutes>
• ParkUntilFurtherNotice
  set <name> ParkUntilFurtherNotice
  Parks mower in charging station until further notice
• ParkUntilNextSchedule
  set <name> ParkUntilNextSchedule
  Parks mower in charging station and starts with next planned start
• Pause
  set <name> Pause
  Pauses mower immediately at current position
• ResumeSchedule
  set <name> ResumeSchedule
  Starts immediately if in planned intervall, otherwise with next scheduled start>
• Start
  set <name> Start <number of minutes>
  Starts immediately for <number of minutes>
• dateTime
  set <name> dateTime <timestamp / s>
  Syncronize the mower time to timestamp. The default (empty Input field) timestamp is for local time of the machine the mower is defined, see also mowerAutoSyncTime.
• confirmError
  set <name> confirmError
  Testing: Confirm current error on the mower. Will only work if current error is considered confirmable by the mower. Available for models 405X, 415X, 435X AWD and 535 AWD. Also available on all Ceora, EPOS and NERA models.
• StartInWorkArea
  set <name> StartInWorkArea <workAreaId|name> [<number of minutes>]
  Testing: Starts immediately in <workAreaId|name> for <number of minutes>.
  If <number of minutes> is empty or 0 is selected in the widget the mower will continue forever.
  Work area name must not include space.
• chargingStationPositionToAttribute
  set <name> chargingStationPositionToAttribute
  Sets the calculated charging station coordinates to the corresponding attributes.
• client_secret
  set <name> client_secret <application secret>
  Sets the mandatory application secret (client secret)
• cuttingHeight
  set <name> cuttingHeight <1..9>
  Sets the cutting height. NOTE: Do not use for 550 EPOS and Ceora.
• resetCuttingBladeUsageTime
  set <name> resetCuttingBladeUsageTime
  Resets the cutting blade usage time if the mower provides it.
• cuttingHeightInWorkArea
  set <name> cuttingHeightInWorkArea <Id|name> <0..100>
  Testing: Sets the cutting height for Id or zone name from 0 to 100. Zone name must not include space and contain at least one alphabetic character.
• stayOutZone
  set <name> stayOutZone <Id|name> <enable|disable>
  Testing: Enables or disables stay out zone by Id or zone name. Zone name must not include space and contain at least one alphabetic character.
• getNewAccessToken
  set <name> getNewAccessToken
  For debug purpose only.
• getUpdate
  set <name> getUpdate
  For debug purpose only.
• 
  get <name> getMessages
  Gets messages from mower if supported, see also errorStack.
• headlight
  set <name> headlight <ALWAYS_OFF|ALWAYS_ON|EVENIG_ONLY|EVENING_AND_NIGHT>
  
• mowerScheduleToAttribute
  set <name> mowerScheduleToAttribute
  Writes the schedule in to the attribute moverSchedule.
• sendScheduleFromAttributeToMower
  set <name> sendScheduleFromAttributeToMower
  Sends the schedule to the mower. NOTE: Do not use for 550 EPOS and Ceora.
• mapZonesTemplateToAttribute
  set <name> mapZonesTemplateToAttribute
  Load the command reference example into the attribute mapZones.
• defaultDesignAttributesToAttribute
  set <name> defaultDesignAttributesToAttribute
  Load default design attributes.




Get
• html
  get <name> html
  Returns the mower area image as html code. For use in uiTable, TabletUI, Floorplan, readingsGroup, weblink etc.
• InternalData
  get <name> InternalData
  Lists some device internal data
• MowerData
  get <name> MowerData
  Lists all mower data with its hash path exept positon array. The hash path can be used for generating userReadings. The trigger is e.g. device_state: connected or mower_wsEvent: <status-event|positions-event|settings-event>.
  Example: created reading serialnumber with hash path $hash->{helper}{mower}{attributes}{system}{serialNumber}

attr <name> userReadings serialnumber:connected {$defs{$name}->{helper}{mower}{attributes}{system}{serialNumber}}
• StatisticsData
  get <name> StatisticsData
  Lists statistics data with its hash path. The hash path can be used for generating userReadings. The trigger is e.g. device_state: connected or mower_wsEvent: <status-event|positions-event|settings-event>.
• errorCodes
  get <name> errorCodes
  Lists API response status codes and mower error codes
• errorStack
  get <name> errorStack
  Lists error stack and messages, see also getMessages.



Attributes
• mapImagePath
  attr <name> mapImagePath <path to image>
  Path of a raster image file for an area the mower path has to be drawn to.
  If the image name implies the image size by containing a part which matches /(\d+)x(\d+)/
  the corresponding attribute will be set to mapImageWidthHeight = '$1 $2'
  Image name example: map740x1300.webp
• mapImageWidthHeight
  attr <name> mapImageWidthHeight <width in pixel><separator><height in pixel>
  Width and Height in pixel of a raster image file for an area image the mower path has to be drawn to. <separator> is one space character.
• mapImageZoom
  attr <name> mapImageZoom <zoom factor>
  Zoom of a raster image for an area the mower path has to be drawn to.
• mapBackgroundColor
  attr <name> mapBackgroundColor <background-color>
  The value is used as background-color.
• mapDesignAttributes
  attr <name> mapDesignAttributes <complete list of design-attributes>
  Load the list of attributes by set <name> defaultDesignAttributesToAttribute to change its values. Design attributes with changed default values are mandatory in this attribute.
  Default values:
  areaLimitsColor="#ff8000"
areaLimitsLineWidth="1"
areaLimitsConnector=""
hullColor="#0066ff"
hullLineWidth="1"
hullConnector="1"
hullResolution="40"
hullCalculate="1"
hullSubtract=""
propertyLimitsColor="#33cc33"
propertyLimitsLineWidth="1"
propertyLimitsConnector="1"
errorBackgroundColor="#3d3d3d"
errorFont="14px Courier New"
errorFontColor="#ff8000"
errorPathLineColor="#ff00bf"
errorPathLineDash=""
errorPathLineWidth="2"
chargingStationPathLineColor="#999999"
chargingStationPathLineDash="6,2"
chargingStationPathLineWidth="1"
chargingStationPathDotWidth="2"
otherActivityPathLineColor="#999999"
otherActivityPathLineDash="6,2"
otherActivityPathLineWidth="1"
otherActivityPathDotWidth="2"
leavingPathLineColor="#33cc33"
leavingPathLineDash="6,2"
leavingPathLineWidth="1"
leavingPathDotWidth="2"
goingHomePathLineColor="#0099ff"
goingHomePathLineDash="6,2"
goingHomePathLineWidth="1"
goingHomePathDotWidth="2"
mowingPathDisplayStart=""
mowingPathLineColor="#ff0000"
mowingPathLineDash="6,2"
mowingPathLineWidth="1"
mowingPathDotWidth="2"
mowingPathUseDots=""
mowingPathShowCollisions=""
hideSchedulerButton=""
• mapImageCoordinatesToRegister
  attr <name> mapImageCoordinatesToRegister <upper left longitude><space><upper left latitude><line feed><lower right longitude><space><lower right latitude>
  Upper left and lower right coordinates to register (or to fit to earth) the image. Format: linewise longitude and latitude values separated by 1 space.
  The lines are splitted by (/\s|\R$/). Use WGS84 (GPS) coordinates in decimal degree notation.
• mapImageCoordinatesUTM
  attr <name> mapImageCoordinatesUTM <upper left longitude><space><upper left latitude><line feed><lower right longitude><space><lower right latitude>
  Upper left and lower right coordinates to register (or to fit to earth) the image. Format: linewise longitude and latitude values separated by 1 space.
  The lines are splitted by (/\s|\R$/). Use UTM coordinates in meter notation.
  This attribute has to be set after the attribute mapImageCoordinatesToRegister. The values are used to calculate the scale factors and the attribute scaleToMeterXY is set accordingly.
• showMap
  attr <name> showMap <1,0>
  Shows Map on (1 default) or not (0).
• mowerAutoSyncTime
  attr <name> mowerAutoSyncTime <0,1>
  Synchronizes mower time if DST changes, on (1) or not (0 default).
• chargingStationCoordinates
  attr <name> chargingStationCoordinates <longitude><separator><latitude>
  Longitude and latitude of the charging station. Use WGS84 (GPS) coordinates in decimal degree notation. <separator> is one space character
• chargingStationImagePosition
  attr <name> chargingStationImagePosition <right, bottom, left, top, center>
  Position of the charging station image relative to its coordinates.
• mowerCuttingWidth
  attr <name> mowerCuttingWidth <cutting width>
  mower cutting width in meter to calculate the mowed area. default: 0.24
• mowerSchedule
  attr <name> mowerSchedule <schedule array>
  This attribute provides the possebility to edit the mower schedule in form of an JSON array.
  The actual schedule can be loaded with the command set <name> mowerScheduleToAttribute.
  The command set <name> sendScheduleFromAttributeToMower sends the schedule to the mower. The maximum of array elements is 14 and 2 each day, so every day of a week can have 2 time spans. Each array element consists of 7 day values (monday to sunday) which can be true or false, a start and duration value in minutes. Start time counts from midnight. NOTE: Do not use for 550 EPOS and Ceora. Delete the attribute after the schedule is successfully uploaded.
• mowingAreaLimits
  attr <name> mowingAreaLimits <positions list>
  List of position describing the area to mow. Format: linewise longitude and latitude values separated by 1 space. The lines are splitted by (/\s|\R$/).
  The position values could be taken from Google Earth KML file, but whithout the altitude values.
• propertyLimits
  attr <name> propertyLimits <positions list>
  List of position describing the property limits. Format: linewise of longitude and latitude values separated by 1 space. The lines are splitted by (/\s|\R$/).The position values could be taken from . For converting UTM32 meter to ETRS89 / WGS84 decimal degree you can use the BKG-Geodatenzentrum BKG-Geodatenzentrum.
• numberOfWayPointsToDisplay
  attr <name> numberOfWayPointsToDisplay <number of way points>
  Set the number of way points stored and displayed, default is 5000 at least 100. The way points are shifted through the dedicated stack.
• weekdaysToResetWayPoints
  attr <name> weekdaysToResetWayPoints <any combination of weekday numbers, space or minus [0123456 -]>
  A combination of weekday numbers when the way point stack will be reset. No reset for space or minus. Default 1.
• scaleToMeterXY
  attr <name> scaleToMeterXY <scale factor longitude><seperator><scale factor latitude>
  The scale factor depends from the Location on earth, so it has to be calculated for short ranges only. <seperator> is one space character.
  Longitude: (LongitudeMeter_1 - LongitudeMeter_2) / (LongitudeDegree_1 - LongitudeDegree _2)
  Latitude: (LatitudeMeter_1 - LatitudeMeter_2) / (LatitudeDegree_1 - LatitudeDegree _2)
• mapZones
  attr <name> mapZones <valid perl condition to separate Zones>
  These Zones are provided by the Modul and are not related to Husqvarnas work areas.
  Provide the zones with conditions as JSON-String:
  The waypoints are accessable by the variables $longitude und $latitude.
  Zones have have to be separated by conditions in alphabetical order of their names.
  The last zone is determined by the remaining waypoints.
  Syntactical example:
  '{
    "<name_1>" : {
      "condition" : "<condition to separate name_1 from other zones>",
      "cuttingHeight" : "<cutting height for the first zone>"
  },
    "<name_2>" : {
      "condition" : "<condition to separate name_2 from other zones, except name_1>",
      "cuttingHeight" : "<cutting height for the second zone>"
  },
    "<name_3>" : {
      "condition" : "<condition to separate name_3 from other zones, except name_1 and name_2>",
      "cuttingHeight" : "<cutting height for the third zone>"
  },
    "<name_n-1>" : {
      "condition" : "<condition to separate name_n-1 from other zones ,except the zones already seperated>",
      "cuttingHeight" : "<cutting height for the nth-1 zone>"
  },
    "<name n>" : {
      "condition" : "Use 'undef' because the last zone remains.",
      "cuttingHeight" : "<cutting height for the nth zone>"
  }
}'

  Example with two Zones and virtual lines defined by latitude 52.6484600648553, 52.64839739580418 (horizontal) and longitude 9.54799477359984 (vertikal). all way points above 52.6484600648553 or all way points above 52.64839739580418 and all way points to the right of 9.54799477359984 belong to zone 01_oben. All other way points belong to zone 02_unten.
  There are different cutting heightts each zone '{
    "01_oben" : {
      "condition" : "$latitude > 52.6484600648553 || $longitude > 9.54799477359984 && $latitude > 52.64839739580418",
      "cuttingHeight" : "7"
  },
    "02_unten" : {
      "condition" : "undef",
      "cuttingHeight" : "3"
  }
}'

• addPollingMinInterval
  attr <name> addPollingMinInterval <interval in seconds>
  Set minimum intervall for additional polling triggered by status-event, default 0 (no polling). Gets periodically statistics data from mower. Make sure to be within API limits (10000 calls per month).
• addPositionPolling
  attr <name> addPositionPolling <[1|0]>
  Set position polling, default 0 (no position polling). Gets periodically position data from mower, instead from websocket. It has no effect without setting attribute addPollingMinInterval.
• mowingAreaHull
  attr <name> mowingAreaHull <use button 'mowingAreaHullToAttribute' to fill the attribute>
  Contains the calculated hull coordinates as JSON string and is set by button 'mowingAreaHullToAttribute' under the dislpayed map.
  The stored hull polygon is displayed like the other limits.
  Use the design attribute 'hullResolution' to change the number of fractions ℕ
  . The hull polygon is calculated when the design attribut is set to 1 hullCalculate="1" and there are more than 50 Points for activity MOWING.
  The calculation is done only after site reload.
  The calculation of hull is stopped when the attribute ist set and starts again when attribute is deleted.
  The attribute weekdaysToResetWayPoints should be set to - and also the design attribute mowingPathUseDots should be set to "1" until the hull is sufficient. If there is a polygon in attribute, it can be changed.
  The design attribute hullSubtract can be set to a natural number {ℕ}, it depicts the recursion depth in which polygon points removed from way points.
  This reduces spikes in border region.
  hullSubtract="" removes the button 'Subtract Hull'.
  
• mowerPanel
  attr <name> mowerPanel <html code>
  Shows user defined html beneath the map. usefull for a panel with shortcuts
  The command attribute has to contain the mower command, without set <name>
  command="Start 210" stands for set <name> Start 210
  A directive as comment in the first line allows positioning.
  
  • <!-- ON_TOP --> shows html above map
  Panel has to be enclosed by a div-tag with a mandatory HTML-attribute data-amc_panel_inroom=<"1"|"">. Panel is shown in room view, i.e. for uiTable, weblink, etc., for value "1" and hidden for value "" look at example.
  Example:
  <style>
.amc_panel_button {height:50px; width:150px;}
.amc_panel_div {position:relative; left:348px; top:-330px; z-index: 2; width:150px; height:1px}
</style>
<div class="amc_panel_div" data-amc_panel_inroom="1" >
<button class="amc_panel_button" command="Start 210" >Start für 3 1/2 h</button>
<button class="amc_panel_button" command="Pause" >Pause bis auf Weiteres</button>
<button class="amc_panel_button" command="ResumeSchedule" >Weiter nach Plan</button>
<button class="amc_panel_button" command="ParkUntilNextSchedule" >Parken bis nächsten Termin</button>
<button class="amc_panel_button" command="ParkUntilNextSchedule" >Parken bis auf Weiteres</button>
</div>

• disable
• disabledForIntervals




userattr

The following user attributes are taken into account.

• loglevelDevIo
  attr <name> loglevelDevIo <[012345]>
  Set internal deviologlevel, DevIo: Wichtige_Internals_zur_Konfiguration
• timeoutGetMower
  attr <name> timeoutGetMower <[6 to 60]>
  Set timeout for API call, default 5 s.
• timeoutApiAuth
  attr <name> timeoutApiAuth <[6 to 60]>
  Set timeout for API call, default 5 s.
• timeoutCMD
  attr <name> timeoutCMD <[6 to 60]>
  Set timeout for API call, default 5 s.

The response time is meassured and logged if a timeout ist set to 60 s.
• testing
  attr <name> testing 1
  Enables commands taged as Testing




additional Events
A List of Events generated besides readings events.

• <device name>:AUTHENTICATION ERROR Error during Authentification.
• <device name>:MOWERAPI ERROR Error while Connecting AutomowerConnect API.
• <device name>:WEBSOCKET ERROR Error related to websocket connection.

Readings
• api_MowerFound - all mower registered under the application key (client_id)
• api_callsThisMonth - counts monthly API calls, if attribute addPollingMinInterval is set.
• api_token_expires - date when session of Husqvarna Cloud expires
• batteryPercent - battery state of charge in percent
• mower_activity - current activity "UNKNOWN" | "NOT_APPLICABLE" | "MOWING" | "GOING_HOME" | "CHARGING" | "LEAVING" | "PARKED_IN_CS" | "STOPPED_IN_GARDEN"
• mower_commandSend - Last successfull sent command
• mower_commandStatus - Status of the last sent command cleared each status update
• mower_currentZone - Zone name with activity MOWING in the last status time stamp interval and number of way points in parenthesis.
• mower_inactiveReason - They are NONE, PLANNING, SEARCHING_FOR_SATELLITES.
• mower_wsEvent - websocket connection events (status-event, positions-event, settings-event)
• mower_errorCode - last error code
• mower_errorCodeTimestamp - last error code time stamp
• mower_errorDescription - error description
• mower_mode - current working mode "MAIN_AREA" | "SECONDARY_AREA" | "HOME" | "DEMO" | "UNKNOWN"
• mower_state - current status "UNKNOWN" | "NOT_APPLICABLE" | "PAUSED" | "IN_OPERATION" | "WAIT_UPDATING" | "WAIT_POWER_UP" | "RESTRICTED" | "OFF" | "STOPPED" | "ERROR" | "FATAL_ERROR" |"ERROR_AT_POWER_UP"
• planner_nextStart - next start time
• planner_restrictedReason - reason for parking NOT_APPLICABLE, NONE, WEEK_SCHEDULE, PARK_OVERRIDE, SENSOR, DAILY_LIMIT, FOTA, FROST
• planner_overrideAction - reason for override a planned action NOT_ACTIVE, FORCE_PARK, FORCE_MOW
• state - state of websocket connection
• device_state - status of connection FHEM to Husqvarna Cloud API and device state(e.g. defined, authorization, authorized, connected, error, update)
• settings_cuttingHeight - actual cutting height from API
• settings_headlight - actual headlight mode from API
• statistics_newGeoDataSets - number of new data sets between the last two different time stamps
• statistics_numberOfCollisions - Number of collisions (current day/last day/all days)
• status_connected - state of connetion between mower and Husqvarna Cloud.
• status_statusTimestamp - local time of last status update
• status_statusTimestampDiff - time difference in seconds between the last and second last status update
• system_name - name of the mower
• third_party_library - notice about downloaded JS library. Deleting the reading has no side effects.

BDKM

BDKM is a module supporting Buderus Logamatic KM gateways similar to the km200 module. For installation of the gateway see fhem km200 internet wiki
Compared with the km200 module the code of the BDKM module is more compact and has some extra features. It has the ablility to define how often a gateway ID is polled, which FHEM reading (alias) is generated for a gateway ID and which minimum difference to the last reading must exist to generate a new reading (see attributes).
It determines value ranges, allowed values and writeability from the gateway supporting FHEMWEB and readingsGroup when setting Values (drop down value menues).
On definition of a BDKM device the gateway is connected and a full poll collecting all IDs is done. This takes about 20 to 30 seconds. After that the module knows all IDs reported by the gateway. To examine these IDs just type:
get myBDKM INFO
These IDs can be used with the PollIds attribute to define if and how the IDs are read during the poll cycle.
All IDs can be mapped to own short readings.

Define
define <name> BDKM <IP-address|hostname> <GatewayPassword> <PrivatePassword> <MD5-Salt>
or
define <name> BDKM <IP-address|hostname> <AES-Key>


<name> : Name of device
<IP-address> : The IP adress of your Buderus gateway
<GatewayPassword> : The gateway password as printed on case of the gateway s.th. of the form: xxxx-xxxx-xxxx-xxxx
<PrivatePassword> : The private password as set with the buderus App
<MD5-Salt> : MD5 salt for the crypt algorithm you want to use (hex string like 867845e9.....). Have a look for km200 salt 86 ...
AES-Key can be generated here:
https://ssl-account.com/km200.andreashahn.info


Set
set <name> <ID> <value> ...

where ID is a valid writeable gateway ID (See list command, or "get myBDKM INFO")
The set command first reads the the ID from the gateway and also triggers a FHEM readings if necessary. After that it is checked if the value is valid. Then the ID and value(s) are transfered to to the gateway. After waiting (attr ReadBackDelay milliseconds) the value is read back and checked against value to be set. If necessary again a FHEM reading may be triggered. The read back value or an error is returned by the command.
Examples:
set myBDKM /heatingCircuits/hc1/temporaryRoomSetpoint 22.0
or the aliased version of it (if /heatingCircuits/hc1/temporaryRoomSetpointee is aliased to RoomTemporaryDesiredTemp):
set myBDKM RoomTemporaryDesiredTemp 22.0
special to set time of gateway to the hosts date:
set myBDKM /gateway/DateTime now
aliased:
set myBDKM DateTime now




Get
get <name> <ID> <[raw|json]>...

where ID is a valid gateway ID or an alias to it. (See list command)
The get command reads the the ID from the gateway, triggeres readings if necessarry, and returns the value or an error if s.th. went wrong. While polling is done asychronously with a non blocking HTTP GET. The set and get functions use a blocking HTTP GET/POST to be able to return a value directly to the user. Normaly get and set are only used by command line or when setting values via web interface.
With the raw option the whole original decoded data of the ID (as read from the gateway) is returned as a string.
With the json option a perl hash reference pointing to the JSON data is returned (take a look into the module if you want to use that)

Examples:
get myBDKM /heatingCircuits/hc1/temporaryRoomGetpoint
or the aliased version of it (see attr below):
get myBDKM RoomTemporaryDesiredTemp
get myBDKM DateTime
get myBDKM /gateway/instAccess
Spacial to get Infos about IDs known by the gateway and own configurations:
get myBDKM INFO
Everything matching /temp/ get myBDKM INFO temp
Everything matching /Heaven/ or /Hell/ get myBDKM INFO Heaven Hell
Everything known: get myBDKM INFO .*
Arguments to INFO are reqular expressions which are matched against all IDs and all aliases.



Attributes
• BaseInterval
  The interval time in seconds between poll cycles. It defaults to 120 seconds. Which means that every 120 seconds a new poll collects values of IDs which turn it is.


• InterPollDelay
  The delay time in milliseconds between reading of two IDs from the gateway. It defaults to 0 (read as fast as possible). Some gateways/heatings seem to stop answering after a while when you are reading a lot of IDs. (verbose 2 "communication ERROR"). To avoid gateway hangups always try to read only as many IDs as really required. If it doesn't help try to increase the InterPollDelay value. E.g. start with 100.


• ReadBackDelay
  Read back delay for the set command in milliseconds. This value defaults to 500 (0.5s). After setting a value, the gateway need some time before the value can be read back. If this delay is too short after writing you will get back the old value and not the expected new one. The default should work in most cases.


• HttpTimeout
  Timeout for all HTTP requests in seconds (polling, set, get). This defaults to 10s. If there is no answer from the gateway for HttpTimeout time an error is returned. If a HTTP request expires while polling an error log (level 2) is generated and the request is automatically restarted after 60 seconds.


• PollIds
  Without this attribute FHEM readings are NOT generated automatically!
  This attribute defines how and when IDs are polled within a base interval (set by atrribute BaseInterval).
  The attribute contains list of space separated IDs and options written as
  GatewayID:Modulo:Delta:Alias
  Where Gateway is the real gateway ID like "/gateway/DateTime".
  Modulo is the value which defines how often the GatewayID is polled from the gateway and checked for FHEM readings update. E.g. a value of 4 means that the ID is polled only every 4th cycle.
  Delta defines the minimum difference a polled value must have to the previous reading, before a FHEM reading with the new value is generated.
  Alias defines a short name for the GatewayID under which the gateway ID can be accessed. Also readings (Logfile entries) are generated with this short alias if set. If not set, the original ID is used.
  In detail:
  ID:1:0:Alias - poll every cycle, when difference >= 0 to previous reading (means always, also for strings) trigger FHEM reading to "Alias"
  ID:1::Alias - poll every cycle, no Delta set => trigger FHEM reading to "Alias" on value change only
  ID:0::Alias - update reading on startup once if reading changed (to the one prevously saved in fhem.save)
  ID:1:0.5:Alias - poll every cycle, when difference => 0.5 trigger a FHEM reading to "Alias"
  ID:15::Alias - poll every 15th cylce, update reading only if changed
  ID:::Alias - update reading on (get/set) only and only if value changed
  ID::0:Alias - update reading on (get/set) only and trigger reading always on get/set
  ID - without colons ":", poll every cycle, update reading allways (same as ID:1:0:)
  Also some usefull defaults can be set by the special keyword RC300DEFAULTS, RC35DEFAULTS, RC30DEFAULTS.
  As I don't know anything about RC35 or RC30 the later keywords are currently empty (please send me some info with "get myBDKM INFO" :-)
  Definitions set by the special keywords (see the module code for it) are overwritten by definitions later set in the attribute definition
  Example:
  attr myBDKM PollIds \
RC300DEFAULTS \
/gateway/DateTime:0::Date \
/system/info:0:0:\
/dhwCircuits/dhw1/actualTemp:1:0.2:WaterTemp
  
  Which means: Use RC300DEFAULTS, trigger FHEM reading "Date" when date has changed on startup only. Trigger FHEM reading "/system/info" (no aliasing) always on startup, poll water temperature every cycle and trigger FHEM reading "WaterTemp" when difference to last reading was at least 0.2 degrees.
  

BEOK

BEOK implements a connection to BEOK / Floureon / Hysen WiFi room thermostat
AES Encyrption is needed. Maybe you must first install extra Perl modules.
E.g. for Debian/Raspian :
sudo apt-get install libcrypt-cbc-perl
sudo apt-get install libcrypt-rijndael-perl
sudo apt-get install libssl-dev
sudo cpan Crypt/OpenSSL/AES.pm

Define
define <name> BEOK <ip> [mac]

Example: define Thermo BEOK 192.168.1.100

Set

• desired-temp <5 - 99>


• mode <auto manual>


• loop <12345.67 123456.7 1234567>
  12345.67 means Saturday and Sunday follow the "weekend" schedule
  1234567 means every day (including Saturday and Sunday) follows the "weekday" schedule


• sensor <external internal both>
  both = internal control temperature, external limit temperature


• time
  sets time and day of week on device to FHEM time & day


• lock <on off>


• power-on-memory <on off>


• fre <open close> Anti-freezing function


• room-temp-adj <-5 +5>


• osv <5 - 99>
  Limit temperature value of external sensor


• svh <5 - 99>
  Set upper limit temperature value


• svl <5 - 99>
  Set lower limit temperature value


• dif <1 - 9>
  difference of limit temperature value of external sensor


• day-profil[1-6]-temp <5 - 99>


• day-profil[1-6]-time <00:00 - 23:59>


• we-profile[7-8]-temp <5 - 99>


• we-profile[7-8]-time <00:00 - 23:59>


• weekprofile
  Set all weekday setpoints and temperatures with values from a weekprofile day.
  Syntax : set weekprofile <weekprofile_device:profil_name[:weekday]>
  see also https://forum.fhem.de/index.php/topic,80703.msg901303.html#msg901303


Attributes

• timeout
  timeout for network device communication, default 5


• interval
  poll time interval in seconds, set to 0 for no polling , default 60


• timesync
  set device time and day of week automatic to FHEM time, default 1 (on)


• language
  set to DE for german names of Room, Floor , etc.


• model
  only for FHEM modul statistics at https://fhem.de/stats/statistics.html

BOSEST

BOSEST is used to control a BOSE SoundTouch system (one or more SoundTouch 10, 20 30, 300 or Portable devices)

Note: The following libraries are required for this module:
• libwww-perl
• libmojolicious-perl
• libxml-simple-perl
• libnet-bonjour-perl
• libev-perl
• liburi-escape-xs-perl
• sox
• libsox-fmt-mp3

Use sudo apt-get install libwww-perl libmojolicious-perl libxml-simple-perl libnet-bonjour-perl libev-perl liburi-escape-xs-perl to install this libraries.
Please note: libmojolicious-perl must be >=5.54
Use sudo apt-get install cpanminus and sudo cpanm Mojolicious to update to the newest version.

TextToSpeach (TTS) can be configured as described in the following thread: Link
Questions and/or feedback can be posted on the FHEM forum: Link


Define
define <name> BOSEST

Example:
define bosesystem BOSEST
Defines BOSE SoundTouch system. All devices/speakers will show up after 60s under "Unsorted" in FHEM.


Set
set <name> <command> [<parameter>]

The following commands are defined for the devices/speakers (except autoAddDLNAServers is for the "main" BOSEST) :


General commands
• on   -   power on the device
• off   -   turn the device off
• power   -   toggle on/off
• volume [0...100] [+x|-x]   -   set the volume level in percentage or change volume by ±x from current level
• channel 0...20   -   select present to play
• saveChannel 07...20   -   save current channel to channel 07 to 20
• play   -   start to play
• pause   -   pause the playback
• playpause   -   toggle play/pause
• stop   -   stop playback
• nextTrack   -   play next track
• prevTrack   -   play previous track
• playTrack name|location|source[|sourceAccount]   -   searches per DNLA for the track title and plays it
  additional information:
  1. You can search for trackTitle, trackAlbum, trackArtist (german FHEM forum post)
  2. You can test it in the SoundTouch APP: Use the search in the APP to see if a playlist is found and played. It yes it will work with playTrack too. (german FHEM forum post)
• mute on|off|toggle   -   control volume mute
• shuffle on|off   -   control shuffle mode
• repeat all|one|off   -   control repeat mode
• bass 0...10   -   set the bass level
• recent 0...15   -   set number of names in the recent list in readings
• source bluetooth,bt-discover,aux mode, airplay   -   select a local source


• addDLNAServer Name1 [Name2] [Namex]   -   add DLNA servers Name1 (and Name2 to Namex) to the BOSE library
• removeDLNAServer Name1 [Name2] [Namex]   -   remove DLNA servers Name1 (and Name2 to Namex) to the BOSE library

Example: set BOSE_1234567890AB volume 25  Set volume on device with the name BOSE_1234567890AB



Timer commands:
• on-for-timer 1...x   -   power on the device for x seconds
• off-for-timer 1...x   -   turn the device off and power on again after x seconds
• on-till hh:mm:ss   -   power on the device until defined time
• off-till hh:mm:ss   -   turn the device off and power on again at defined time
• on-till-overneight hh:mm:ss   -   power on the device until defined time on the next day
• off-till-overneight hh:mm:ss   -   turn the device off at defined time on the next day

Example: set BOSE_1234567890AB on-till 23:00:00  Switches device with the name BOSE_1234567890AB now on and at 23:00:00 off



Multiroom commands:
• createZone deviceID[,deviceID]   -   create multiroom zone and adds device(s) to the multiroom zone
• addToZone deviceID   -   add device to multiroom zone
• removeFromZone deviceID   -   remove device from multiroom zone
• playEverywhere   -   play sound of a device on all others devices
• stopPlayEverywhere   -   stop playing sound on all devices

Example1: set BOSE_1234567890AB playEverywhere  Starts playing the sound of the device BOSE_1234567890AB on allother devices

Example2: set BOSE_1234567890AB createZone AB1234567890,12AB34567890  Defines BOSE_1234567890AB as multiroom master and adds BOSE_AB1234567890 and BOSE_12AB34567890 to the multiroom zone

Note: A "double-tap" (<1s) on a preset button (device or remote control) will toggle playEverywhere/stopPlayEverywhere



Show clock command (only for ST20/30):
• clock enable/disable   -   show or hide clock

Example: set BOSE_1234567890AB clock enable  Show time in the ST20/30 display.



TextToSpeach commands (needs Google Translate):
• speak "message" [0...100] [+x|-x] [en|de|xx]   -   Text to speak, optional with volume adjustment and language to use.
• speakOff "message" [0...100] [+x|-x] [en|de|xx]   -   Text to speak, optional with volume adjustment and language to use. Device is switched off after speak.

Example: set BOSE_1234567890AB speakOff "Music is going to switch off now. Good night." 30 en  Speaks message at volume 30 and then switches off device.



DNLA Server command:
• autoAddDLNAServers 0|1   -   1=automatically add all DLNA servers to BOSE library. This command is only for "main" BOSEST, not for devices/speakers!


Get
n/a

Attributes
• staticIPs IP-Address [,IP-Address]  -   Manually define the used IP address(es) (comma separated) of your BOSE devices. Should be used only, if BOSEST device detection doesn't work in your network (e.g. several subnets on server, subnet not directly connected, ...)
  Example: attr bosesystem staticIPs 192.168.1.52,192.168.1.53
• speakChannel channel(s)  -   speaks channel/present name bevor starting a playback, useful for SoundTouch without display (comma separated or range: e.g. 2,3,5,6 or 1-6 ). TTS must be installed.
• auto-zone on|off   -   automatic start multiroom zone play, if speakers are playing the same, according to "contentItemLocation"; (default: off)
• ttsDirectory "directory"   -   set DLNA TTS directory. FHEM user needs permissions to write to that directory.
• ttsLanguage en|de|xx   -   set default TTS language (default: en)
• ttsSpeakOnError 0|1   -   0=disable to speak "not available" text
• ttsVolume [0...100] [+x|-x]   -   set the TTS volume level in percentage or change volume by ±x from current level
• Channel_07 to Channel_20 name|location|source|[sourceAccount]   -   define present 07 to 20
  When you play something, you can find ContentItemLocationName, ContentItemLocation, etc. in the readings. These data can be used here to define the present.

BOTVAC

This module controls Neato Botvac Connected and Vorwerk Robot Vacuums.
For issuing commands or retrieving Readings it's necessary to fetch the information from the NEATO/VORWERK Server. In this way, it can happen, that it's not possible to send commands to the Robot until the corresponding Values are fetched. This means, it can need some time until your Robot will react on your command.

Define

define <name> BOTVAC <email> [NEATO|VORWERK] [<polling-interval>]

Example: define myNeato BOTVAC myemail@myprovider.com NEATO 300

After defining the Device, it's necessary to log in into your account which is linked to your email address.

• If you have a password, enter it with set <name> password <password>
  It is exactly the same Password as you use on the Website or inside the App.

  Example: set NEATO passwort mySecretPassword

• If authentication without a password is provided, you have to following the registration process.

  1. Ask for an one-time password by set <name> requestVerification
  2. Provide one-time password from email set <name> sendVerification <code>

Get

• get <name> batteryPercent
  requests the state of the battery from Robot
• get <name> securityTokens
  list of all tokens stored by the module. The tokens are relevant for user authentication and to get access to robot data.
• get <name> statistics
  display statistical data, extracted from available maps of recent cleanings

Set

• set <name> findMe
  plays a sound and let the LED light for easier finding of a stuck robot
• set <name> dismissCurrentAlert
  reset an actual Warning (e.g. dustbin full)
• set <name> nextCleaningMode
  Depending on Model, there are Arguments available: eco/turbo
• set <name> nextCleaningModifier
  The modifier is used for next spot cleaning. Depending on Model, there are Arguments available: normal/double
• set <name> nextCleaningNavigationMode
  The navigation mode is used for the next house cleaning. Depending on Model, there are Arguments available: normal/extraCare/deep
• set <name> nextCleaningZone
  Depending on Model, the ID of the zone that will be used for the next zone cleaning can be set.
• set <name> nextCleaningSpotHeight
  Is defined as number between 100 - 400. The unit is cm.
• set <name> nextCleaningSpotWidth
  Is defined as number between 100 - 400. The unit is cm.
• set <name> password <password>
  set the password for the NEATO/VORWERK account
• set <name> pause
  interrupts the cleaning
• set <name> pauseToBase
  stops cleaning and returns to base
• set <name> reloadMaps
  load last map from server into the cache of the module. no file is stored!
• set <name> resume
  resume cleaning after pause
• set <name> requestVerification
  Request one-time password for account verfication.
  One-time password will be sent to the account's email address.
• set <name> schedule
  on and off, switch time control
• set <name> sendToBase
  send roboter back to base
• set <name> sendVerification <code>
  Use one-time password from email as code to log in into your account, see requestVerification.
• set <name> setBoundariesOnFloorplan_<floor plan> <name|{JSON String}>
  Set boundaries/nogo lines in the corresponding floor plan. The paramter can either be a name, which is already defined by attribute "boundaries", or alternatively a JSON string. (A comma-separated list of names is also possible.)
  Description of syntax
  Examples:
  set <name> setBoundariesOnFloorplan_0 Bad
set <name> setBoundariesOnFloorplan_0 Bad,Kueche
set <name> setBoundariesOnFloorplan_0 {"type":"polyline","vertices":[[0.710,0.6217],[0.710,0.6923]], "name":"Bad","color":"#E54B1C","enabled":true}
• set <name> setRobot
  choose robot if more than one is registered at the used account
• set <name> startCleaning ([house|map|zone])
  start the Cleaning from the scratch. If the robot supports boundaries/nogo lines/zones, the additional parameter can be used as:
  • house - cleaning without a persisted map
  • map - cleaning with a persisted map
  • zone - cleaning in a specific zone, set zone with nextCleaningZone
• set <name> startSpot
  start spot-Cleaning from actual position.
• set <name> startManual
  start Manual Cleaning. This cleaning mode opens a direct websocket connection to the robot. Therefore robot and FHEM installation has to reside in the same LAN. Even though an internet connection is necessary as the initialization is triggered by a remote call.
  Note: If the robot does not receive any messages for 30 seconds it will exit Manual Cleaning, but it will not close the websocket connection automaticaly.
• set <name> statusRequest
  pull update of all readings. necessary because NEATO/VORWERK does not send updates at their own.
• set <name> stop
  stop cleaning and in case of manual cleaning mode close also the websocket connection
• set <name> syncRobots
  sync robot data with online account. Useful if one has more then one robot registered
• set <name> pollingMode <on|off>
  set polling on (default) or off like attribut disable.
• set <name> robotSounds <on|off>
  set sounds on or off.
• set <name> dirtbinAlertReminderInterval <30|60|90|120|150>
  set alert intervall in minutes.
• set <name> filterChangeReminderInterval <1|2|3>
  set alert intervall in months.
• set <name> brushChangeReminderInterval <4|5|6|7|8>
  set alert intervall in months.
• set <name> wsCommand
  Commands start or stop cleaning activities.
  • eco-on
  • eco-off
  • turbo-on
  • turbo-off
  • brush-on
  • brush-off
  • vacuum-on
  • vacuum-off
• set <name> wsCombo
  Combos specify a behavior on the robot.
  They need to be sent with less than 1Hz frequency. If the robot doesn't receive a combo with the specified frequency it will stop moving. Also, if the robot does not receive any messages for 30 seconds it will exit Manual Cleaning.
  • forward - issues a continuous forward motion.
  • back - issues a discontinuous backward motion in ~30cm intervals as a safety measure since the robot has no sensors at the back.
  • arc-left - issues a 450 turn counter-clockwise while going forward.
  • arc-right - issues a 450 turn clockwise while going forward.
  • pivot-left - issues a 900 turn counter-clockwise.
  • pivot-right - issues a 900 turn clockwise.
  • stop - issues an immediate stop.

Attributes

• actionInterval
  time in seconds between status requests while Device is working
• boundaries
  Boundary entries separated by space in JSON format, e.g.
  {"type":"polyline","vertices":[[0.710,0.6217],[0.710,0.6923]],"name":"Bad","color":"#E54B1C","enabled":true}
{"type":"polyline","vertices":[[0.7139,0.4101],[0.7135,0.4282],[0.4326,0.3322],[0.4326,0.2533],[0.3931,0.2533],[0.3931,0.3426],[0.7452,0.4637],[0.7617,0.4196]],"name":"Kueche","color":"#000000","enabled":true}
  Description of syntax
  The value of paramter name is used as setListe for setBoundariesOnFloorplan_<floor plan>. It is also possible to save more than one boundary with the same name. The command setBoundariesOnFloorplan_<floor plan> <name> sends all boundary with the same name.

BRAVIA

This module controls a Sony TV device over ethernet. Devices of series starting from 2011 are supported.

Define
define <name> BRAVIA <ip-or-hostname> [<poll-interval>]

With definition of a BRAVIA device an internal task will be scheduled. This task pulls frequently the status and other information from the TV.
The intervall can be defined in seconds by an optional parameter <poll-intervall>. The default value is 45 seconds.

After definition of a device using this module it has to be registered as a remote control (set register).

As long as readings are not among the usual AV readings they are clustered:

s_*	: status
ci_*	: content information



The module contains predefined layouts for remotecontrol using PNG and SVG.


Set
set <name> <option> <value>

Options:
• application
  List of applications. Applications are available with models from 2013 and newer.
• channel
  List of all known channels. The module collects all visited channels. Channels can be loaded automtically with models from 2013 and newer. (number of channels, see channelsMax).
• channelDown
  Switches a channel back.
• channelUp
  Switches a channel forward.
• enable
  Enables the internal task to pull the status and other information from the TV.
• disable
  Disables the internal task to pull the status and other information from the TV.
• input
  List of input channels. Imputs are available with models from 2013 and newer.
• mute
  Set mute if Upnp is activated.
• off
  Switches TV to off. State of device will have been set to "set_off" for 60 seconds or until off-status is pulled from TV.
• on
  Switches TV to on, with models from 2013 using WOL. State of device will have been set to "set_on" for 60 seconds or until on-status is pulled from TV.
• openUrl
  Opens an URL on the screen. This Feature is available on models from 2013 and newer.
• pause
  Pauses a playing of a recording, of an internal App, etc.
• play
  Starts playing of a recording, of an internal App, etc.
• record
  Starts recording of current content.
• register
  One-time registration of Fhem as remote control in the TV.
  With requestFormat = "xml" registration works without parameter.
  With requestFormat = "json" registration has to be executed twice.
  The register option offers an additional input field:
  1. Call with empty input. A PIN for registration has to be shown on the TV.
  2. Insert PIN into input field and register again.
• requestFormat
  "xml" for xml based communication (models from 2011 and 2012)
  "json" for communication with models from 2013 and newer
• requestReboot
  Reboots the TV immediately. This Feature is available on models from 2013 and newer.
• remoteControl
  Sends command directly to TV.
• statusRequest
  Retrieves current status information from TV.
• stop
  Stops recording, playing of an internal App, etc.
• text
  Includes the given text into an input field on display.
• toggle
  Toggles power status of TV.
• tvpause
  Activates Timeshift mode.
• upnp
  Activates Upnp service used to control volume.
• volume
  Straight setting of volume. Upnp service has to be activated.
• volumeDown
  Decreases volume.
• volumeUp
  Increases volume.

Attributes
attr <name> <attribute> <value>

Attributes:
• channelsMax
  Maximum amount of channels to be displayed, default is 50.
• macaddr
  Enables power on of TV using Wake-On-Lan.
• wolBroadcast
  Broadcast address for Wake-On-Lan magic packets, default is 255.255.255.255.

BS

The module BS allows to collect data from a brightness sensor through a FHZ device. For details on the brightness sensor see busware wiki. You can have at most nine different brightness sensors in range of your FHZ.

The state contains the brightness in % (reading brightness) and the brightness in lux (reading lux). The flags reading is always zero. The meaning of these readings is explained in more detail on the above mentioned wiki page.

Define
define <name> BS <sensor#> [<RExt>]

<sensor#> is the number of sensor in the brightness sensor address system that runs from 1 to 9.

<RExt> is the value of the resistor on your brightness sensor in Ω (Ohm). The brightness reading in % is proportional to the resistance, the lux reading is proportional to the resistance squared. The value is optional. The default resistance is RExt= 50.000Ω.

Example:

define bs1 BS 1 40000


Set
N/A

Get
N/A

Attributes
• do_not_notify
• showtime
• model (bs)
• ignore
• readingFnAttributes

Babble

FHEM module for speech control of FHEM devices

Usage

See German Wiki page


Define

define <name> Babble
Defines the Babble device.

Notes:
• This module uses the global attribute language to determine its output data
  (default: EN=english). For German output set attr global language DE.
• This module needs the JSON package.
• Only when the chatbot functionality of RiveScript is required, the RiveScript module must be installed as well, see https://github.com/aichaos/rivescript-perl

Usage

To use this module,
1. call the Perl function Babble_DoIt("<name>","<sentence>"[,<parm0>,<parm1>,...]).
2. execute the FHEM command set <name> talk|doit <sentence>[,<parm0>,<parm1>,...].
<name> is the name of the Babble device, <parm0> <parm1> are arbitrary parameters passed to the executed command. The module will analyze the sentence passed an isolate a device to be addressed, a place identifier, a verb, a target and its value from the sentence passed. Attention: in case the FHEM command is used, <sentence> must not contain commas. If a proper command has been stored with device, place, verb and target, it will be subject to substitutions and then will be executed. In these substitutions, a string $VALUE will be replaced by the value for the target reading, a string $DEV will be replaced by the device name identified by Babble, and strings $PARM[0|1|2...] will be replaced by the corresponding parameters passed to the function Babble_DoIt
• If no stored command ist found, the sentence is passed to the local RiveScript interpreter if present
• To have a FHEM register itself as a Babble Device, it must get an attribute value babbleDevice=<name>. The name parameter must either be unique to the Babble system, or it muts be of the form <name>_<digits>
• Devices on remote FHEM installations are defined in the babbleDevices attribute, see below

Set

• set <name> talk|doit <sentence>[,<parm0>,<parm1>,...]
  
  execute the command given in the sentence.
• set <name> locked
set <name> unlocked
  sets the lockstate of the babble module to locked (i.e., babble setups may not be changed) resp. unlocked (i.e., babble setups may be changed>)
• set <name> save|restore
  Manually save/restore the babble to/from the external file babbleFILE (save done automatically at each state modification, restore at FHEM start)
• set <name> rivereload
  Reload data for RiveScript Interpreter
• set <name> test
  Run a few test cases for normalization

Get

• get <name> version
  Display the version of the module
• get <name> tokens
  Obtain fresh csrfToken from remote FHEM installations (needed after restart of remote FHEM)

Attributes

• attr <name> babbleDevices [<babble devname>:<FHEM devname>:1|2|3]*
  space separated list of remote FHEM devices, each as a group separated by ':' consisting of
  • a Babble device name
  • a FHEM Device name
  • an integer 1..3, indication which of the remoteFHEM functions to be called
  The Babble device name may contain a *-character. If this is the case, it will be considered a regular expression, with the star replaced by (.*). When using Babble with a natural language sentence whose device part matches this regular expression, the character group addressed by the star sequence is placed in the variable $STAR, and used to replace this value in the command sequence.
• attr <name> helpFunc <function name&rt;
  name of a help function which is used in case no command is found for a certain device. When this function is called, the strings $DEV, $HELP, $PARM[0|1|2...] will be replaced by the devicename identified by Babble, the help text for this device and parameters passed to the Babble_DoIt function
• attr <name> testParm(0|1|2|3) <string&rt;
  if a command is not really excuted, but only tested, the values of these attributes will be used to substitute the strings $PARM[0|1|2...] in the tested command
• attr <name> dnuFile <filename&rt;
  if this filename is given, every sentence that could not be analyzed is stored in this file
• attr <name> confirmFunc <function name&rt;
  name of a confirmation function which is used in case a command is exceuted. When this function is called, the strings $DEV, $HELP, $PARM[0|1|2...] will be replaced by the devicename identified by Babble, the help text for this device and parameters passed to the Babble_DoIt function
• attr <name> noChatBot 0|1
  if this attribute is set to 1, a local RiveScript interpreter will be ignored even though it is present in the system
• attr <name> remoteFHEM(0|1|2|3) [<user>:<password>@]<IP address:port&rt;
  IP address and port for a remote FHEM installation
• attr <name> remoteFunc(0|1|2|3) <function name&rt;
  name of a Perl function that is called for addressing a certain remote FHEM device
• attr <name> remoteToken(0|1|2|3) <csrfToken&rt;
  csrfToken for addressing a certain remote FHEM device
• attr <name> babbleIds ...
  space separated list of identities by which babble may be addressed
• attr <name> babbleSubs :,:, ...
  space separated list of regular expressions and their replacements - this will be used on the initial sentence submitted to Babble (Note: a space in the regexp must be replaced by \s).
• attr <name> babblePlaces ...
  space separated list of special places to be identified in speech
• attr <name> babbleNoPlaces ...
  space separated list of rooms (in the local FHEM device) that should not appear in the list of place
• attr <name> babbleStatus ...
  space separated list of status identifiers to be identified in speech. Example: Status Value Weather Time
• attr <name> babblePrepos ...
  space separated list of prepositions to be identified in speech. Example: by in at on
• attr <name> babbleTimes ...
  space separated list of temporal adverbs. Example: today tomorrow
• attr <name> babbleQuests ...
  space separated list of questioning adverbs. Example: how when where
• attr <name> babbleArticles ...
  space separated list of articles to be identified in speech. Example: the
• attr <name> babbleVerbs ,...: ,...:
  space separated list of verb groups to be identified in speech. Each group consists of comma separated verb forms (conjugations as well as variations), followed by a ':' and then the infinitive form of the verb. Example: speak,speaks,say,says:speaking
• attr <name> babbleWrites ...
  space separated list of write verbs to be identified in speech. Example: send add remove
• attr <name> babbleVerbParts ...
  space separated list of verb parts to be identified in speech. Example: un re
• attr <name> linkname <string>
  Name for babble web link, default: babbles
• attr <name> hiddenroom <string>
  Room name for hidden babble room (containing only the Babble device), default: babbleRoom
• attr <name> publicroom <string>
  Room name for public babble room (containing sensor/actor devices), default: babble
• attr <name> lockstate locked|unlocked
  locked means that babble setups may not be changed, unlocked means that babble setups may be changed>

BlinkCamera

This module connects remotely to a system of Blink Home Cameras Blink Home Cameras are relatively inexpensive wire-free video home security & monitoring system

Disclaimer: Since there are no official APIs for the blink cameras, there is no guarantee for this module to continue working. Several changes over the years have caused temporary outages due to incompatibe changes done by the provider of the Blink cameras.

The blink device contains the possibility to regular poll for updates (i.e. specifically for notifications/alerts) MOst commands that change configurations are not synchronous, but the result will be returned after polling for status information. This is automatically handled in the device and the result of the cmd is marked in the reading cmdResult with the value "SUCCESS".
Traditional Blink cameras and also the BlinkMini types should work
The blink device also contains a proxy for retrieving videos and thumbnails throug an FHEMweb extension in the form of http://<fhem>:<fhemwebport>/fhem/BlinkCamera/<name of the blink device>/...

Define
define <name> BlinkCamera <email> [ <password> ]

Defines a BlinkCamera device, which connects to the cloud servers with the given user name and password (as provided during registration / setup)

The password will be removed from the define and stored separately (so needs to be given on the initial define)

Example: define blink BlinkCamera ichbins@nicht.de abc123




Set
set <name> <what> [<value>]

where <what> / <value> is one of


• login
  Initiate a login to the blink servers. This is usually done automatically when needed or when the login is expired
• verifyPin
  can be used to verify the pin send from blink via email/sms
• arm or disarm
  All enabled cameras in the system will be armed (i.e. they will be set to a mode where alarms/videos are automatically created based on the current settings) / disarmed (set to inactive mode where no video is recorded.
• camEnable <camera name or number or "all"> or camDisable <camera name or number>
  The specified camera will be enabled (i.e. so that it is included in the arm / disarm commands) / disabled (excluded from arm/disarm).
• reset
  Reset the FHEM device (only used in case of something gets into an unknown or strange state)
• resetUniqueID
  Reset the FHEM device (only used in case of something gets into an unknown or strange state). Additionally the uniqueID that is used in the device loing will be reset in this option.
• videoDelete <video id>
  The video with the given id will be removed (both from the local filesystem and from the blink servers)


Get
get <name> <what> [<value>]

where <what> / <value> is one of


• getNetworks
  Retrieve the networks defined in the blink account. This is needed for further operations and information request to blink. For specifying a specific network (id), the attribute network can be also set
• getInfo
  Get information about the system from the blink servers (including cameras and state) . This is usually done automatically based on the reular interval specified in attribute pollingTimeout
• getInfoCamera <camera name or number or "all">
  Get the information about the specified camera from the blink system. Currently the information about the camera is just stored in raw json format in a single reading cameraConfig<camera id>
• getThumbnail <camera name or number or "all">
  Request a new thumbnail being taken from the specified camera in the blink system. The thumbnail is not automatically retrieved, this can be done using getInfoCamera
• getVideoAlert [ <video id> ]
  Retrieve the video for the corresponding id (or if ommitted as specified in the reading alertID) and store the video in a local file in the directory given in the attribute proxyDir
• liveview <camera name or number or "all">
  Request a link to the live video stream. The live video stream access (URL) will be stored in the reading liveVideo (the associated cam id in liveCam). The link to the video is an rtsp - which can be shown in video players like VLC.
  Note: Live video streaming might have a substantially negative effect on battery life
  


Attributes


• maxRetries <0|1|2...|9>
  Defines the number of retries that are done in case of a failure of a command. Pauses between retries are done with an increasing delay between calls.
• network <network id>
  This attribute is needed if your blink system contains more than one network. If not specified the first netowrk defined in the account is used
• proxyDir <directory path>
  Specify the path where temporary files (videos, thumbnails) are stored to be access via the proxy server built into the device as an fhemweb extension
• pollingTimeout <interval>
  Interval in which the system is checking for status updates from the blink servers (given in seconds - value 0 means no polling). This is the frequency in which new alerts can be received
• imgTemplate <HTML template for reading>
  Give an HTML template for the image reading that shows the thumbnail of a camera. Default is a template which shows the image a link to the image and also the url as text. In the template the string #URL# will be replaced with the actual URL
• imgOriginalFile <1 or 0>
  If set to 1 it will keep the original filename of the thumbnail when storing ti. With setting this new thumbnails will not overwrite existing ones.
  NOTE: No cleanup of thumbnails is done, so over time more and more thumbnails will be stored in the proxydir.
• vidTemplate <HTML template for reading>
  Give an HTML template for the video reading that shows the video of a notification from the camera. Default is a template which shows the video a link to the video and also the url and id as text. In the template the string #URL# will be replaced with the actual URL of the video and #ID# will be replaced by the video ID.
• webname <path to fhem web>
  can be set if fhem is not accessible through the standard url of FHEMWeb /fhem/... (Default value is fhem).
• homeScreenV3 <1 or 0>
  If set to 1 (default) the new version 3 of the blink API will be used. Unfortunately this includes different readings and settings
  NOTE: This attribute is deprecated and not needed anymore, since the old API has been switched off by Blink (default is on = 1)


Readings
• cmd <internal name of the last executed command>
  Used to identify the cmd that was last executed and where the result is given in cmdResult
• cmdResult <error message or SUCCESS>
  Used to identify success or failure of a command


• networks <list of networks>
  Lists the defined networks for the account at blink in the form networkid:networkname
• networkName <name>
  Name of the network that is currently used to fill the readings
• networkArmed <status>
  Network arm status (true or false)
• networkStatus <ok or failure>
  Basic status of the current network
• networkCameras <number>
  Lists the defined cameras in the current network in the form cameraid:cameraname
• networkSyncModule <id and status>
  Information about the syncmodule in the current network in the form syncid:syncmodulestatus


• networkCamera...
  Set of readings specific for each camera (identified by the cameraID in the reading name). Providing status and name of the camera / most recent thumbnail / url for the thumbnail to the proxy
• networkCameraEnabled
  Shows the enabled (active) status of the camera (known values: 0 / 1 / "undef" - last value will be given if this value is not contained in the camerainfo


• alert...
  Set of readings specifying the last alert (movement alert) coming from one of the devices. Especially the ID is relevant here for accessing the corresponding video secifically. Additionally the camera, time and video url are specifed here.

Broadlink

Broadlink implements a connection to Broadlink devices - currently tested with Broadlink RM Pro, which is able to send IR and 433MHz commands. It is also able to record this commands. It can also control rmmini devices and sp3 or sp3s plugs.
It requires AES encryption please install on Windows:
ppm install Crypt-CBC
ppm install Crypt-OpenSSL-AES

or Linux/Raspberry: sudo apt-get install libcrypt-cbc-perl
sudo apt-get install libcrypt-rijndael-perl
sudo cpan Crypt/OpenSSL/AES.pm


Define
define <name> Broadlink <ip/host> <mac> <type=rmpro or rmmini or sp3 or sp3s>

Example: define broadlinkWZ Broadlink 10.23.11.85 34:EA:34:F4:77:7B rmpro

The mac of the device have to be set in format: xx:xx:xx:xx:xx
The type is in current development state optional.

Set for rmpro

• set <name> <commandSend> <command name>
  
  Send a previous recorded command.
• set <name> recordNewCommand <command name>
  
  Records a new command. You have to specify a commandname
• set <name> remove <command name>
  
  Removes a recored command.
• set <name> rename <old command name> <new command name>
  
  Renames a recored command.
• set <name> getTemperature
  
  Get the device current enviroment Temperature
Set for rmmini

• set <name> <commandSend> <command name>
  
  Send a previous recorded command.
• set <name> recordNewCommand <command name>
  
  Records a new command. You have to specify a commandname
• set <name> remove <command name>
  
  Removes a recored command.
• set <name> rename <old command name> <new command name>
  
  Renames a recored command.

Set for sp3

• set <name> on
  
  Set the device on
• set <name> off
  
  Set the device off
• set <name> toggle
  
  Toggle the device on and off
• set <name> getStatus
  
  Get the device on/off status
Set for sp3s

• set <name> on
  
  Set the device on
• set <name> off
  
  Set the device off
• set <name> toggle
  
  Toggle the device on and off
• set <name> getStatus
  
  Get the device on/off status
• set <name> getEnergy
  
  Get the device current energy consumption

Attributes for all Broadlink Devices

• socket_timeout
  
  sets a timeout for the device communication

CALVIEW

This module creates a device with deadlines based on calendar-devices of the 57_Calendar.pm module. You need to install the perl-modul Date::Parse!

Please configure the attribut HideOlderThen in your CALENDAR-Device, that controls if old events from past are shown!

Define

define <Name> CALVIEW <calendarname(s) separate with ','> <next> <updateintervall in sec (default 43200)>

define myView CALVIEW Googlecalendar next

define myView CALVIEW Googlecalendar,holiday next 900

- setting the update interval is not needed normally because every calendar update triggers a caview update

Set

set <Name> update

set myView update

this will manually update all readings from the given CALENDAR Devices

Attribute

datestyle
not set - the default, disables displaying readings bdatetimeiso / edatetimeiso
ISO8601 - enables readings bdatetimeiso / edatetimeiso (start and end time of term ISO8601 formated like 2017-02-27T00:00:00)

disable
0 / not set - internal notify function enabled (default)
1 - disable the internal notify-function of CALVIEW wich is triggered when one of the given CALENDAR devices has updated

filterSummary

filterSummary <filtersouce>:<filtersummary>[,<filtersouce>:<filtersummary>]
not set - displays all terms (default .*:.*)
<filtersouce>:<filtersummary>[,<filtersouce>:<filtersummary>] - CALVIEW will display term where summary matches the <filtersouce>:<filtersummary>, several filters must be separated by comma (,) e.g.: filterSummary Kalender_Abfall:Leichtverpackungen,Kalender_Abfall:Bioabfall filterSummary Kalender_Abfall:Leichtverpackungen,Kalender_Feiertage:.*,Kalender_Christian:.*,Kalender_Geburtstage:.*

fulldaytext [text]
this text will be displayed in _timeshort reading for fullday terms (default ganztägig)

isbirthday
0 / not set - no age calculation (default)
1 - age calculation active. The module calculates the age with year given in description or location (see att yobfield).

maxreadings
defines the number of max term as readings

modes
here the CALENDAR modes can be selected , to be displayed in the view

oldStyledReadings
0 the default style of readings
1 readings look like "2015.06.21-00:00" with value "Start of Summer"

sourcecolor <calendername>:<colorcode>[,<calendername>:<colorcode>]
here you can define the termcolor for terms from your calendars for the calview tabletui widget, several calendar:color pairs must be separated by comma

timeshort
0 time in _timeshort readings formated 00:00:00
1 time in _timeshort readings formated 00:00

yobfield
_description - (default) year of birth will be read from term description
_location - year of birth will be read from term location
_summary - year of birth will be read from summary (uses the first sequence of 4 digits in the string)

weekdayformat
formats the name of the reading weekdayname
- de-long - (default) german, long name like Dienstag
- de-short - german, short name like Di
- en-long - english, long name like Tuesday
- en-short - english, short name like Tue

CDCOpenData

CM11

Note: this module requires the Device::SerialPort or Win32::SerialPort module.

Define
define <name> CM11 <serial-device>

CM11 is the X10 module to interface X10 devices with the PC.

The current implementation can evaluate incoming data on the powerline of any kind. It can send on, off, dimdown and dimup commands.

The name of the serial-device depends on your distribution. If serial-device is none, then no device will be opened, so you can experiment without hardware attached.
If you experience problems (for verbose 4 you get a lot of "Bad CRC message" in the log), then try to define your device as
define <name> FHZ <serial-device> strangetty

Example:
define x10if CM11 /dev/ttyUSB3



Set
set <name> reopen

Reopens the serial port.

Get
get <name> fwrev

Reads the firmware revision of the CM11 device. Returns error if the serial connection to the device times out. Can be used for error detection.

get <name> time

Reads the internal time of the device which is the total uptime (modulo one year), since fhem sets the time to 0.00:00:00 if the device requests the time to be set after being powered on. Returns error if the serial connection to the device times out. Can be used for error detection.

Attributes
• do_not_notify
• dummy
• model (CM11)

CO20

Module for measuring air quality with usb sticks based on the AppliedSensor iAQ-Engine sensor. Products currently know to work are the VOLTCRAFT CO-20, the Sentinel Haus Institut RaumluftWächter and the VELUX Raumluftfühler.
Probably works with all devices recognized as iAQ Stick (0x03eb:0x2013).

Notes:
• Device::USB hast to be installed on the FHEM host.
  It can be installed with 'cpan install Device::USB'
  or on debian with 'sudo apt-get install libdevice-usb-perl''
• FHEM has to have permissions to open the device. To configure this with udev rules see here: Install_AirSensor_Linux usb-sensors-linux
• Advanced features are only available after setting the attribute advanced.
  Almost all the hidden settings from the Windows application are implemented in this mode.
  Readout of values gathered in standalone mode is not possible yet.

Define
define <name> CO20 [bus:device]

Defines a CO20 device. bus:device hast to be used if more than one sensor is connected to the same host.

Examples:
define CO20 CO20


Readings
• voc
  CO2 equivalents in ppm
• debug
  debug value
• pwm
  pwm value
• r_h
  resistance of heating element in Ohm (?)
• r_s
  resistance of sensor element in Ohm (?)

Get
• update / air_data
  trigger an update
• flag_data
  get internal flag values
• knob_data
  get internal knob values
• stick_data
  get stick information

Set
• KNOB_CO2_VOC_level_warn1
  sets threshold for yellow led
• KNOB_CO2_VOC_level_warn2
  sets threshold for red led
• KNOB_Reg_Set
  internal value, affects voc reading
• KNOB_Reg_P
  internal pid value
• KNOB_Reg_I
  internal pid value
• KNOB_Reg_D
  internal pid value
• KNOB_LogInterval
  log interval for standalone mode
• KNOB_ui16StartupBits
  set to 0 for no automatic calibration on startup
• FLAG_WARMUP
  warmup time left in minutes
• FLAG_BURN_IN
  burn in time left in minutes
• FLAG_RESET_BASELINE
  reset voc baseline value
• FLAG_CALIBRATE_HEATER
  trigger calibration / burn in
• FLAG_LOGGING
  value count from external logging

Attributes
• interval
  the interval in seconds used to read updates [10..]. the default ist 300.
• retries
  number of retries on USB read/write failures [0..20]. the default is 3.
• timeout
  the USB connection timeout in milliseconds [250..10000]. the default is 1000.
• advanced
  1 -> enables most of the advanced settings and readings described here
• disable
  1 -> disconnect and stop polling

COE_Node

Define

define <name> COE_Node <CAN-Node ID>

Defines a CanOverEthernet node. FHEM will automatically create these.
Example:
define COE_Node_coe_2 COE_Node 2
Assigment of readings to incoming values is done in the attribue 'readingsConfig'.

Attributes

• readingsConfigAnalog {index=reading-name}
  This maps received analog values to readings. eg 1=Flowrate_Solar 2=T.Solar_Backflow
• readingsConfigDigital {index=reading-name}
  This maps received digital values to readings. eg 1=Pump_Solar_Power 2=Pump_Water_Power

CUL

The CUL/CUN(O) is a family of RF devices sold by busware.de. With the opensource firmware culfw they are capable to receive and send different 433/868 MHz protocols (FS20/FHT/S300/EM/HMS/MAX!). It is even possible to use these devices as range extenders/routers, see the CUL_RFR module for details. Some protocols (FS20, FHT and KS300) are converted by this module so that the same logical device can be used, irrespective if the radio telegram is received by a CUL or an FHZ device. Other protocols (S300/EM) need their own modules. E.g. S300 devices are processed by the CUL_WS module if the signals are received by the CUL, similarly EMWZ/EMGZ/EMEM is handled by the CUL_EM module. It is possible to attach more than one device in order to get better reception, FHEM will filter out duplicate messages. Note: This module may require the Device::SerialPort or Win32::SerialPort module if you attach the device via USB and the OS sets strange default parameters for serial devices.

Define
define <name> CUL <device> <FHTID>

USB-connected devices (CUL/CUN):

<device> specifies the serial port to communicate with the CUL. The name of the serial-device depends on your distribution, under linux the cdc_acm kernel module is responsible, and usually a /dev/ttyACM0 device will be created. If your distribution does not have a cdc_acm module, you can force usbserial to handle the CUL by the following command:
modprobe usbserial vendor=0x03eb product=0x204b
In this case the device is most probably /dev/ttyUSB0.

You can also specify a baudrate if the device name contains the @ character, e.g.: /dev/ttyACM0@38400

If the baudrate is "directio" (e.g.: /dev/ttyACM0@directio), then the perl module Device::SerialPort is not needed, and FHEM opens the device with simple file io. This might work if the operating system uses sane defaults for the serial parameters, e.g. some Linux distributions and OSX.


Network-connected devices (CUN(O)):

<device> specifies the host:port of the device, e.g. 192.168.0.244:2323

If the device is called none, then no device will be opened, so you can experiment without hardware attached.
The FHTID is a 4 digit hex number, and it is used when the CUL talks to FHT devices or when CUL requests data. Set it to 0000 to avoid answering any FHT80b request by the CUL.

Set
• reopen
  Reopens the connection to the device and reinitializes it.


• raw
  Issue a CUL firmware command. See the this document for details on CUL commands.


• freq / bWidth / rAmpl / sens
  SlowRF mode only.
  Set the CUL frequency / bandwidth / receiver-amplitude / sensitivity
  Use it with care, it may destroy your hardware and it even may be illegal to do so. Note: The parameters used for RFR transmission are not affected.
  
  • freq sets both the reception and transmission frequency. Note: Although the CC1101 can be set to frequencies between 315 and 915 MHz, the antenna interface and the antenna of the CUL is tuned for exactly one frequency. Default is 868.3 MHz (or 433 MHz)
  • bWidth can be set to values between 58 kHz and 812 kHz. Large values are susceptible to interference, but make possible to receive inaccurately calibrated transmitters. It affects tranmission too. Default is 325 kHz.
  • rAmpl is receiver amplification, with values between 24 and 42 dB. Bigger values allow reception of weak signals. Default is 42.
  • sens is the decision boundary between the on and off values, and it is 4, 8, 12 or 16 dB. Smaller values allow reception of less clear signals. Default is 4 dB.


• hmPairForSec
  HomeMatic mode only.
  Set the CUL in Pairing-Mode for the given seconds. Any HM device set into pairing mode in this time will be paired with FHEM.


• hmPairSerial
  HomeMatic mode only.
  Try to pair with the given device. The argument is a 10 character string, usually starting with letters and ending with digits, printed on the backside of the device. It is not necessary to put the given device in learning mode if it is a receiver.


• led
  Set the CUL led off (00), on (01) or blinking (02).


• ITClock
  Set the IT clock for Intertechno V1 protocol. Default 250.


Get
• version
  returns the CUL firmware version


• uptime
  returns the CUL uptime (time since CUL reset)


• raw
  Issues a CUL firmware command, and waits for one line of data returned by the CUL. See the CUL firmware README document for details on CUL commands.


• fhtbuf
  CUL has a message buffer for the FHT. If the buffer is full, then newly issued commands will be dropped, and an "EOB" message is issued to the FHEM log. fhtbuf returns the free memory in this buffer (in hex), an empty buffer in the CUL V2 is 74 bytes, in CUL V3/CUN(O) 200 Bytes. A message occupies 3 + 2x(number of FHT commands) bytes, this is the second reason why sending multiple FHT commands with one set is a good idea. The first reason is, that these FHT commands are sent at once to the FHT.


• ccconf
  Read some CUL radio-chip (cc1101) registers (frequency, bandwidth, etc.), and display them in human readable form.


• cmds
  Depending on the firmware installed, CULs have a different set of possible commands. Please refer to the README of the firmware of your CUL to interpret the response of this command. See also the raw command.


• credit10ms
  One may send for a duration of credit10ms*10 ms before the send limit is reached and a LOVF is generated.


Attributes
• addvaltrigger
  Create triggers for additional device values. Right now these are RSSI and RAWMSG for the CUL family and RAWMSG for the FHZ.


• connectCommand
  raw culfw command sent to the CUL after a (re-)connect of the USB device, and sending the usual initialization needed for the configured rfmode.
• do_not_notify
• dummy
• hmId
  Set the HomeMatic ID of this device. If this attribute is absent, the ID will be F1<FHTID>. Note 1: After setting or changing this attribute you have to relearn all your HomeMatic devices. Note 2: The value must be a 6 digit hex number, and 000000 is not valid. FHEM won't complain if it is not correct, but the communication won't work.


• hmProtocolEvents
  Generate events for HomeMatic protocol messages. These are normally used for debugging, by activating "inform timer" in a telnet session, or looking at the Event Monitor window in the FHEMWEB frontend.
  Example:
  2012-05-17 09:44:22.515 CUL CULHM RCV L:0B N:81 CMD:A258 SRC:...... DST:...... 0000 (TYPE=88,WAKEMEUP,BIDI,RPTEN)


• longids
  Comma separated list of device-types for CUL that should be handled using long IDs. This additional ID allows it to differentiate some weather sensors, if they are sending on the same channel. Therefore a random generated id is added. If you choose to use longids, then you'll have to define a different device after battery change. Default is not to use long IDs.
  Modules which are using this functionality are for e.g. : 14_Hideki, 41_OREGON, 14_CUL_TCM97001, 14_SD_WS07.
  Examples:
  
  # Do not use any long IDs for any devices (this is default):
attr cul longids 0
# Use long IDs for all devices:
attr cul longids 1
# Use longids for SD_WS07 devices.
# Will generate devices names like SD_WS07_TH_3 for channel 3.
attr cul longids SD_WS07


• model (CUL,CUN,etc)


• noRawReadLog
  Do not log RAW read events at verbose 5, as sometimes makes this the log unreadable (Forum #122160).


• sendpool
  If using more than one CUL for covering a large area, sending different events by the different CUL's might disturb each other. This phenomenon is also known as the Palm-Beach-Resort effect. Putting them in a common sendpool will serialize sending the events. E.g. if you have three CUN's, you have to specify following attributes:
  attr CUN1 sendpool CUN1,CUN2,CUN3
attr CUN2 sendpool CUN1,CUN2,CUN3
attr CUN3 sendpool CUN1,CUN2,CUN3
  


• rfmode
  Configure the RF Transceiver of the CUL (the CC1101). Available arguments are:
  • SlowRF
    To communicate with FS20/FHT/HMS/EM1010/S300/Hoermann devices @1 kHz datarate. This is the default.
  • HomeMatic
    To communicate with HomeMatic type of devices @10 kHz datarate.
  • MAX
    To communicate with MAX! type of devices @10 kHz datarate.
  • WMBus_S
  • WMBus_T
  • WMBus_C
    To communicate with Wireless M-Bus devices like water, gas or electrical meters. Wireless M-Bus uses three different communication modes, S-Mode, T-Mode and C-Mode. While in this mode, no reception of other protocols like SlowRF or HomeMatic is possible. See also the WMBUS FHEM Module.


• showtime
• readingFnAttributes

CUL_EM

The CUL_EM module interprets EM type of messages received by the CUL, notably from EMEM, EMWZ or EMGZ devices.

Define
define <name> CUL_EM <code> [corr1 corr2 CostPerUnit BasicFeePerMonth]

<code> is the code which must be set on the EM device. Valid values are 1 through 12. 1-4 denotes EMWZ, 5-8 EMEM and 9-12 EMGZ devices.

corr1 is used to correct the current number, corr2 for the total number.
• for EMWZ devices you should specify the rotation speed (R/kW) of your watt-meter (e.g. 150) for corr1 and 12 times this value for corr2
• for EMEM devices the corr1 value is 0.01, and the corr2 value is 0.001

CostPerUnit and BasicFeePerMonth are used to compute your daily and monthly fees. Your COST will appear in the log, generated once daily (without the basic fee) or month (with the bassic fee included). Your definition should look like e.g.:
define emwz CUL_EM 1 75 900 0.15 12.50

and the Log looks like:
CUM_DAY: 6.849 CUM: 60123.4 COST: 1.02
CUM_MONTH: 212.319 CUM: 60123.4 COST: 44.34

Tip: You can configure your EMWZ device to show in the CUM column of the STATE reading the current reading of your meter. For this purpose: multiply the current reading (from the real device) with the corr1 value (RperKW), and subtract the RAW CUM value from it. Now set the basis reading of your EMWZ device (named emwz) to this value.


Set
N/A

Get
N/A

Attributes
• ignore


• do_not_notify


• showtime


• model (EMEM,EMWZ,EMGZ)


• IODev


• eventMap


• readingFnAttributes


• maxPeak <number>
  Specifies the maximum possible peak value for the EM meter ("TOP:" value in logfile). Peak values greater than this value are considered as EM read errors and are ignored. For example if it's not possible to consume more than 40kW of power set maxPeak to 40 to make the readings of the power meter more robust.


• CounterOffset
  Specifies the difference between true (gas) meter value and value reported by the EMGZ.
  CounterOffset = true Value - Reading "total"
  Example:
  attr Gaszaehler CounterOffset 15427.434
  

CUL_FHTTK

This module handles messages from the FHT80 TF "Fenster-Tür-Kontakt" (Window-Door-Contact) which are normally only acted upon by the FHT80B. With this module, FHT80 TFs are in a limited way (see Wiki for detailed explanation of TF's mode of operation) usable similar to HMS100 TFK. The name of the module was chosen as a) only CUL will spill out the datagrams and b) "TF" designates usually temperature+humidity sensors (no clue, why ELV didn't label this one "TFK" like with FS20 and HMS).

As said before, FHEM can receive FHT80 TF radio (868.35 MHz) messages only through an CUL device, so this must be defined first.

With the latest build on SVN or next official version 1.62 or higher, it is possible to send out FHT80 TF data with a CUL or simular devices. So it can be simulate up to four window sensor with one device (see FHEM Wiki). To setup a window sensor, you have to add and/or change the attribute "model" to virtual. The 6 digit hex number must not equal to FHTID.

Define
define <name> CUL_FHTTK <devicecode>

<devicecode> is a six digit hex number, given to the FHT80 TF during production, i. e. it is not changeable. (Yes, it keeps this code after changing batteries as well.)
Examples:
define TK_TEST CUL_FHTTK 965AB0

Set
Only available, if model is set to virtual.

set <name> <value>

where value is one of:

• Closed
  set window state to Closed


• Open
  set window state to Open


• Pair
  start pairing with FHT80B (activate FHT80B sync mode before) - state after pairing is Closed


• ReSync
  resync virtual sensor with FHT80b after a reset of CUL device. In other words, perform a virtual battery exchange to synchronize the sensor with FHT80b device again. (at the moment, only available with prototype cul fw - see forum 55774)



Special to the "ReSync" of existing FHT80TFs after a CUL firmware reset:
After a reset or restart of a CUL device, the connection between the FHT80B and the virtual FHT80TFs is interrupted. This is equivalent to a battery change. The contacts are still registered at the FHT80B. No new pairing is required. If multiple virtual contacts are used, it is recommended to synchronize them at large intervals!
Calling the CUL_FHTTK_ReSyncAll() function synchronizes all virtual window contacts successively with the FHT80B. The time interval between the individual sensors is 1 hour. This is determined by the 1% rule, since per contact 480 credits are consumed within 64 seconds!

Get
No get implemented yet ...

Attributes
• do_not_notify


• verbose


• model
  Possible values are: FHT80TF, FHT80TF-2, virtual (value, which allow to simulate a window sensor)


• showtime


• IODev


• ignore


• eventMap


• readingFnAttributes

CUL_HM

Support for eQ-3 HomeMatic devices via the CUL or the HMLAN.



Define

define <name> CUL_HM <6-digit-hex-code|8-digit-hex-code>

Correct device definition is the key for HM environment simple maintenance.
Background to define entities:
HM devices has a 3 byte (6 digit hex value) HMid - which is key for addressing. Each device hosts one or more channels. HMid for a channel is the device's HMid plus the channel number (1 byte, 2 digit) in hex. Channels should be defined for all multi-channel devices. Channel entities cannot be defined if the hosting device does not exist
Note: FHEM mappes channel 1 to the device if it is not defined explicitely. Therefore it does not need to be defined for single channel devices.
Note: if a device is deleted all assotiated channels will be removed as well.
An example for a full definition of a 2 channel switch is given below:

define livingRoomSwitch CUL_HM 123456
define LivingroomMainLight CUL_HM 12345601
define LivingroomBackLight CUL_HM 12345602


livingRoomSwitch is the device managing communication. This device is defined prior to channels to be able to setup references.
LivingroomMainLight is channel 01 dealing with status of light, channel peers and channel assotiated register. If not defined channel 01 is covered by the device entity.
LivingRoomBackLight is the second 'channel', channel 02. Its definition is mandatory to operate this function.

Sender specials: HM threats each button of remotes, push buttons and similar as channels. It is possible (not necessary) to define a channel per button. If all channels are defined access to pairing informatin is possible as well as access to channel related register. Furthermore names make the traces better readable.

define may also be invoked by the autocreate module, together with the necessary subType attribute. Usually you issue a hmPairForSec and press the corresponding button on the device to be paired, or issue a hmPairSerial set command if the device is a receiver and you know its serial number. Autocreate will then create a fhem device and set all necessary attributes. Without pairing the device will not accept messages from fhem. fhem may create the device even if the pairing is not successful. Upon a successful pairing you'll see a CommandAccepted entry in the details section of the CUL_HM device.

If you cannot use autocreate, then you have to specify:

• the <6-digit-hex-code>or HMid+ch <8-digit-hex-code>
  It is the unique, hardcoded device-address and cannot be changed (no, you cannot choose it arbitrarily like for FS20 devices). You may detect it by inspecting the fhem log.
• the subType attribute
  which is one of switch dimmer blindActuator remote sensor swi pushButton threeStateSensor motionDetector keyMatic winMatic smokeDetector
Without these attributes fhem won't be able to decode device messages appropriately.

Notes
• If the interface is a CUL device, the rfmode attribute of the corresponding CUL/CUN device must be set to HomeMatic. Note: this mode is BidCos/Homematic only, you will not receive FS20/HMS/EM/S300 messages via this device. Previously defined FS20/HMS etc devices must be assigned to a different input device (CUL/FHZ/etc).
• Currently supported device families: remote, switch, dimmer, blindActuator, motionDetector, smokeDetector, threeStateSensor, THSensor, winmatic. Special devices: KS550, HM-CC-TC and the KFM100.
• Device messages can only be interpreted correctly if the device type is known. fhem will extract the device type from a "pairing request" message, even if it won't respond to it (see hmPairSerial and hmPairForSec to enable pairing).
• The so called "AES-Encryption" is in reality a signing request: if it is enabled, an actor device will only execute a received command, if a correct answer to a request generated by the actor is received. This means:
  • Reaction to commands is noticably slower, as 3 messages are sent instead of one before the action is processed by the actor.
  • Every command and its final ack from the device is sent in clear, so an outside observer will know the status of each device.
  • The firmware implementation is buggy: the "toggle" event is executed before the answer for the signing request is received, at least by some switches (HM-LC-Sw1-Pl and HM-LC-SW2-PB-FM).
  • The HMLAN configurator will answer signing requests by itself, and if it is configured with the 3-byte address of a foreign CCU which is still configurerd with the default password, it is able to answer signing requests correctly.
  • AES-Encryption is useable with a HMLAN or a CUL. When using a CUL, the perl-module Crypt::Rijndael needs to be installed. Due to the issues above I do not recommend using Homematic encryption at all.



Set

Note: devices which are normally send-only (remote/sensor/etc) must be set into pairing/learning mode in order to receive the following commands.

Universal commands (available to most hm devices):
• assignHmKey
  Initiates a key-exchange with the device, exchanging the old AES-key of the device with the key with the highest index defined by the attribute hmKey* in the HMLAN or VCCU. The old key is determined by the reading aesKeyNbr, which specifies the index of the old key when the reading is divided by 2.
• clear <[rssi|readings|register|msgEvents|attack|all]>
  A set of variables or readings can be removed.
  
  readings: all readings are removed. Any new reading will be added usual. Used to eliminate old data.
  register: all captured register-readings in FHEM are removed. NO impact to the device.
  msgEvents: all message event counter are removed. Also commandstack is cleared.
  msgErrors: message-error counter are removed.
  rssi: collected rssi values are cleared.
  attack: information regarding an attack are removed.
  trigger: all trigger readings are removed.
  all: all of the above.
  
• getConfig
  Will read configuration of the physical HM device. Executed on a channel it reads peerings and register information.
  Executed on a device the command will retrieve configuration for ALL associated channels.
• getRegRaw [List0|List1|List2|List3|List4|List5|List6|List7]<peerChannel>
  Read registerset in raw format. Description of the registers is beyond the scope of this documentation.
  Registers are structured in so called lists each containing a set of registers.
  List0: device-level settings e.g. CUL-pairing or dimmer thermal limit settings.
  List1: per channel settings e.g. time to drive the blind up and down.
  List3: per 'link' settings - means per peer-channel. This is a lot of data!. It controlls actions taken upon receive of a trigger from the peer.
  List4: settings for channel (button) of a remote
  
  <PeerChannel> paired HMid+ch, i.e. 4 byte (8 digit) value like '12345601'. It is mendatory for List 3 and 4 and can be left out for List 0 and 1.
  'all' can be used to get data of each paired link of the channel.
  'selfxx' can be used to address data for internal channels (associated with the build-in switches if any). xx is the number of the channel in decimal.
  Note1: execution depends on the entity. If List1 is requested on a device rather then a channel the command will retrieve List1 for all channels assotiated. List3 with peerChannel = all will get all link for all channel if executed on a device.
  Note2: for 'sender' see remote
  Note3: the information retrieval may take a while - especially for devices with a lot of channels and links. It may be necessary to refresh the web interface manually to view the results
  Note4: the direct buttons on a HM device are hidden by default. Nevertheless those are implemented as links as well. To get access to the 'internal links' it is necessary to issue
  'set <name> regSet intKeyVisib visib'
  or
  'set <name> regBulk RegL_0. 2:81'
  Reset it by replacing '81' with '01'
  example:
  
  set mydimmer getRegRaw List1
set mydimmer getRegRaw List3 all

• getSerial
  Read serial number from device and write it to attribute serialNr.
• inhibit [on|off]
  Block / unblock all changes to the actor channel, i.e. actor state is frozen until inhibit is set off again. Inhibit can be executed on any actor channel but obviously not on sensors - would not make any sense.
  Practically it can be used to suspend any notifies as well as peered channel action temporarily without the need to delete them.
  Examples:
  # Block operation
set keymatic inhibit on


• pair
  Pair the device with a known serialNumber (e.g. after a device reset) to FHEM Central unit. FHEM Central is usualy represented by CUL/CUNO, HMLAN,... If paired, devices will report status information to FHEM. If not paired, the device won't respond to some requests, and certain status information is also not reported. Paring is on device level. Channels cannot be paired to central separate from the device. See also getPair and unpair.
  Don't confuse pair (to a central) with peer (channel to channel) with peerChan.
  
• peerBulk <peerch1,peerch2,...> [set|unset]
  peerBulk will add peer channels to the channel. All peers in the list will be added.
  with unset option the peers in the list will be subtracted from the device's peerList.
  peering sets the configuration of this link to its defaults. As peers are not added in pairs default will be as defined for 'single' by HM for this device.
  More suffisticated funktionality is provided by peerChan.
  peerBulk will not delete existing peers, just handle the given peerlist. Other already installed peers will not be touched.
  peerBulk may be used to remove peers using unset option while default ist set.
  Main purpose of this command is to re-store data to a device. It is recommended to restore register configuration utilising regBulk subsequent.
  Example:
  
  set myChannel peerBulk 12345601,
set myChannel peerBulk self01,self02,FB_Btn_04,FB_Btn_03,
set myChannel peerBulk 12345601 unset # remove peer 123456 channel 01

• regBulk <reg List>.<peer> <addr1:data1> <addr2:data2>...
  This command will replace the former regRaw. It allows to set register in raw format. Its main purpose is to restore a complete register list to values secured before.
  Values may be read by getConfig. The resulting readings can be used directly for this command.
  <reg List> is the list data should be written to. Format could be '00', 'RegL_00', '01'...
  <peer> is an optional adder in case the list requires a peer. The peer can be given as channel name or the 4 byte (8 chars) HM channel ID.
  <addr1:data1> is the list of register to be written in hex format.
  Example:
  
  set myChannel regBulk RegL_00. 02:01 0A:17 0B:43 0C:BF 15:FF 00:00
RegL_03.FB_Btn_07 01:00 02:00 03:00 04:32 05:64 06:00 07:FF 08:00 09:FF 0A:01 0B:44 0C:54 0D:93 0E:00 0F:00 11:C8 12:00 13:00 14:00 15:00 16:00 17:00 18:00 19:00 1A:00 1B:00 1C:00 1D:FF 1E:93 1F:00 81:00 82:00 83:00 84:32 85:64 86:00 87:FF 88:00 89:FF 8A:21 8B:44 8C:54 8D:93 8E:00 8F:00 91:C8 92:00 93:00 94:00 95:00 96:00 97:00 98:00 99:00 9A:00 9B:00 9C:00 9D:05 9E:93 9F:00 00:00
set myblind regBulk 01 0B:10
set myblind regBulk 01 0C:00

  myblind will set the max drive time up for a blind actor to 25,6sec
• regSet [prep|exec] <regName> <value> <peerChannel>
  For some major register a readable version is implemented supporting register names <regName> and value conversionsing. Only a subset of register can be supproted.
  Optional parameter [prep|exec] allowes to pack the messages and therefore greatly improve data transmission. Usage is to send the commands with paramenter "prep". The data will be accumulated for send. The last command must have the parameter "exec" in order to transmitt the information.
  <value> is the data in human readable manner that will be written to the register.
  <peerChannel> is required if this register is defined on a per 'peerChan' base. It can be set to '0' other wise.See getRegRaw for full description
  Supported register for a device can be explored using
  
  set regSet ? 0 0
  Condensed register description will be printed using
  
  set regSet <regname> ? 0
• reset
  Factory reset the device. You need to pair it again to use it with fhem.
• sign [on|off]
  Activate or deactivate signing (also called AES encryption, see the note above). Warning: if the device is attached via a CUL, you need to install the perl-module Crypt::Rijndael to be able to switch it (or deactivate signing) from fhem.
• statusRequest
  Update device status. For multichannel devices it should be issued on an per channel base
• unpair
  "Unpair" the device, i.e. make it available to pair with other master devices. See pair for description.
• virtual <number of buttons>
  configures a defined curcuit as virtual remote controll. Then number of button being added is 1 to 255. If the command is issued a second time for the same entity additional buttons will be added.
  Example for usage:
  define vRemote CUL_HM 100000 # the selected HMid must not be in use
set vRemote virtual 20 # define 20 button remote controll
set vRemote_Btn4 peerChan 0 <actorchannel> # peers Button 4 and 5 to the given channel
set vRemote_Btn4 press
set vRemote_Btn5 press long

  see also press
• deviceRename <newName>
  rename the device and all its channels.
• fwUpdate [onlyEnterBootLoader] <filename> [<waitTime>]
  update Fw of the device. User must provide the appropriate file. waitTime can be given optionally. In case the device needs to be set to FW update mode manually this is the time the system will wait.
  "onlyEnterBootLoader" tells the device to enter the boot loader so it can be flashed using the eq3 firmware update tool. Mainly useful for flush-mounted devices in FHEM environments solely using HM-LAN adapters.
• assignIO <IOname> <set|unset>
  Add or remove an IO device to the list of available IO's. Changes attribute IOList accordingly.

subType dependent commands:


• switch
  • on - set level to 100%
  • off - set level to 0%
  • on-for-timer <sec> - set the switch on for the given seconds [0-85825945].
    Note: off-for-timer like FS20 is not supported. It may to be programmed thru channel register.
  • on-till <time> - set the switch on for the given end time.
    
    set <name> on-till 20:32:10

    Currently a max of 24h is supported with endtime.
    
  • pressL <peer> [<repCount>] [<repDelay>]
    simulate a press of the local button or direct connected switch of the actor.
    <peer> allows to stimulate button-press of any peer of the actor. i.e. if the actor is peered to any remote, virtual or io (HMLAN/CUL) press can trigger the action defined.
    <repCount> number of automatic repetitions.
    <repDelay> timer between automatic repetitions.
    Example: set actor pressL FB_Btn01 # trigger long peer FB button 01
set actor pressL FB_chn-8 # trigger long peer FB button 08
set actor pressL self01 # trigger short of internal peer 01
set actor pressL fhem02 # trigger short of FHEM channel 2

  • pressS <peer>
    simulates a short press similar to long press
  • eventL <peer> <condition> [<repCount>] [<repDelay>]
    simulate an event of an peer and stimulates the actor.
    <peer> allows to stimulate button-press of any peer of the actor. i.e. if the actor is peered to any remote, virtual or io (HMLAN/CUL) press can trigger the action defined.
    <codition> the level of the condition
    Example: set actor eventL md 30 # trigger from motion detector with level 30

  • eventS <peer> <condition>
    simulates a short event from a peer of the actor. Typically sensor do not send long events.
  • toggle - toggle the Actor. It will switch from any current level to off or from off to 100%
  
  
• dimmer, blindActuator
  Dimmer may support virtual channels. Those are autocrated if applicable. Usually there are 2 virtual channels in addition to the primary channel. Virtual dimmer channels are inactive by default but can be used in in parallel to the primay channel to control light.
  Virtual channels have default naming SW<channel>_V<no>. e.g. Dimmer_SW1_V1 and Dimmer_SW1_V2.
  Dimmer virtual channels are completely different from FHEM virtual buttons and actors but are part of the HM device. Documentation and capabilities for virtual channels is out of scope.
  
  • 0 - 100 [on-time] [ramp-time]
    set the actuator to the given value (in percent) with a resolution of 0.5.
    Optional for dimmer on-time and ramp time can be choosen, both in seconds with 0.1s granularity.
    On-time is analog "on-for-timer".
    Ramp-time default is 2.5s, 0 means instantanous
    
  • on
  • off
  • press <[short|long]><[on|off]>
  • toggle
  • toggleDir - toggled drive direction between up/stop/down/stop
  • on-for-timer <sec> - Dimmer only!
    
  • on-till <time> - Dimmer only!
    
  • stop - stop motion (blind) or dim ramp
  • old - switch back to old value after a change. Dimmer only.
  • pct <level> [<ontime>] [<ramptime>] - set actor to a desired absolut level.
    Optional ontime and ramptime could be given for dimmer.
    ontime may be time in seconds. It may also be entered as end-time in format hh:mm:ss
  • up [changeValue] [<ontime>] [<ramptime>] dim up one step
  • down [changeValue] [<ontime>] [<ramptime>] dim up one step
    changeValue is optional an gives the level to be changed up or down in percent. Granularity is 0.5%, default is 10%.
    ontime is optional an gives the duration of the level to be kept. '0' means forever and is default.
    ramptime is optional an defines the change speed to reach the new level. It is meaningful only for dimmer.
    
  
  
• remotes, pushButton
  This class of devices does not react on requests unless they are put to learn mode. FHEM obeys this behavior by stacking all requests until learn mode is detected. Manual interaction of the user is necessary to activate learn mode. Whether commands are pending is reported on device level with parameter 'protCmdPend'.
• trgEventS [all|<peer>] <condition>
  Issue eventS on the peer entity. If all is selected each of the peers will be triggered. See also eventS
  <condition>: is the condition being transmitted with the event. E.g. the brightness in case of a motion detector.
• trgEventL [all|<peer>] <condition>
  Issue eventL on the peer entity. If all is selected each of the peers will be triggered. a normal device will not sent event long. See also eventL
  <condition>: is the condition being transmitted with the event. E.g. the brightness in case of a motion detector.
• trgPressS [all|<peer>]
  Issue pressS on the peer entity. If all is selected each of the peers will be triggered. See also pressS
  
• trgPressL [all|<peer>]
  Issue pressL on the peer entity. If all is selected each of the peers will be triggered. See also pressL
  
• peerIODev [IO] <btn_no> [set|unset]
  The command is similar to peerChan. While peerChan is executed on a remote and peers any remote to any actor channel peerIODev is executed on an actor channel and peer this to an channel of an FHEM IO device.
  An IO device according to eQ3 supports up to 50 virtual buttons. Those will be peered/unpeerd to the actor. press can be used to stimulate the related actions as defined in the actor register.
• peerSmart [<peer>]
  The command is similar to peerChan with reduced options for peer and unpeer.
  peerSmart peers in single mode (see peerChan) while funktionallity should be defined by setting register (not much difference to peerChan).
  Smart register setting could be done using hmTemplate.
• peerChan <btn_no> <actChan> [single|dual|reverse][set|unset] [both|actor|remote]
  peerChan will establish a connection between a sender- channel and an actuator-channel called link in HM nomenclatur. Peering must not be confused with pairing.
  Pairing refers to assign a device to the central.
  Peering refers to virtally connect two channels.
  Peering allowes direkt interaction between sender and aktor without the necessity of a CCU
  Peering a sender-channel causes the sender to expect an ack from -each- of its peers after sending a trigger. It will give positive feedback (e.g. LED green) only if all peers acknowledged.
  Peering an aktor-channel will setup a parameter set which defines the action to be taken once a trigger from -this- peer arrived. In other words an aktor will
  - process trigger from peers only
  - define the action to be taken dedicated for each peer's trigger
  An actor channel will setup a default action upon peering - which is actor dependant. It may also depend whether one or 2 buttons are peered in one command. A swich may setup oen button for 'on' and the other for 'off' if 2 button are peered. If only one button is peered the funktion will likely be 'toggle'.
  The funtion can be modified by programming the register (aktor dependant).
  Even though the command is executed on a remote or push-button it will as well take effect on the actuator directly. Both sides' peering is virtually independant and has different impact on sender and receiver side.
  Peering of one actuator-channel to multiple sender-channel as well as one sender-channel to multiple Actuator-channel is possible.
  <actChan> is the actuator-channel to be peered.
  <btn_no> is the sender-channel (button) to be peered. If 'single' is choosen buttons are counted from 1. For 'dual' btn_no is the number of the Button-pair to be used. I.e. '3' in dual is the 3rd button pair correcponding to button 5 and 6 in single mode.
  If the command is executed on a channel the btn_no is ignored. It needs to be set, should be 0
  [single|dual]: this mode impacts the default behavior of the Actuator upon using this button. E.g. a dimmer can be learned to a single button or to a button pair.
  Defaults to dual.
  'dual' (default) Button pairs two buttons to one actuator. With a dimmer this means one button for dim-up and one for dim-down.
  'reverse' identical to dual - but button order is reverse.
  'single' uses only one button of the sender. It is useful for e.g. for simple switch actuator to toggle on/off. Nevertheless also dimmer can be learned to only one button.
  [set|unset]: selects either enter a peering or remove it.
  Defaults to set.
  'set' will setup peering for the channels
  'unset' will remove the peering for the channels
  [actor|remote|both] limits the execution to only actor or only remote. This gives the user the option to redo the peering on the remote channel while the settings in the actor will not be removed.
  Defaults to both.
  Example:
  set myRemote peerChan 2 mySwActChn single set #peer second button to an actuator channel
set myRmtBtn peerChan 0 mySwActChn single set #myRmtBtn is a button of the remote. '0' is not processed here
set myRemote peerChan 2 mySwActChn dual set #peer button 3 and 4
set myRemote peerChan 3 mySwActChn dual unset #remove peering for button 5 and 6
set myRemote peerChan 3 mySwActChn dual unset aktor #remove peering for button 5 and 6 in actor only
set myRemote peerChan 3 mySwActChn dual set remote #peer button 5 and 6 on remote only. Link settings il mySwActChn will be maintained

• virtual
  
  • peerChan see remote
  • press [long|short] [<peer>] [<repCount>] [<repDelay>]
    simulates button press for an actor from a peered sensor. will be sent of type "long".
    • [long|short] defines whether long or short press shall be simulated. Defaults to short
    • [<peer>] define which peer's trigger shall be simulated.Defaults to self(channelNo).
    • [<repCount>] Valid for long press only. How long shall the button be pressed? Number of repetition of the messages is defined. Defaults to 1
    • [<repDelay>] Valid for long press only. defines wait time between the single messages.
  • virtTemp <[off -10..50]> simulates a thermostat. If peered to a device it periodically sends the temperature until "off" is given. See also virtHum
    
  • virtHum <[off -10..50]> simulates the humidity part of a thermostat. If peered to a device it periodically sends the temperature and humidity until both are "off". See also virtTemp
    
  • valvePos <[off 0..100]> stimulates a VD
    
• smokeDetector
  Note: All these commands work right now only if you have more then one smoekDetector, and you peered them to form a group. For issuing the commands you have to use the master of this group, and currently you have to guess which of the detectors is the master.
  smokeDetector can be setup to teams using peerChan. You need to peer all team-members to the master. Don't forget to also peerChan the master itself to the team - i.e. peer it to itself! doing that you have full controll over the team and don't need to guess.
  
  • teamCall - execute a network test to all team members
  • teamCallBat - execute a network test simulate bat low
  • alarmOn - initiate an alarm
  • alarmOff - switch off the alarm
• 4Dis (HM-PB-4DIS-WM|HM-RC-DIS-H-X-EU|ROTO_ZEL-STG-RM-DWT-10)
  • text <btn_no> [on|off] <text1> <text2>
    Set the text on the display of the device. To this purpose issue this set command first (or a number of them), and then choose from the teach-in menu of the 4Dis the "Central" to transmit the data.
    If used on a channel btn_no and on|off must not be given but only pure text.
    \_ will be replaced by blank character.
    Example:
    set 4Dis text 1 on On Lamp
set 4Dis text 1 off Kitchen Off

set 4Dis_chn4 text Kitchen Off

  
  
• Climate-Control (HM-CC-TC)
  • desired-temp <temp>
    Set different temperatures. <temp> must be between 6 and 30 Celsius, and precision is half a degree.
  • tempListSat [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListSun [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListMon [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListTue [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListThu [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListWed [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListFri [prep|exec] HH:MM temp ... 24:00 temp
    Specify a list of temperature intervals. Up to 24 intervals can be specified for each week day, the resolution is 10 Minutes. The last time spec must always be 24:00.
    Example: until 6:00 temperature shall be 19, from then until 23:00 temperature shall be 22.5, thereafter until midnight, 19 degrees celsius is desired.
    set th tempListSat 06:00 19 23:00 22.5 24:00 19

  
  
  • tempListTmpl =>"[verify|restore] [[ <file> :]templateName] ...
    The tempList for one or more devices can be stored in a file. User can compare the tempList in the file with the data read from the device.
    Restore will write the tempList to the device.
    Default opeartion is verify.
    Default file is tempList.cfg.
    Default templateName is the name of the actor
    Default for file and templateName can be set with attribut tempListTmpl
    Example for templist file. room1 and room2 are the names of the template:
    entities:room1 tempListSat>08:00 16.0 15:00 18.0 21:30 19.0 24:00 14.0 tempListSun>08:00 16.0 15:00 18.0 21:30 19.0 24:00 14.0 tempListMon>07:00 16.0 16:00 18.0 21:00 19.0 24:00 14.0 tempListTue>07:00 16.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 15.0 tempListWed>07:00 16.0 16:00 18.0 21:00 19.0 24:00 14.0 tempListThu>07:00 16.0 16:00 18.0 21:00 19.0 24:00 14.0 tempListFri>07:00 16.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 14.0 entities:room2 tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0 tempListSun>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0 tempListMon>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0 tempListTue>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 15.0 tempListWed>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0 tempListThu>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0 tempListFri>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 14.0 Specials:
    
  • none: template will be ignored
  • defaultWeekplan: as default each day is set to 18.0 degree. useful if peered to a TC controller. Implicitely teh weekplan of TC will be used.
  • tempTmplSet =>"[[ <file> :]templateName]
    Set the attribut and apply the change to the device
  • tplDel =>" <template>
    Delete template entry for this entity
  • tplSet_<peer> =>" <template>
    Set a template for a peer of the entity. Possible parameter will be set to the current register value of the device - i.e. no change to the register. Parameter may be changed after assigning the template by using the tplPara command.
    The command is avalilable if HMinfo is defined and a tamplate fitting the combination is available. Note that the register of the device need to be available (see getConfig command).
    In case of dedicated template for long and short trigger separat commands will be available.
  • tplParaxxx_<peer>_<tpl>_<param> =>" <template>
    A parameter of an assigned template can be modified. A command s available for each parameter of each assigned template.
  • partyMode <HH:MM><durationDays>
    set control mode to party and device ending time. Add the time it ends and the number of days it shall last. If it shall end next day '1' must be entered
    
  • sysTime
    set time in climate channel to system time
  
  
• Climate-Control (HM-CC-RT-DN|HM-CC-RT-DN-BOM)
  • controlMode <auto|boost|day|night>
    
  • controlManu <temp>
    
  • controlParty <temp><startDate><startTime><endDate><endTime>
    set control mode to party, define temp and timeframe.
    example:
    set controlParty 15 03-8-13 20:30 5-8-13 11:30
  • sysTime
    set time in climate channel to system time
  • desired-temp <temp>
    Set different temperatures. <temp> must be between 6 and 30 Celsius, and precision is half a degree.
  • tempListSat [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListSun [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListMon [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListTue [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListThu [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListWed [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListFri [prep|exec] HH:MM temp ... 24:00 temp
    Specify a list of temperature intervals. Up to 24 intervals can be specified for each week day, the resolution is 10 Minutes. The last time spec must always be 24:00.
    Optional parameter [prep|exec] allowes to pack the messages and therefore greatly improve data transmission. This is especially helpful if device is operated in wakeup mode. Usage is to send the commands with paramenter "prep". The data will be accumulated for send. The last command must have the parameter "exec" in order to transmitt the information.
    Example: until 6:00 temperature shall be 19, from then until 23:00 temperature shall be 22.5, thereafter until midnight, 19 degrees celsius is desired.
    set th tempListSat 06:00 19 23:00 22.5 24:00 19

set th tempListSat prep 06:00 19 23:00 22.5 24:00 19
set th tempListSun prep 06:00 19 23:00 22.5 24:00 19
set th tempListMon prep 06:00 19 23:00 22.5 24:00 19
set th tempListTue exec 06:00 19 23:00 22.5 24:00 19

  
  
• OutputUnit (HM-OU-LED16)
  • led [off|red|green|yellow]
    switches the LED of the channel to the color. If the command is executed on a device it will set all LEDs to the specified color.
    For Expert all LEDs can be set individual by providing a 8-digit hex number to the device.
    
  • ilum <brightness><duration>
    <brightness> [0-15] of backlight.
    <duration> [0-127] in sec. 0 is permanent 'on'.
    
  
  
• OutputUnit (HM-OU-CFM-PL)
  • led <color>[,<color>..] [<repeat>..]
    Possible colors are [redL|greenL|yellowL|redS|greenS|yellowS|pause]. A sequence of colors can be given separating the color entries by ','. White spaces must not be used in the list. 'S' indicates short and 'L' long ilumination.
    repeat defines how often the sequence shall be executed. Defaults to 1.
    
  • playTone <MP3No>[,<MP3No>..] [<repeat>] [<volume>]
    Play a series of tones. List is to be entered separated by ','. White spaces must not be used in the list.
    replay can be entered to repeat the last sound played once more.
    repeat defines how often the sequence shall be played. Defaults to 1.
    volume is defined between 0 and 10. 0 stops any sound currently playing. Defaults to 10 (100%).
    Example:
    # "hello" in display, symb bulb on, backlight, beep
set cfm_Mp3 playTone 3 # MP3 title 3 once
set cfm_Mp3 playTone 3 3 # MP3 title 3 3 times
set cfm_Mp3 playTone 3,6,8,3,4 # MP3 title list 3,6,8,3,4 once
set cfm_Mp3 playTone 3,6,8,3,4 255# MP3 title list 3,6,8,3,4 255 times
set cfm_Mp3 playTone replay # repeat last sequence

set cfm_Led led redL 4 # led red blink 3 times long
set cfm_Led led redS,redS,redS,redL,redL,redL,redS,redS,redS 255 # SOS 255 times

  
  
• HM-RC-19xxx
  • alarm <count>
    issue an alarm message to the remote
    
  • service <count>
    issue an service message to the remote
    
  • symbol <symbol> [set|unset]
    activate a symbol as available on the remote.
    
  • beep [off|1|2|3]
    activate tone
    
  • backlight [off|on|slow|fast]
    activate backlight
    
  • display <text> comma unit tone backlight <symbol(s)>
    control display of the remote
    <text> : up to 5 chars
    comma : 'comma' activates the comma, 'no' leaves it off
    [unit] : set the unit symbols. [off|Proz|Watt|x3|C|x5|x6|x7|F|x9|x10|x11|x12|x13|x14|x15]. Currently the x3..x15 display is not tested.
    tone : activate one of the 3 tones [off|1|2|3]
    backlight: activate backlight flash mode [off|on|slow|fast]
    <symbol(s)> activate symbol display. Multople symbols can be acticated at the same time, concatinating them comma separated. Don't use spaces here. Possiblesymbols are [bulb|switch|window|door|blind|scene|phone|bell|clock|arrowUp|arrowDown]
    
    Example:
    # "hello" in display, symb bulb on, backlight, beep
set FB1 display Hello no off 1 on bulb
# "1234,5" in display with unit 'W'. Symbols scene,phone,bell and # clock are active. Backlight flashing fast, Beep is second tone
set FB1 display 12345 comma Watt 2 fast scene,phone,bell,clock
  
  
• HM-DIS-WM55
  • displayWM help
    displayWM [long|short] <text1> <color1> <icon1> ... <text6> <color6> <icon6>
    displayWM [long|short] <lineX> <text> <color> <icon>
    up to 6 lines can be addressed.
    lineX line number that shall be changed. If this is set the 3 parameter of a line can be adapted.
    textNo is the text to be dispalyed in line No. The text is assotiated with the text defined for the buttons. txt<BtnNo>_<lineNo> references channel 1 to 10 and their lines 1 or 2. Alternaly a free text of up to 12 char can be used
    color is one white, red, orange, yellow, green, blue
    icon is one off, on, open, closed, error, ok, noIcon
    Example:
    set disp01 displayWM short txt02_2 green noIcon txt10_1 red error txt05_2 yellow closed txt02_2 orange open
set disp01 displayWM long line3 txt02_2 green noIcon
set disp01 displayWM long line2 nc yellow noIcon
set disp01 displayWM long line6 txt02_2
set disp01 displayWM long line1 nc nc closed

  
  
• HM-DIS-EP-WM55
  • displayEP help
    displayEP <text1,icon1:text2,icon2:text3,icon3> <sound> <repetition> <pause> <signal>
    up to 3 lines can be addressed.
    If help is given a help on the command is given. Options for all parameter will be given.
    textx 12 char text for the given line. If empty the value as per reading will be transmittet - i.e. typically no change. text0-9 will display predefined text of channels 4 to 8. 0xHH allows to display a single char in hex format.
    iconx Icon for this line. If empty the value as per reading will be transmittet - i.e. typically no change.
    sound sound to be played
    repetition 0..15
    pause 1..160
    signal signal color to be displayed
    
    Note: param reWriteDisplayxx
    
  • upon button press the device will overwrite the 3 middles lines. When set
    attr chan param reWriteDisplayxx
    the 3 lines will be rewritten to the latest value after xx seconds. xx is between 01 and 99
    
  
  
• keyMatic
  
  
  The Keymatic uses the AES signed communication. Control of the Keymatic is possible with the HM-LAN adapter and the CUL. To control the KeyMatic with a CUL, the perl-module Crypt::Rijndael needs to be installed.
  
  
  • lock
    The lock bolt moves to the locking position
    
  • unlock [sec]
    The lock bolt moves to the unlocking position.
    [sec]: Sets the delay in seconds after the lock automatically locked again.
    0 - 65535 seconds
  • open [sec]
    Unlocked the door so that the door can be opened.
    [sec]: Sets the delay in seconds after the lock automatically locked again.
    0 - 65535 seconds
• winMatic
  
  
  winMatic provides 2 channels, one for the window control and a second for the accumulator.
  
  
  • level <level> <relockDelay> <speed>
    set the level.
    <level>: range is 0 to 100%
    <relockDelay>: range 0 to 65535 sec. 'ignore' can be used to igneore the value alternaly
    <speed>: range is 0 to 100%
    
  • stop
    stop movement
    
• CCU_FHEM
  
  • defIgnUnknown
    define unknown devices which are present in the readings. set attr ignore and remove the readingfrom the list.
    
• HM-SYS-SRP-PL
  
  setup the repeater's entries. Up to 36entries can be applied.
  • setRepeat <entry> <sender> <receiver> <broadcast>
    <entry> [1..36] entry number in repeater table. The repeater can handle up to 36 entries.
    <sender> name or HMID of the sender or source which shall be repeated
    <receiver> name or HMID of the receiver or destination which shall be repeated
    <broadcast> [yes|no] determines whether broadcast from this ID shall be repeated
    
    short application:
    setRepeat setAll 0 0 0
will rewrite the complete list to the deivce. Data will be taken from attribut repPeers.
    attribut repPeers is formated:
    src1:dst1:[y/n],src2:dst2:[y/n],src2:dst2:[y/n],...
    
    Reading repPeer is formated:
    
    Number src dst broadcast verify
    number: entry sequence number
    src: message source device - read from repeater
    dst: message destination device - assembled from attributes
    broadcast: shall broadcast be repeated for this source - read from repeater
    verify: do attributes and readings match?
    

Debugging:
• raw <data> ...
  Only needed for experimentation. send a "raw" command. The length will be computed automatically, and the message counter will be incremented if the first two charcters are ++. Example (enable AES):

               set hm1 raw ++A001F100001234560105000000001




Get



• configSave <filename>
  Saves the configuration of an entity into a file. Data is stored in a format to be executed from fhem command prompt.
  The file is located in the fhem home directory aside of fhem.cfg. Data will be stored cumulative - i.e. new data will be appended to the file. It is up to the user to avoid duplicate storage of the same entity.
  Target of the data is ONLY the HM-device information which is located IN the HM device. Explicitely this is the peer-list and the register. With the register also the peering is included.
  The file is readable and editable by the user. Additionaly timestamps are stored to help user to validate.
  Restrictions:
  Even though all data of the entity will be secured to the file FHEM stores the data that is avalilable to FHEM at time of save!. It is up to the user to read the data from the HM-hardware prior to execution. See recommended flow below.
  This command will not store any FHEM attributes o device definitions. This continues to remain in fhem.cfg.
  Furthermore the secured data will not automatically be reloaded to the HM-hardware. It is up to the user to perform a restore.
  
  As with other commands also 'configSave' is best executed on a device rather then on a channel. If executed on a device also the assotiated channel data will be secured.
  
  Recommended work-order for device 'HMdev':
set HMdev clear msgEvents # clear old events to better check flow
set HMdev getConfig # read device & channel inforamtion
# wait until operation is complete
# protState should be CMDs_done
# there shall be no warnings amongst prot... variables
get configSave myActorFile

• param <paramName>
  returns the content of the relevant parameter for the entity.
  Note: if this command is executed on a channel and 'model' is requested the content hosting device's 'model' will be returned.
• reg <addr> <list> <peerID>
  returns the value of a register. The data is taken from the storage in FHEM and not read directly outof the device. If register content is not present please use getConfig, getReg in advance.
  <addr> address in hex of the register. Registername can be used alternaly if decoded by FHEM. "all" will return all decoded register for this entity in one list.
  <list> list from which the register is taken. If rgistername is used list is ignored and can be set to 0.
  <peerID> identifies the registerbank in case of list3 and list4. It an be set to dummy if not used.
  
• regVal <addr> <list> <peerID>
  returns the value of a register. It does the same as reg but strips off units
  
• regList
  returns a list of register that are decoded by FHEM for this device.
  Note that there could be more register implemented for a device.
  
• saveConfig <file>
  stores peers and register to the file.
  Stored will be the data as available in fhem. It is necessary to read the information from the device prior to the save.
  The command supports device-level action. I.e. if executed on a device also all related channel entities will be stored implicitely.
  Storage to the file will be cumulative. If an entity is stored multiple times to the same file data will be appended. User can identify time of storage in the file if necessary.
  Content of the file can be used to restore device configuration. It will restore all peers and all register to the entity.
  Constrains/Restrictions:
  prior to rewrite data to an entity it is necessary to pair the device with FHEM.
  restore will not delete any peered channels, it will just add peer channels.
  
• list (normal|hidden);
  issue list command for the fiven entity normal or including the hidden parameter
• listDevice
  
  • when used with ccu it returns a list of Devices using the ccu service to assign an IO.
    
  • when used with ActionDetector user will get a comma separated list of entities being assigned to the action detector
    get ActionDetector listDevice # returns all assigned entities
    get ActionDetector listDevice notActive# returns entities which habe not status alive
    get ActionDetector listDevice alive # returns entities with status alive
    get ActionDetector listDevice unknown # returns entities with status unknown
    get ActionDetector listDevice dead # returns entities with status dead
    
• info
  
  • provides information about entities using ActionDetector
    



Attributes

• eventMap
• do_not_notify
• ignore
• dummy
• showtime
• readingFnAttributes
• actAutoTry
  actAutoTry 0_off,1_on
  setting this option enables Action Detector to send a statusrequest in case of a device is going to be marked dead. The attribut may be useful in case a device is being checked that does not send messages regularely - e.g. an ordinary switch.
• actCycle <[hhh:mm]|off>
  Supports 'alive' or better 'not alive' detection for devices. [hhh:mm] is the maximum silent time for the device. Upon no message received in this period an event will be raised "<device> is dead". If the device sends again another notification is posted "<device> is alive".
  This actiondetect will be autocreated for each device with build in cyclic status report.
  Controlling entity is a pseudo device "ActionDetector" with HMId "000000".
  Due to performance considerations the report latency is set to 600sec (10min). It can be controlled by the attribute "actCycle" of "ActionDetector".
  Once entered to the supervision the HM device has 2 attributes:
  
  actStatus: activity status of the device
  actCycle: detection period [hhh:mm]
  
  The overall function can be viewed checking out the "ActionDetector" entity. The status of all entities is present in the READING section.
  Note: This function can be enabled for devices with non-cyclic messages as well. It is up to the user to enter a reasonable cycletime.
• actStatus
  readonly
  This attribut is set by ActionDetector. It cannot be set manually
• aesCommReq
  if set IO is forced to request AES signature before sending ACK to the device.
  Defautls to 0
  
• aesKey
  specifies which aes key is to be used if aesCommReq is active
  
• autoReadReg
  '0' autoReadReg will be ignored.
  '1' will execute a getConfig for the device automatically after each reboot of FHEM.
  '2' like '1' plus execute after power_on.
  '3' includes '2' plus updates on writes to the device
  '4' includes '3' plus tries to request status if it seems to be missing
  '5' checks reglist and peerlist. If reading seems incomplete getConfig will be scheduled
  '8_stateOnly' will only update status information but not configuration data like register and peer
  Execution will be delayed in order to prevent congestion at startup. Therefore the update of the readings and the display will be delayed depending on the size of the database.
  Recommendations and constrains upon usage:
  
  usage on devices which only react to 'config' mode is not recommended since executen will not start until config is triggered by the user
  usage on devices which support wakeup-mode is usefull. But consider that execution is delayed until the device "wakes up".
  
• burstAccess
  can be set for the device entity if the model allowes conditionalBurst. The attribut will switch off burst operations (0_off) which causes less message load on HMLAN and therefore reduces the chance of HMLAN overload.
  Setting it on (1_auto) allowes shorter reaction time of the device. User does not need to wait for the device to wake up.
  Note that also the register burstRx needs to be set in the device.
• expert <option1[[,option2],...]>
  This attribut controls the visibility of the register readings. This attibute controls the presentation of device parameter in readings.
  Options are:
  
  defReg : default register
  allReg : all register
  rawReg : raw reading
  templ : template assiciation
  none : no register
  
  If expert is applied to the device it is used for assotiated channels if not overwritten by it.
  
• communication status copied to channel reading
  on: device communication status not visible in channel entities
  off: device communication status commState is visiblein channel entities
  
• firmware <FWversion>
  Firmware version of the device. Should not be overwritten.
• hmKey <key>
  AES key to be used
• hmProtocolEvents
  parses and logs the device messages. This is performance consuming and may disturb the timing. Use with care.
  Options:
  
  0_off : no parsing - default
  1_dump : log all messages
  2_dumpFull : log with extended parsing
  3_dumpTrigger : log full and include trigger events
  
• readOnly
  1: restricts commands to read od observ only.
• readingOnDead
  defines how readings shall be treated upon device is marked 'dead'.
  The attribute is applicable for devices only. It will modify the readings upon entering dead of the device. Upon leaving state 'dead' the selected readings will be set to 'notDead'. It is expected that useful values will be filled by the normally operating device.
  Options are:
  noChange: no readings will be changed upon entering 'dead' except Actvity. Other valvues will be ignored
  state: set the entites 'state' readings to dead
  periodValues: set periodic numeric readings of the device to '0'
  periodString: set periodic string readings of the device to 'dead'
  channels: if set the device's channels will be effected identical to the device entity
  custom readings: customer may add a list of other readings that will be set to 'dead'
  
  Example:
  
  attr myDevice readingOnDead noChange,state # no dead marking - noChange has priority
attr myDevice readingOnDead state,periodValues,channels # Recommended. reading state of the device and all its channels will be set to 'dead'. Periodic numerical readings will be set to 0 which influences graphics
attr myDevice readingOnDead state,channels # reading state of the device and all its channels will be set to 'dead'.
attr myDevice readingOnDead periodValues,channels # numeric periodic readings of device and channels will be set to '0'
attr myDevice readingOnDead state,deviceMsg,CommandAccepted # upon entering dead state,deviceMsg and CommandAccepted of the device will be set to 'dead' if available.

• rssiLog
  can be given to devices, denied for channels. If switched '1' each RSSI entry will be written to a reading. User may use this to log and generate a graph of RSSI level.
  Due to amount of readings and events it is NOT RECOMMENDED to switch it on by default.
• IOgrp
  can be given to devices and shall point to a virtual CCU. Setting the attribut will remove attr IODev since it mutual exclusiv. As a consequence the VCCU will take care of the assignment to the best suitable IO. It is necessary that a virtual VCCU is defined and all relevant IO devices are assigned to it. Upon sending the CCU will check which IO is operational and has the best RSSI performance for this device.
  Optional a prefered IO - perfIO can be given. In case this IO is operational it will be selected regardless of rssi values.
  If none is detected in the VCCU's IOList the mechanism is stopped.
  Example:
  
  attr myDevice1 IOgrp vccu
attr myDevice2 IOgrp vccu:prefIO
attr myDevice2 IOgrp vccu:prefIO1,prefIO2,prefIO3
attr myDevice2 IOgrp vccu:prefIO1,prefIO2,none

• levelRange <min,max>
  It defines the usable dimm-range. Can be used for e.g. LED light starting at 10% and reach maxbrightness at 40%. levelRange will normalize the level to this range. I.e. set to 100% will physically set the dimmer to 40%, 1% will set to 10% physically. 0% still switches physially off.
  Applies to all level commands as on, up, down, toggle and pct. off and level 0 still sets to physically 0%.
  LevelRage does not impact register controlled level and direct peering.
  The attribut needs to be set for each virtual channel of a device.
  Example:
  
  attr myChannel levelRange 10,80

• levelMap <=[:=[:...]]>
  the level value valX will be replaced by keyX. Multiple values can be mapped.
• modelForce
  modelForce overwrites the model attribute. Doing that it converts the device and its channel to the new model.
  Reason for this attribute is an eQ3 bug as some devices are delivered with wrong Module IDs.
  ATTENTION: changing model id automatically starts reconfiguration of the device and its channels! channels may be deleted or incarnated
  
• model
  showes model. This is read only.
• subType
  showes models subType. This is read only.
• serialNr
  device serial number. Should not be set manually
• msgRepeat
  defines number of repetitions if a device doesn't answer in time.
  Devices which donly support config mode no repeat ist allowed.
  For devices with wakeup mode the device will wait for next wakeup. Lonng delay might be considered in this case.
  Repeat for burst devices will impact HMLAN transmission capacity.
• peerIDs
  will be filled automatically by getConfig and shows the direct peerings of the channel. Should not be changed by user.
• rawToReadable
  Used to convert raw KFM100 values to readable data, based on measured values. E.g. fill slowly your container, while monitoring the values reported with inform. You'll see:
  10 (at 0%)
  50 (at 20%)
  79 (at 40%)
  270 (at 100%)
  
  Apply these values with: "attr KFM100 rawToReadable 10:0 50:20 79:40 270:100". fhem will do a linear interpolation for values between the bounderies.
• tempListTmpl
  Sets the default template for a heating controller. If not given the detault template is taken from file tempList.cfg using the enitity name as template name (e.g. ./tempLict.cfg:RT1_Clima
  To avoid template usage set this attribut to 'none' or '0'.
  Format is <file>:<templatename>. lt
• unit
  set the reported unit by the KFM100 if rawToReadable is active. E.g.
  attr KFM100 unit Liter
• cyclicMsgOffset
  when calculating the timestamp for sending the next cyclic message (e.g. weather or valve data) then the value of this attribute
  in milliseconds is added to the result. So adjusting this might fix problems for example when weather messages of virtual devices are not received reliably


• param defines model specific behavior or functions. Available parameters are (model dependand):
  • HM-SEN-RD-O
    offAtPon heat channel only: force heating off after powerOn
    onAtRain heat channel only: force heating on while status changes to 'rain' and off when it changes to 'dry'
    
  • virtuals
    noOnOff virtual entity will not toggle state when trigger is received. If this parameter is not given the entity will toggle its state between On and Off with each trigger
    msgReduce:<No> if channel is used for valvePos it skips every No message in order to reduce transmit load. Numbers from 0 (no skip) up to 9 can be given. VD will lose connection with more then 5 skips
    
  • blind
    levelInverse while HM considers 100% as open and 0% as closed this may not be intuitive to all user. Ny default 100% is open and will be dislayed as 'on'. Setting this param the display will be inverted - 0% will be open and 100% is closed.
    NOTE: This will apply to readings and set commands. It does not apply to any register.
    ponRestoreSmart upon powerup of the device the Blind will drive to expected closest endposition followed by driving to the pre-PON level
    ponRestoreForce upon powerup of the device the Blind will drive to level 0, then to level 100 followed by driving to the pre-PON level
    
  • switch
    levelInverse siehe blind above.
  • sensRain
    siren
    powerMeter
    switch
    dimmer
    rgb
    showTimed if timmed is running -till will be added to state. This results eventually in state on-till which allowes better icon handling.
    



Generated events:

• general
  recentStateType:[ack|info] # cannot be used ti trigger notifies
  
  • ack indicates that some statusinfo is derived from an acknowledge
  • info indicates an autonomous message from the device
  • sabotageAttackId
    Alarming configuration access to the device from a unknown source
    
  • sabotageAttack
    Alarming configuration access to the device that was not issued by our system
    
  • trigDst_<name>: noConfig
    A sensor triggered a Device which is not present in its peerList. Obviously the peerList is not up to date
    
• HM-CC-TC,ROTO_ZEL-STG-RM-FWT
  T: $t H: $h
  battery:[low|ok]
  measured-temp $t
  humidity $h
  actuator $vp %
  desired-temp $dTemp
  desired-temp-manu $dTemp #temperature if switchen to manual mode
  desired-temp-cent $dTemp #temperature if switchen to central mode
  windowopen-temp-%d %.1f (sensor:%s)
  tempList$wd hh:mm $t hh:mm $t ...
  displayMode temp-[hum|only]
  displayTemp [setpoint|actual]
  displayTempUnit [fahrenheit|celsius]
  controlMode [auto|manual|central|party]
  tempValveMode [Auto|Closed|Open|unknown]
  param-change offset=$o1, value=$v1
  ValveErrorPosition_for_$dname $vep %
  ValveOffset_for_$dname : $of %
  ValveErrorPosition $vep %
  ValveOffset $of %
  time-request
  trig_<src> <value> #channel was triggered by <src> channel. This event relies on complete reading of channels configuration, otherwise Data can be incomplete or incorrect.
  trigLast <channel> #last receiced trigger
  
• HM-CC-RT-DN and HM-CC-RT-DN-BOM
  state:T: $actTemp desired: $setTemp valve: $vp %
  motorErr: [ok|ValveTight|adjustRangeTooLarge|adjustRangeTooSmall|communicationERR|unknown|lowBat|ValveErrorPosition] measured-temp $actTemp
  desired-temp $setTemp
  ValvePosition $vp %
  mode [auto|manual|party|boost]
  battery [low|ok]
  batteryLevel $bat V
  measured-temp $actTemp
  desired-temp $setTemp
  actuator $vp %
  time-request
  trig_<src> <value> #channel was triggered by <src> channel.
• HM-CC-VD,ROTO_ZEL-STG-RM-FSA
  $vp %
  battery:[critical|low|ok]
  motorErr:[ok|blocked|loose|adjusting range too small|opening|closing|stop]
  ValvePosition:$vp %
  ValveErrorPosition:$vep %
  ValveOffset:$of %
  ValveDesired:$vp % # set by TC
  operState:[errorTargetNotMet|onTarget|adjusting|changed] # operational condition
  operStateErrCnt:$cnt # number of failed settings
  
• HM-CC-SCD
  [normal|added|addedStrong]
  battery [low|ok]
  
• HM-SEC-SFA-SM
  powerError [on|off]
  sabotageError [on|off]
  battery: [critical|low|ok]
  
• HM-LC-BL1-PB-FM
  motor: [opening|closing]
  
• HM-LC-SW1-BA-PCB
  battery: [low|ok]
  
• HM-OU-LED16
  color $value # hex - for device only
  $value # hex - for device only
  color [off|red|green|orange] # for channel
  [off|red|green|orange] # for channel
  
• HM-OU-CFM-PL
  [on|off|$val]
  
• HM-SEN-WA-OD
  $level%
  level $level%
  
• KFM100
  $v
  $cv,$unit
  rawValue:$v
  Sequence:$seq
  content:$cv,$unit
  
• KS550/HM-WDS100-C6-O
  T: $t H: $h W: $w R: $r IR: $ir WD: $wd WDR: $wdr S: $s B: $b
  temperature $t
  humidity $h
  windSpeed $w
  windDirection $wd
  windDirRange $wdr
  rain $r
  isRaining $ir
  sunshine $s
  brightness $b
  unknown $p
  
• HM-SEN-RD-O
  lastRain: timestamp # no trigger generated. Begin of previous Rain - timestamp of the reading is the end of rain.
  
• THSensor and HM-WDC7000
  T: $t H: $h AP: $ap
  temperature $t
  humidity $h
  airpress $ap #HM-WDC7000 only
  
• dimmer
  overload [on|off]
  overheat [on|off]
  reduced [on|off]
  dim: [up|down|stop]
  
• motionDetector
  brightness:$b
  alive
  motion on (to $dest)
  motionCount $cnt _next:$nextTr"-"[0x0|0x1|0x2|0x3|15|30|60|120|240|0x9|0xa|0xb|0xc|0xd|0xe|0xf]
  cover [closed|open] # not for HM-SEC-MDIR
  sabotageError [on|off] # only HM-SEC-MDIR
  battery [low|ok]
  devState_raw.$d1 $d2
  
• remote/pushButton/outputUnit
  
  (to $dest) is added if the button is peered and does not send to broadcast
  Release is provided for peered channels only
  Btn$x onShort
  Btn$x offShort
  Btn$x onLong $counter
  Btn$x offLong $counter
  Btn$x onLongRelease $counter
  Btn$x offLongRelease $counter
  Btn$x onShort (to $dest)
  Btn$x offShort (to $dest)
  Btn$x onLong $counter (to $dest)
  Btn$x offLong $counter (to $dest)
  Btn$x onLongRelease $counter (to $dest)
  Btn$x offLongRelease $counter (to $dest)
  
• remote/pushButton
  battery [low|ok]
  trigger [Long|Short]_$no trigger event from channel
  
• swi
  Btn$x Short
  Btn$x Short (to $dest)
  battery: [low|ok]
  
• switch/dimmer/blindActuator
  $val
  powerOn [on|off|$val]
  [unknown|motor|dim] [up|down|stop]:$val
  timedOn [running|off]
  # on is temporary - e.g. started with on-for-timer
• sensRain
  $val
  powerOn
  level <val≥
  timedOn [running|off]
  # on is temporary - e.g. started with on-for-timer trigger [Long|Short]_$no trigger event from channel
  
• smokeDetector
  [off|smoke-Alarm|alive] # for team leader
  [off|smoke-forward|smoke-alarm] # for team members
  [normal|added|addedStrong] #HM-CC-SCD
  SDteam [add|remove]_$dname
  battery [low|ok]
  smoke_detect [none|<src>]
  teamCall:from $src
  
• threeStateSensor
  [open|tilted|closed]
  [wet|damp|dry] #HM-SEC-WDS only
  cover [open|closed] #HM-SEC-WDS and HM-SEC-RHS
  alive yes
  battery [low|ok]
  contact [open|tilted|closed]
  contact [wet|damp|dry] #HM-SEC-WDS only
  sabotageError [on|off] #HM-SEC-SC only
  
• winMatic
  [locked|$value]
  motorErr [ok|TurnError|TiltError]
  direction [no|up|down|undefined]
  charge [trickleCharge|charge|dischange|unknown]
  airing [inactiv|$air]
  course [tilt|close]
  airing [inactiv|$value]
  contact tesed
  
• keyMatic
  unknown:40
  battery [low|ok]
  uncertain [yes|no]
  error [unknown|motor aborted|clutch failure|none']
  lock [unlocked|locked]
  [unlocked|locked|uncertain]
  

Internals

• aesCommToDev
  gives information about success or fail of AES communication between IO-device and HM-Device
  

CUL_HOERMANN

The CUL_HOERMANN module registers the 868MHz Hoermann Garage-Door-Opener signals received by the CUL. Note: As the structure of this signal is not understood, no checksum is verified, so it is likely to receive bogus messages.

Define
define <name> CUL_HOERMANN <10-digit-hex-code>


Set
• toggle
  Send a signal, which, depending on the status of the door, opens it, closes it or stops the current movement. NOTE: needs culfw 1.67+

Get
N/A

Attributes
• do_not_notify
• showtime
• IODev
• disable
• disabledForIntervals

CUL_IR

The CUL_IR module interprets Infrared messages received by the CUN/CUNO/CUNOv2/TuxRadio. Those devices can receive Infrared Signals from basically any Remote controller and will transform that information in a so called Button-Code

Define
define <name> CUL_IR <IODev>

<IODev> is the devicename of the IR-receivung device, e.g. CUNO1.

Your definition should look like E.g.:

    define IR-Dev CUL_IR CUNO1

Set
• irLearnForSec
  Sets the CUL_IR device in an IR-Code Learning mode for the given seconds. Any received IR-Code will be stored as a Button attribute for this devices. The name of these attributes is dependent on the two attributes learncount and learnprefix.
  Attention: Before learning IR-Codes the CUL_IR device needs to be set in IR-Receiving mode by modifying the irReceive attribute.
• irSend
  Sends out IR-commands via the connected IODev. The IR-command can be specified as buttonname according to Button.* or as IR-Code directly. If a buttonname is specified, the corresponding IR-Code will be sent out.
  Example:
  

  set IR-Dev irSend ButtonA001 

  If defining an IR-Code directly the following Code-Syntax needs to be followed:
  

  IRCode: <PP><AAAA><CCCC><FF> 

  with P = Protocol; A = Address; C = Command; F = Flags
  With the Flags you can modify IR-Repetition. Flags between 00-0E will produce 0-15 IR-Repetitions. You can type the IR-Code as plain as above, or with a heading "I" as learnt for the buttons.
  Example:
  set IR-Dev irSend 0A07070F0F02
set IR-Dev irSend I0A07070F0F00
Get
N/A
Attributes
• do_not_notify


• showtime


• loglevel


• irReceive
  Configure the IR Transceiver of the <IODev> (the CUNO1). Available arguments are:
  • OFF
    Switching off the reception of IR signals. This is the default.
  • ON
    Switching on the reception of IR signals. This is WITHOUT filtering repetitions. This is not recommended as many remote controls do repeat their signals.
  • ON_NR
    Switching on the reception of IR signals with filtering of repetitions. This is the recommended modus operandi.


• Button.*
  Button.* is the wildcard for all learnt IR-Codes. IR-Codes are learnt as Button-Attributes. The name for a learnt Button - IR-Code is compiled out of three elements:
  

          Button<learnprefix><learncount>
          

  When the CUL_IR device is set into learning mode it will generate a new button-attribute for each new IR-Code received.This is done according to the following syntax:
  

          <Button-Attribute-Name> <IR-Code>

  Examples of learnt button-attributes with EMPTY <learnprefix> and <learncount> starting from 1:
  

          Button001   I02029A000000
          Button002   I02029A000001

  To make sure that something happens when this IR-code is received later on one has to modify the attribute and to add commands as attribute values. Examples:

          Button001   I02029A000000   set WZ_Lamp on
          Button002   I02029A000001   set Switch on

  The syntax for this is:

          attr <device-name> <attribute-name> <IR-Code> <command>
          

• Group.*
  Group.* is the wildcard for IR-Code groups. With these attributes one can define IR-Code parts, which may match to several Button-IR-Codes.
  This is done by defining group-attributes that contain only parts of the IR-Code. The syntax is:

          <Group-Attribute-Name> <IR-Code>

  Examples of a group-attribute is:
  

          Group001   I02029A

  With this all IR-Codes starting with I02029A will match the Group001.


• learncount
  learncount is used to store the next button-code-number that needs to be learned. By manually modifying this attribute new button sequences can be arranged.


• learnprefix
  learnprefix is a string which will be added to the button-attribute-name.
  A button-attribute-name is constructed by:

          Button<learnprefix><learncount>    

  If learnprefix is empty the button-attribute-name only contains the term "Button" and the actual number of learncount.

CUL_MAX

The CUL_MAX module interprets MAX! messages received by the CUL. It will be automatically created by autocreate, just make sure that you set the right rfmode like attr CUL0 rfmode MAX.


Define
define <name> CUL_MAX <addr>

Defines an CUL_MAX device of type <type> and rf address <addr>. The rf address must not be in use by any other MAX device.

Set
• pairmode
  Sets the CUL_MAX into pairing mode for 60 seconds where it can be paired with other devices (Thermostats, Buttons, etc.). You also have to set the other device into pairing mode manually. (For Thermostats, this is pressing the "Boost" button for 3 seconds, for example).
• fakeSC <device> <open>
  Sends a fake ShutterContactState message <open> must be 0 or 1 for "window closed" or "window opened". If the <device> has a non-zero groupId, the fake ShutterContactState message affects all devices with that groupId. Make sure you associate the target device(s) with fakeShutterContact beforehand.
• fakeWT <device> <desiredTemperature> <measuredTemperature>
  Sends a fake WallThermostatControl message (parameters both may have one digit after the decimal point, for desiredTemperature it may only by 0 or 5). If the <device> has a non-zero groupId, the fake WallThermostatControl message affects all devices with that groupId. Make sure you associate the target device with fakeWallThermostat beforehand.

Get
N/A

Attributes
• dummy


• debug


• do_not_notify


• ignore


• showtime


• readingFnAttributes

Generated events:
N/A

CUL_REDIRECT

The CUL_REDIRECT modul receive additional protocols from CUL
and redirect them to other modules.

CUL_RFR

The CUL_RFR module is used to "attach" a second CUL to your base CUL, and use it as a repeater / range extender. RFR is shorthand for RF_ROUTER. Transmission of the data uses the CC1101 packet capabilities with GFSK modulation at 250kBaud after pinging the base CUL at the usual 1kBaud. After configured, the RFR device can be used like another CUL connected directly to FHEM. In theory every SlowRF protocol should work, as the hook is implemented in the culfw output routine: instead of sending the data to the USB-Interface it is transmitted via radio to the base CUL. There are still some restrictions: due to the ping both CULs have to be in SlowRF mode, and use the same parameters (freq, bwidth, etc). the logical module handling the protocol is not allowed to access the routines of the IODev (i.e. CUL) directly. Tested protocols are FHT, FS20, EM, HMS, S300. Since there is no ack or a resend mechanism, it should be primarily used to forward "unimportant" data, it was developed for forwading KS300 packets. Before you can use this feature in fhem, you have to enable/configure RF ROUTING in both CUL's: First give your base CUL (which remains connected to the PC) an RFR ID by issuing the fhem command "set MyCUL raw ui0100". With this command the base CUL will get the ID 01, and it will not relay messages to other CUL's (as the second number is 00). Now replace the base CUL with the RFR CUL, and set its id by issuing the fhem command "set MyCUL raw ui0201". Now remove this CUL and attach the original, base CUL again. The RFR CUL got the id 02, and will relay every message to the base CUL with id 01. Take the RFR CUL, and attach it to an USB power supply, as seen on the image. As the configured base id is not 00, it will activate RF reception on boot, and will start sending messages to the base CUL. Now you have to define this RFR cul as a fhem device:


Define
define <name> CUL_RFR <own-id> <base-id>

<own-id> is the id of the RFR CUL not connected to the PC, <base-id> is the id of the CUL connected to the PC. Both parameters have two characters, each representing a one byte hex number.
Example:
set MyCUL raw ui0100
# Now replace the base CUL with the RFR CUL
set MyCUL raw ui0201
# Reattach the base CUL to the PC and attach the RFR CUL to a USB power supply
define MyRFR CUL_RFR 02 01


Set
Same as for the CUL.

Get
Same as for the CUL.

Attributes
• ignore


• IODev

The rest of the attributes is the same as for the CUL.

CUL_TCM97001

The CUL_TCM97001 module interprets temperature sensor messages received by a Device like CUL, CUN, SIGNALduino etc.

Supported models:
• ABS700
• AURIOL (older Sensors with only Temperature)
• Auriol_IAN (NC-3982, ADE WS 1503, Tchibo 65 722)
• Auriol_Z31743B
• Eurochron
• GT_WT_02
• KW9010
• KW9015 (TFA 30.3161)
• Mebus
• Mebus7312
• NC_WS (PEARL NC7159)
• TCM21....
• TCM218943
• TCM97...
• Type1
• PFR-130 (rain)
• Prologue (GT-WT-01)
• Rubicson
• Ventus W155(Auriol): W044(temp/hum) W132(wind) W174(rain)

New received device packages are add in fhem category CUL_TCM97001 with autocreate.

Define
The received devices created automatically.
The ID of the defive are the first two Hex values of the package as dezimal.


Generated events:
• temperature: The temperature
• humidity: The humidity (if available)
• battery: The battery state: low or ok (if available)
• channel: The Channelnumber (if available)
• trend: The temperature trend (if available)
• israining: Statement rain between two measurements (if available)
• rain: The rain value, a consecutive number until the battery is changed (if available)
• winddir: The current wind direction
• windgrad: The current wind direction in degrees
• windspeed: The current wind speed
• windgust: windguest

Attributes
• IODev Note: by setting this attribute you can define different sets of 8 devices in FHEM, each set belonging to a Device which is capable of receiving the signals. It is important, however, that a device is only received by the defined IO Device, e.g. by using different Frquencies (433MHz vs 868MHz)
• disableCreateUndefDevice
  this can be used to deactivate the creation of new devices
  the new devices (Modell + ID, ioname, number) are saved in the device Unknown in the readings "undefModel_a" and "undefModel_b"
• disableUnknownEvents
  with this, the events can be deactivated for unknown messages
• do_not_notify
• ignore
• model (ABS700, AURIOL, Auriol_IAN, GT_WT_02, KW9010, NC_WS, PFR-130, Prologue, Rubicson, TCM21...., TCM218943, TCM97…, Unknown, W044, W132, W174)
• max-deviation-temp: (default:1, allowed values: 1,2,3,4,5,6,7,8,9,10,15,20,25,30,35,40,45,50)
  Maximum permissible deviation of the measured temperature from the previous value in Kelvin.
• max-diff-rain: Default:0 (deactive)
  Maximum permissible deviation of the rainfall to the previous value in l/qm.
• negation-batt: invert Battery reading
• showtime
• readingFnAttributes
• windDirectionInverse: If the anemometer has been mounted upside down, the wind direction can be turned around

CUL_TX

The CUL_TX module interprets TX2/TX3 type of messages received by the CUL, see also http://www.f6fbb.org/domo/sensors/tx3_th.php. This protocol is used by the La Crosse TX3-TH thermo/hygro sensor and other wireless themperature sensors. Please report the manufacturer/model of other working devices.

Define
define <name> CUL_TX <code> [corr] [minsecs]

<code> is the code of the autogenerated address of the TX device (0 to 127)
corr is a correction factor, which will be added to the value received from the device.
minsecs are the minimum seconds between two log entries or notifications from this device.
E.g. if set to 300, logs of the same type will occure with a minimum rate of one per 5 minutes even if the device sends a message every minute. (Reduces the log file size and reduces the time to display the plots)

Set
N/A

Get
N/A

Attributes
• ignore


• do_not_notify


• showtime


• readingFnAttributes

Generated events:
• temperature: $temp
• humidity: $hum

CUL_WS

The CUL_WS module interprets S300 type of messages received by the CUL.

Define
define <name> CUL_WS <code> [corr1...corr4]

<code> is the code which must be set on the S300 device. Valid values are 1 through 8.
corr1..corr4 are up to 4 numerical correction factors, which will be added to the respective value to calibrate the device. Note: rain-values will be multiplied and not added to the correction factor.

Set
N/A

Get
N/A

Attributes
• IODev Note: by setting this attribute you can define different sets of 8 devices in FHEM, each set belonging to a CUL. It is important, however, that a device is only received by the CUL defined, e.g. by using different Frquencies (433MHz vs 868MHz)
• do_not_notify
• eventMap
• ignore
• model (S300,KS300,ASH2200)
• showtime
• readingFnAttributes
• strangeTempDiff DIFFVAL
  If set, the module will only accept temperature values when the difference between the reported temperature and the last recorded value is less than DIFFVAL.

CULflash

CULflash [fhem-device|none]; <TYPE>

Download the firmware from a nightly SVN chekout and flash the hardware. Currently the CUL is supported with its versions: CUL_V2, CUL_V2_HM, CUL_V3, CUL_V3_ZWAVE, CUL_V4.
If the fhem-device is none, than the inserted device must already be in the flash-mode.
Note:for flashing the CUL dfu-programmer has to be installed in the path, this is already the case with the Fritz!Box 7390 image from fhem.de
Example:
CULflash CUL CUL_V3
CULflash none CUL_V3
Note: the message "dfu-programmer: failed to release interface 0." is normal on the FB7390.

Calendar

Define


define <name> Calendar ical url <URL> [<interval>]
define <name> Calendar ical file <FILENAME> [<interval>]

Defines a calendar device.

A calendar device periodically gathers calendar events from the source calendar at the given URL or from a file. The file must be in ICal format.

If the URL starts with https://, the perl module IO::Socket::SSL must be installed (use cpan -i IO::Socket::SSL).

<URL> may contain %-wildcards of the POSIX strftime function of the underlying OS (see your strftime manual). Common used wildcards are:
• %d day of month (01..31)
• %m month (01..12)
• %Y year (1970...)
• %w day of week (0..6); 0 represents Sunday
• %j day of year (001..366)
• %U week number of year with Sunday as first day of week (00..53)
• %W week number of year with Monday as first day of week (00..53)

- Wildcards in url will be evaluated on every calendar update.
- The evaluation of wildcards maybe disabled by adding literal 'noWildcards' to attribute 'quirks'. This may be useful in url containing % without marking a wildcard.

Note for users of Google Calendar:
• Wildcards must not be used in Google Calendar url!
• You can literally use the private ICal URL from your Google Calendar.
• If your Google Calendar URL starts with https:// and the perl module IO::Socket::SSL is not installed on your system, you can replace it by http:// if and only if there is no redirection to the https:// URL. Check with your browser first if unsure.

Note for users of Netxtcloud Calendar: you can use an URL of the form https://admin:admin@demo.nextcloud.com/wid0ohgh/remote.php/dav/calendars/admin/personal/?export.

The optional parameter interval is the time between subsequent updates in seconds. It defaults to 3600 (1 hour).
An interval = 0 will not be allowed and replaced by 3600 automatically. A corresponding log entry will be created.

Examples:

      define MyCalendar Calendar ical url https://www.google.com­/calendar/ical/john.doe%40example.com­/private-foo4711/basic.ics
      define YourCalendar Calendar ical url http://www.google.com­/calendar/ical/jane.doe%40example.com­/private-bar0815/basic.ics 86400
      define SomeCalendar Calendar ical file /home/johndoe/calendar.ics
    

Note on cutoff of event creation:
• Events that are more than 400 days in the past or in the future from their time of creation are omitted. This time window can be further reduced by the cutoffOlderThan and cutoffLaterThan attributes. This would have the following consequence: as long as the calendar is not re-initialized (set ... reload or restart of FHEM) and the VEVENT record is not modified, events beyond the horizon never get created. Thus, a forced reload should be scheduled every now and then.

Set


• set <name> update
  Forces the retrieval of the calendar from the URL. The next automatic retrieval is scheduled to occur interval seconds later.
  
  
• set <name> reload
  Same as update but all calendar events are removed first.
  
  

Get


• get <name> update
  Same as set <name> update
  
  
• get <name> reload
  Same as set <name> update
  
  
• get <name> events [format:<formatSpec>] [timeFormat:<timeFormatSpec>] [filter:<filterSpecs>] [series:next[=<max>]] [limit:<limitSpecs>] [include:<names>] [returnType:<returnTypeSpec>]
  
  The swiss army knife for displaying calendar events. Returns, line by line, information on the calendar events in the calendar <name> according to formatting and filtering rules. You can give none, one or several of the format, timeFormat, filter, series and limit parameters and it makes even sense to give the filter parameter several times.
  
  The format parameter determines the overall formatting of the calendar event. The following format specifications are available:
  
  

  <formatSpec>	content
  default	the default format (see below)
  full	same as custom="$U $M $A $T1-$T2 $S $CA $L"
  text	same as custom="$T1 $S"
  human	same as custom={ human($t1,$t2,$S) } - human() is a built-in function that presents the event in a terse human-readable format
  custom="<formatString>"	a custom format (see below)
  custom="{ <perl-code> }"	a custom format (see below)

  
  Single quotes (') can be used instead of double quotes (") in the custom format.
  
  You can use the following variables in the <formatString> and in the <perl-code>:
  
  

  variable	meaning
  $t1	the start time in seconds since the epoch
  $T1	the start time according to the time format
  $t2	the end time in seconds since the epoch
  $T2	the end time according to the time format
  $a	the alarm time in seconds since the epoch
  $A	the alarm time according to the time format
  $d	the duration in seconds
  $D	the duration in human-readable form
  $S	the summary
  $L	the location
  $CA	the categories
  $CL	the classification
  $DS	the description
  $U	the UID
  $M	the mode

  
  \, (masked comma) in summary, location and description is replaced by a comma but \n (indicates newline) is untouched.
  
  If the format parameter is omitted, the custom format string from the defaultFormat attribute is used. If this attribute is not set, "$T1 $D $S" is used as default custom format string. The last occurance wins if the format parameter is given several times.
  
  Examples:
  get MyCalendar events format:full
get MyCalendar events format:custom="$T1-$T2 $S \@ $L"
get MyCalendar events format:custom={ sprintf("%20s %8s", $S, $D) }
  
  The timeFormat parameter determines the formatting of start, end and alarm times.
  
  You use the POSIX conversion specifications in the <timeFormatSpec>. The web page strftime.net has a nice builder for <timeFormatSpec>.
  
  If the timeFormat parameter is omitted, the time format specification from the defaultTimeFormat attribute is used. If this attribute is not set, "%d.%m.%Y %H:%M" is used as default time format specification. Single quotes (') or double quotes (") can be used to enclose the format specification.
  
  The last occurance wins if the parameter is given several times.
  
  Example:
  get MyCalendar events timeFormat:"%e-%b-%Y" format:full
  
  The filter parameter restricts the calendar events displayed to a subset. <filterSpecs> is a comma-separated list of <filterSpec> specifications. All filters must apply for a calendar event to be displayed. The parameter is cumulative: all separate occurances of the parameter add to the list of filters.
  
  

  <filterSpec>	description
  uid=="<uid>"	UID is <uid> same as field(uid)=="<uid>"
  uid=~"<regex>"	UID matches regular expression <regex> same as field(uid)=~"<regex>"
  mode=="<mode>"	mode is <mode> same as field(mode)=="<mode>"
  mode=~"<regex>"	mode matches regular expression <regex> same as field(mode)=~"<regex>"
  field(<field>)=="<value>"	content of the field <field> is <value> <field> is one of uid, mode, summary, location, description, categories, classification
  field(<field>)=~"<regex>"	content of the field <field> matches <regex> <field> is one of uid, mode, summary, location, description, categories, classification

  
  The double quotes (") on the right hand side of a <filterSpec> are not part of the value or regular expression. Single quotes (') can be used instead.
  
  Examples:
  get MyCalendar events filter:uid=="432dsafweq64yehdbwqhkd"
get MyCalendar events filter:uid=~"^7"
get MyCalendar events filter:mode=="alarm"
get MyCalendar events filter:mode=~"alarm|upcoming"
get MyCalendar events filter:field(summary)=~"Mama"
get MyCalendar events filter:field(classification)=="PUBLIC"
get MyCalendar events filter:field(summary)=~"Gelber Sack",mode=~"upcoming|start"
get MyCalendar events filter:field(summary)=~"Gelber Sack" filter:mode=~"upcoming|start"
  
  The series parameter determines the display of recurring events. series:next limits the display to the next calendar event out of all calendar events in the series that have not yet ended. series:next=<max> shows at most the <max> next calendar events in the series. This applies per series. To limit the total amount of events displayed see the limit parameter below.
  
  The limit parameter limits the number of events displayed. <limitSpecs> is a comma-separated list of <limitSpec> specifications.
  
  

  <limitSpec>	description
  count=<n>	shows at most <n> events, <n> is a positive integer
  from=[+|-]<timespec>	shows only events that end after a timespan <timespec> from now; use a minus sign for events in the past; <timespec> is described below in the Attributes section
  to=[+|-]<timespec>	shows only events that start before a timespan <timespec> from now; use a minus sign for events in the past; <timespec> is described below in the Attributes section
  when=today|tomorrow	shows events for today or tomorrow
  when=<D1>	shows events for day <D1> from now, <D1>= 0 stands for today, negative values allowed
  when=<D1>..<D2>	shows events for the day range from day <D1> to day <D2> from now

  
  Examples:
  get MyCalendar events limit:count=10
get MyCalendar events limit:from=-2d
get MyCalendar events limit:when=today
get MyCalendar events limit:count=10,from=0,to=+10d
  
  
  The include parameter includes events from other calendars. This is useful for displaying events from several calendars in one combined output. <names> is a comma-separated list of names of calendar devices. The name of the device itself as well as any duplicates are silently ignored. Names of non-existant devices or of devices that are not Calendar devices are ignored and an error is written to the log.
  
  Example:
  get MyCalendar events include:HolidayCalendar,GarbageCollection
  
  
  The returnType parameter is used to return the events in a particular type. This is useful for Perl scripts.
  
  

  <returnTypeSpec>	description
  $text	a multiline string in human-readable format (default)
  @texts	an array of strings in human-readable format
  @events	an array of Calendar::Event hashes

  
  
  
• get <name> find <regexp>
  Returns, line by line, the UIDs of all calendar events whose summary matches the regular expression <regexp>.
  
  
• get <name> vcalendar
  Returns the calendar in ICal format as retrieved from the source.
  
  
• get <name> vevents
  Returns a list of all VEVENT entries in the calendar with additional information for debugging. Only properties that have been kept during processing of the source are shown. The list of calendar events created from each VEVENT entry is shown as well as the list of calendar events that have been omitted.


Attributes


• defaultFormat <formatSpec>
  Sets the default format for the get <name> events command. The specification is explained there. You must enclose the <formatSpec> in double quotes (") like input in attr myCalendar defaultFormat "$T1 $D $S".
• defaultTimeFormat <timeFormatSpec>
  Sets the default time format for the get <name>events command. The specification is explained there. Do not enclose the <timeFormatSpec> in quotes.
• synchronousUpdate 0|1
  If this attribute is not set or if it is set to 0, the processing is done in the background and FHEM will not block during updates.
  If this attribute is set to 1, the processing of the calendar is done in the foreground. Large calendars will block FHEM on slow systems.
  
  Attribute value will be ignored if FHEM is running on a Windows platform.
  On Windows platforms the processing will always be done synchronously
  
• update onUrlChanged|none
  If this attribute is set to onUrlChanged, the processing is done only if url to calendar has changed since last calendar update.
  If this attribute is set to none, the calendar will not be updated at all.
• delay <time>
  The waiting time in seconds after the initialization of FHEM or a configuration change before actually retrieving the calendar from its source. If not set, a random time between 10 and 29 seconds is chosen. When several calendar devices are defined, staggered delays reduce load error rates.
• timeout <time>
  The timeout in seconds for retrieving the calendar from its source. The default is 30. Increase for very large calendars that take time to be assembled and retrieved from their sources.
• removevcalendar 0|1
  If this attribute is set to 1, the vCalendar will be discarded after the processing to reduce the memory consumption of the module. A retrieval via get <name> vcalendar is then no longer possible.
• hideOlderThan <timespec>
hideLaterThan <timespec>
  

  These attributes limit the list of events shown by get <name> full|debug|text|summary|location|alarm|start|end ....

  The time is specified relative to the current time t. If hideOlderThan is set, calendar events that ended before t-hideOlderThan are not shown. If hideLaterThan is set, calendar events that will start after t+hideLaterThan are not shown.

  Please note that an action triggered by a change to mode "end" cannot access the calendar event if you set hideOlderThan to 0 because the calendar event will already be hidden at that time. Better set hideOlderThan to 10.

  <timespec> must have one of the following formats:
  

  format	description	example
  SSS	seconds	3600
  SSSs	seconds	3600s
  HH:MM	hours:minutes	02:30
  HH:MM:SS	hours:minutes:seconds	00:01:30
  D:HH:MM:SS	days:hours:minutes:seconds	122:10:00:00
  DDDd	days	100d

• cutoffOlderThan <timespec>
cutoffLaterThan <timespec>
  These attributes cut off all calendar events that end a timespan cutoffOlderThan before or a timespan cutoffLaterThan after the last update of the calendar. The purpose of setting this attribute is to save memory and processing time. Such calendar events cannot be accessed at all from FHEM.
• onCreateEvent <perl-code>
  This attribute allows to run the Perl code <perl-code> for every calendar event that is created. See section Plug-ins below.
• SSLVerify
  This attribute sets the verification mode for the peer certificate for connections secured by SSL. Set attribute either to 0 for SSL_VERIFY_NONE (no certificate verification) or to 1 for SSL_VERIFY_PEER (certificate verification). Disabling verification is useful for local calendar installations (e.g. OwnCloud, NextCloud) without valid SSL certificate.
• ignoreCancelled
  Set to 1 to ignore events with status "CANCELLED". Set this attribute to 1 if calanedar events of a series are returned although they are cancelled.
• hasModeReadings
  Set to 1 to use the obsolete mode readings.
• quirks <values>
  Parameters to handle special situations. <values> is a comma-separated list of the following keywords:
  • ignoreDtStamp: if present, a modified DTSTAMP attribute of a calendar event does not signify that the calendar event was modified.
  • noWildcards: if present, wildcards in the calendar's URL will not be expanded.
• readingFnAttributes


Description

A calendar is a set of calendar events. The calendar events are fetched from the source calendar at the given URL on a regular basis.

A calendar event has a summary (usually the title shown in a visual representation of the source calendar), a start time, an end time, and zero, one or more alarm times. In case of multiple alarm times for a calendar event, only the earliest alarm time is kept.

Recurring calendar events (series) are currently supported to an extent: FREQ INTERVAL UNTIL COUNT are interpreted, BYMONTHDAY BYMONTH WKST are recognized but not interpreted. BYDAY is correctly interpreted for weekly and monthly events. The module will get it most likely wrong if you have recurring calendar events with unrecognized or uninterpreted keywords. Out-of-order events and events excluded from a series (EXDATE) are handled. Calendar events are only created within ±400 days around the time of the last update.

Calendar events are created when FHEM is started or when the respective entry in the source calendar has changed and the calendar is updated or when the calendar is reloaded with get <name> reload. Only calendar events within ±400 days around the event creation time are created. Consider reloading the calendar from time to time to avoid running out of upcoming events. You can use something like define reloadCalendar at +*240:00:00 set MyCalendar reload for that purpose.

Some dumb calendars do not use LAST-MODIFIED. This may result in modifications in the source calendar go unnoticed. Reload the calendar if you experience this issue.

A calendar event is identified by its UID. The UID is taken from the source calendar. All events in a series including out-of-order events habe the same UID. All non-alphanumerical characters are stripped off the original UID to make your life easier.

A calendar event can be in one of the following modes:

upcoming	Neither the alarm time nor the start time of the calendar event is reached.
alarm	The alarm time has passed but the start time of the calendar event is not yet reached.
start	The start time has passed but the end time of the calendar event is not yet reached.
end	The end time of the calendar event has passed.


A calendar event transitions from one mode to another immediately when the time for the change has come. This is done by waiting for the earliest future time among all alarm, start or end times of all calendar events.

For backward compatibility, mode readings are filled when the hasModeReadings attribute is set. The remainder of this description applies to the obsolete mode readings.

Each mode reading is a semicolon-separated list of UIDs of calendar events that satisfy certain conditions:

calname	name of the calendar
modeAlarm	events in alarm mode
modeAlarmOrStart	events in alarm or start mode
modeAlarmed	events that have just transitioned from upcoming to alarm mode
modeChanged	events that have just changed their mode somehow
modeEnd	events in end mode
modeEnded	events that have just transitioned from start to end mode
modeStart	events in start mode
modeStarted	events that have just transitioned to start mode
modeUpcoming	events in upcoming mode

For recurring events, usually several calendar events exists with the same UID. In such a case, the UID is only shown in the mode reading for the most interesting mode. The most interesting mode is the first applicable of start, alarm, upcoming, end.

In particular, you will never see the UID of a series in modeEnd or modeEnded as long as the series has not yet ended - the UID will be in one of the other mode... readings. This means that you better do not trigger FHEM events for series based on mode... readings. See below for a recommendation.


Events


When the calendar was reloaded or updated or when an alarm, start or end time was reached, one FHEM event is created:

triggered

When you receive this event, you can rely on the calendar's readings being in a consistent and most recent state.

When a calendar event has changed, two FHEM events are created:

changed: UID <mode>
<mode>: UID

<mode> is the current mode of the calendar event after the change. Note: there is a colon followed by a single space in the FHEM event specification.

The recommended way of reacting on mode changes of calendar events is to get notified on the aforementioned FHEM events and do not check for the FHEM events triggered by a change of a mode reading.



Plug-ins

A plug-in is a piece of Perl code that modifies a calendar event on the fly. The Perl code operates on the hash reference $e. The most important elements are as follows:

code	description
$e->{start}	the start time of the calendar event, in seconds since the epoch
$e->{end}	the end time of the calendar event, in seconds since the epoch
$e->{alarm}	the alarm time of the calendar event, in seconds since the epoch
$e->{summary}	the summary (caption, title) of the calendar event
$e->{location}	the location of the calendar event


To add or change the alarm time of a calendar event for all events with the string "Tonne" in the summary, the following plug-in can be used:

attr MyCalendar onCreateEvent { $e->{alarm}= $e->{start}-86400 if($e->{summary} =~ /Tonne/);; }

The double semicolon masks the semicolon. Perl specials cannot be used.

To add a missing end time, the following plug-in can be used:

attr MyCalendar onCreateEvent { $e->{end}= $e->{start}+86400 unless(defined($e->{end})) }



Usage scenarios

Show all calendar events with details


get MyCalendar events format:full
2767324dsfretfvds7dsfn3e4­dsa234r234sdfds6bh874­googlecom alarm 31.05.2012 17:00:00 07.06.2012 16:30:00-07.06.2012 18:00:00 Erna for coffee
992hydf4y44awer5466lhfdsr­gl7tin6b6mckf8glmhui4­googlecom upcoming 08.06.2012 00:00:00-09.06.2012 00:00:00 Vacation


Show calendar events in your photo frame


Put a line in the layout description to show calendar events in alarm or start mode:

text 20 60 { fhem("get MyCalendar events timeFormat:'%d.%m.%Y %H:%M' format:custom='$T1 $S' filter:mode=~'alarm|start') }

This may look like:

07.06.12 16:30 Erna for coffee
08.06.12 00:00 Vacation


Switch the light on when Erna comes


First find the UID of the calendar event:

get MyCalendar find .*Erna.*
2767324dsfretfvds7dsfn3e4­dsa234r234sdfds6bh874­googlecom

Then define a notify (the dot after the second colon matches the space):

define ErnaComes notify MyCalendar:start:.2767324dsfretfvds7dsfn3e4­dsa234r234sdfds6bh874­googlecom set MyLight on

You can also do some logging:

define LogErna notify MyCalendar:alarm:.2767324dsfretfvds7dsfn3e4­dsa234r234sdfds6bh874­googlecom { Log3 $NAME, 1, "ALARM name=$NAME event=$EVENT part1=$EVTPART0 part2=$EVTPART1" }


Switch actors on and off


Think about a calendar with calendar events whose summaries (subjects, titles) are the names of devices in your fhem installation. You want the respective devices to switch on when the calendar event starts and to switch off when the calendar event ends.

define SwitchActorOn notify MyCalendar:start:.* { \
my $reading="$EVTPART0";; \
my $uid= "$EVTPART1";; \
my $actor= fhem('get MyCalendar events filter:uid=="'.$uid.'" format:custom="$S"');; \
if(defined $actor) { fhem("set $actor on") } \
}

define SwitchActorOff notify MyCalendar:end:.* { \
my $reading="$EVTPART0";; \
my $uid= "$EVTPART1";; \
my $actor= fhem('get MyCalendar events filter:uid=="'.$uid.'" format:custom="$S"');; \
if(defined $actor) { fhem("set $actor off") } \
}

You can also do some logging:

define LogActors notify MyCalendar:(start|end):.* { my $reading= "$EVTPART0";; my $uid= "$EVTPART1";; \
my $actor= fhem('get MyCalendar events filter:uid=="'.$uid.'" format:custom="$S"');; \
Log3 $NAME, 1, "Actor: $actor, Reading $reading" }


Inform about garbage collection


We assume the GarbageCalendar has all the dates of the garbage collection with the type of garbage collected in the summary. The following notify can be used to inform about the garbage collection:

define GarbageCollectionNotifier notify GarbageCalendar:alarm:.* { \
my $uid= "$EVTPART1";; \
my $summary= fhem('get MyCalendar events filter:uid=="'.$uid.'" format:custom="$S"');; \
# e.g. mail $summary to someone \
}

If the garbage calendar has no reminders, you can set these to one day before the date of the collection:

attr GarbageCalendar onCreateEvent { $e->{alarm}= $e->{start}-86400 }

The following code realizes a HTML display of the upcoming collection dates (see below):

{ CalendarEventsAsHtml('GarbageCalendar','format:text filter:mode=~"alarm|start"') }


Embedded HTML

The module provides two functions which return HTML code.

CalendarAsHtml(<name>,<options>) returns the HTML code for a list of calendar events. <name> is the name of the Calendar device and <options> is what you would write after get <name> text .... This function is deprecated.

Example: define MyCalendarWeblink weblink htmlCode { CalendarAsHtml("MyCalendar","next 3") }

CalendarEventsAsHtml(<name>,<parameters>) returns the HTML code for a list of calendar events. <name> is the name of the Calendar device and <parameters> is what you would write in get <name> events <parameters>.

Example: define MyCalendarWeblink weblink htmlCode { CalendarEventsAsHtml('F','format:custom="$T1 $D $S" timeFormat:"%d.%m" series:next=3') }

Tip: use single quotes as outer quotes.

CanOverEthernet

Define

define <name> CanOverEthernet

Defines a CanOverEthernet device. FHEM will start listening to UDP broadcasts on port 5441.
Example:
define coe CanOverEthernet
Actual readings for the incoming data will be written to COE_Node devices, which are created on-the-fly.

Set

• sendDataAnalog
  Publishes analog values.
  Example: set sendDataAnalog <Target-IP> <CAN-Channel> <Index>=<Value>;<Type>
set coe sendDataAnalog 192.168.1.1 3 1=22.7;1 2=18.0;1
• sendDataDigital
  Publishes digital values. This can be 0 or 1.
  Example: set sendDataDigital <Target-IP> <CAN-Channel> <Index>=<Value>
set coe sendDataDigital 192.168.1.1 3 1=1 2=0

ComfoAir

ComfoAir provides a way to communicate with ComfoAir ventilation systems from Zehnder, especially the ComfoAir 350 (CA350). It seems that many other ventilation systems use the same communication device and protocol, e.g. WHR930 from StorkAir, G90-380 from Wernig and Santos 370 DC from Paul. They are connected via serial line to the fhem computer. This module is based on the protocol description at http://www.see-solutions.de/sonstiges/Protokollbeschreibung_ComfoAir.pdf and copies some ideas from earlier modules for the same devices that were posted in the fhem forum from danhauck(Santos) and Joachim (WHR962).
The module can be used in two ways depending on how fhem and / or a vendor supplied remote control device like CC Ease or CC Luxe are connected to the system. If a remote control device is connected it is strongly advised that fhem does not send data to the ventilation system as well and only listens to the communication betweem the vendor equipment. The RS232 interface used is not made to support more than two parties communicating and connecting fhem in parallel to a CC Ease or similar device can lead to collisions when sending data which can corrupt the ventilation system. If connected in parallel fhem should only passively listen and <Interval> is to be set to 0.
If no remote control device is connected to the ventilation systems then fhem has to take control and actively request data in the interval to be defined. Otherwiese fhem will not see any data. In this case fhem can also send commands to modify settings.

Prerequisites


• This module requires the Device::SerialPort or Win32::SerialPort module.

Define

define <name> ComfoAir <device> <Interval>

The module connects to the ventialation system through the given Device and either passively listens to data that is communicated between the ventialation system and its remote control device (e.g. CC Luxe) or it actively requests data from the ventilation system every <Interval> seconds
If <Interval> is set to 0 then no polling will be done and the module only listens to messages on the line.

Example:


define ZL ComfoAir /dev/ttyUSB1@9600 60

Configuration of the module


apart from the serial connection and the interval which both are specified in the define command there are several attributes that can optionally be used to modify the behavior of the module.

The module internally gives names to all the protocol messages that are defined in the module and these names can be used in attributes to define which requests are periodically sent to the ventilation device. The same nams can also be used with set commands to manually send a request. Since all messages and readings are generically defined in a data structure in the module, it should be quite easy to add more protocol details if needed without programming.
The names currently defined are:

        Bootloader-Version
        Firmware-Version
        RS232-Modus
        Sensordaten
        KonPlatine-Version
        Verzoegerungen
        Ventilation-Levels
        Temperaturen
        Betriebsstunden
        Status-Bypass
        Status-Vorheizung
        

The attributes that control which messages are sent / which data is requested every <Interval> seconds are:

        poll-Bootloader-Version
        poll-Firmware-Version
        poll-RS232-Modus
        poll-Sensordaten
        poll-KonPlatine-Version
        poll-Verzoegerungen
        poll-Ventilation-Levels
        poll-Temperaturen
        poll-Betriebsstunden
        poll-Status-Bypass
        poll-Status-Vorheizung
        

if the attribute is set to 1, the corresponding data is requested every <Interval> seconds. If it is set to 0, then the data is not requested. by default Ventilation-Levels, Temperaturen and Status-Bypass are requested if no attributes are set.

Example:



        define ZL ComfoAir /dev/ttyUSB1@9600 60
        attr ZL poll-Status-Bypass 0
        define FileLog_Lueftung FileLog ./log/Lueftung-%Y.log ZL
        

Set-Commands

like with the attributes mentioned above, set commands can be used to send a request for data manually. The following set options are available for this:

        request-Status-Bypass 
        request-Bootloader-Version 
        request-Sensordaten
        request-Temperaturen 
        request-Firmware-Version 
        request-KonPlatine-Version 
        request-Ventilation-Levels 
        request-Verzoegerungen 
        request-Betriebsstunden 
        request-Status-Vorheizung 
        

additionally important fields can be set:

        Temp_Komfort (target temperature for comfort)
        Stufe (ventilation level)
        

Get-Commands

All readings that are derived from the responses to protocol requests are also available as Get commands. Internally a Get command triggers the corresponding request to the device and then interprets the data and returns the right field value. To avoid huge option lists in FHEMWEB, only the most important Get options are visible in FHEMWEB. However this can easily be changed since all the readings and protocol messages are internally defined in the modue in a data structure and to make a Reading visible as Get option only a little option (e.g. showget => 1 has to be added to this data structure
Attributes


• do_not_notify
• readingFnAttributes


• poll-Bootloader-Version
• poll-Firmware-Version
• poll-RS232-Modus
• poll-Sensordaten
• poll-KonPlatine-Version
• poll-Verzoegerungen
• poll-Ventilation-Levels
• poll-Temperaturen
• poll-Betriebsstunden
• poll-Status-Bypass
• poll-Status-Vorheizung
include a request for the data belonging to the named group when sending requests every interval seconds

• hide-Bootloader-Version
• hide-Firmware-Version
• hide-RS232-Modus
• hide-Sensordaten
• hide-KonPlatine-Version
• hide-Verzoegerungen
• hide-Ventilation-Levels
• hide-Temperaturen
• hide-Betriebsstunden
• hide-Status-Bypass
• hide-Status-Vorheizung
prevent readings of the named group from being created even if used passively without polling and an external remote control requests this data. please note that this attribute doesn't delete already existing readings.

• queueDelay
modify the delay used when sending requests to the device from the internal queue, defaults to 1 second

• queueMax
max length of the send queue, defaults to 50

• timeout
set the timeout for reads, defaults to 2 seconds

• alignTime
Aligns each periodic read request for the defined interval to this base time. This is typcally something like 00:00 (see the Fhem at command)

CustomReadings

FHEM module to define own readings.

This module allows to define own readings. The readings can be defined in an attribute so that they can get changed without changing the code of the module.
To use this module you should have some perl and linux knowledge
The examples presuppose that you run FHEM on a linux machine like a Raspberry Pi or a Cubietruck.
Note: the "bullshit" definition is an example to show what happens if you define bullshit :-)

Example (definition in fhem.cfg)
define myReadings CustomReadings
attr myReadings room 0-Test
attr myReadings group Readings
attr myReadings interval 2
attr myReadings readingDefinitions hdd_temperature:qx(hddtemp /dev/sda 2>&1),
ac_powersupply_voltage:qx(cat /sys/class/power_supply/ac/voltage_now 2>&1) / 1000000,
ac_powersupply_current:qx(cat /sys/class/power_supply/ac/current_now 2>&1) / 1000000,
perl_version:$],
timezone:qx(cat /etc/timezone 2>&1),
kernel:qx(uname -r 2>&1),
device_name:$hash->{NAME},
bullshit: $hash->{bullshit},
fhem_backup_folder_size:qx(du -ch /opt/fhem/backup | grep total | cut -d 't' -f1 2>&1)


Optionally, to display the readings:
define myReadingsDisplay weblink htmlCode {CustomReadings_GetHTML('myReadings')}
attr myReadingsDisplay group Readings
attr myReadingsDisplay room 0-Test

Resulting readings:


ac_powersupply_current	0.236	2014-08-09 15:40:21
ac_powersupply_voltage	5.028	2014-08-09 15:40:21
bullshit	ERROR	2014-08-09 15:40:21
device_name	myReadings	2014-08-09 15:40:21
fhem_backup_folder_size	20M	2014-08-09 15:40:21
hdd_temperature	/dev/sda: TS128GSSD320: 47°C	2014-08-09 15:40:21
kernel	3.4.103-sun7i+	2014-08-09 15:40:21
perl_version	5.014002	2014-08-09 15:40:21
timezone	Europe/Berlin	2014-08-09 15:40:21


Define
define <name> CustomReadings

Readings
As defined

Attributes
• interval
  Refresh interval in seconds


• readingDefinitions
  The definitions are separated by a comma. A definition consists of two parts, separated by a colon.
  The first part is the name of the reading and the second part the function.
  The function gets evaluated and must return a result.
  
  Example: kernel:qx(uname -r 2>&1)
  Defines a reading with the name "kernel" and evaluates the linux function uname -r
  Multiline output from commands, systemcall, scripts etc. can be use for more than one reading with
  the keyword COMBINED as reading (which wont appear itself) while its command output
  will be put line by line in the following readings defined (so they don't need a function defined
  after the colon (it would be ignored)).But the lines given must match the number and order of the
  following readings.
  
  COMBINED can be used together or lets say after or even in between normal expressions if the
  number of lines of the output matches exactly. Example: COMBINED:qx(cat /proc/sys/vm/dirty_background*),dirty_bytes:,dirty_ration:
  Defines two readings (dirty_bytes and dirty_ratio) which will get set by the lines of those
  two files the cat command will find in the kernel proc directory.
  In some cases this can give an noticeable performance boost as the readings are filled up all at once.

DENON_AVR

Define
define <name> DENON_AVR <ip-address-or-hostname[:PORT]>
define <name> DENON_AVR <devicename[@baudrate]>

This module controls DENON (Marantz) A/V receivers in real-time via network connection.

Instead of IP address or hostname you may set a serial connection format for direct connectivity.

Example:


define avr DENON_AVR 192.168.0.10

# With explicit port
define avr DENON_AVR 192.168.0.10:23

# With serial connection
define avr DENON_AVR /dev/ttyUSB0@9600


Set
set <name> <command> [<parameter>]

Currently, the following commands are defined:

• allZoneStereo   -   set allZoneStereo on/off
• audioRestorer   -   set audioRestorer off/low/medium/high
• audysseyLFC   -   set audysseyLFC on/off
• audysseyLFCAmount   -   set audysseyLFCAmount (1 - 7)
• autoStandby   -   set auto standby (off, 15,30,60 min)
• bass   -   adjust bass level
• channelVolume   -   adjust channel volume level for active speakers (up/down),
   to reset all channel level use FactoryDefaults
   Example to adjust volume level via command line: set avr channelVolume FrontLeft -1
   (possible values -12 to 12)
• cinemaEQ   -   set cinemaEQ on/off
• display   -   controls display dim state
• dynamicEQ   -   set dynamicEQ on/off
• dynamicEQRefLevelOffset   -   set dynamicEQRefLevelOffset (0, 5, 10, 15)
• dynamicVolume   -   set dynamicEQ off/light/medium/heavy
• eco   -   controls eco state
• favorite   -   switches between favorite (only older models)
• favoriteList   -   select entries in favorite list (workaround for new models >= 2014),
   it is recommended to use set stream in combination with module 98_DLNARenderer!
• input   -   switches between inputs
• loudness   -   set loudness on/off
• lowFrequencyEffect   -   adjust LFE level (-10 to 0)
• multiEQ   -   set multiEQ off/reference/bypassLR...
• mute on,off   -   controls volume mute
• muteT   -   toggle mute state
• off   -   turns the device in standby mode
• on   -   powers on the device
• preset   -   switches between presets (1-3, only older models)
• presetCall   -   switches between presets (00-35, 00-55 older models)
• presetMemory   -   save presets (00-35, 00-55 older models, for alphanumeric mode A1-G8 set attribute "presetMode" to "alphanumeric")
• quickselect   -   switches between quick select modes (1-5, only new models)
• rawCommand   -   send raw command to AV receiver
• reconnect   -   reconnect AV receiver
• remoteControl   -   remote commands (play, stop, pause,...)
• setup   -   onscreen setup on/off
• sleep   -   set sleep timer (off/10 to 120 min)
• smartselect   -   switches between smart select modes (1-5, only Marantz, to activate set attribute brand to Marantz)
• stream   -   send stream adress via module 98_DLNARenderer to reciever; the user has to create a file "Denon.streams" in folder "fhem/FHEM"
  
  list format:
  Rockantenne<>http://mp3channels.webradio.antenne.de/rockantenne
Bayern3<>http://streams.br.de/bayern3_2.m3u
JamFM<>http://www.jam.fm/streams/jam-nmr-mp3.m3u

  The attribut "dlnaName" must be set to the name of the reciever in DLNARenderer module.
  
• surroundMode   -   set surround mode
• toggle   -   switch between on and off
• treble   -   adjust treble level
• trigger1   -   set trigger1 on/off
• trigger2   -   set trigger2 on/off
• tuner   -   switch between AM and FM
• tunerPreset   -   switches between tuner presets (1-56)
• tunerPresetMemory   -   save tuner presets (1-56)
• usedInputs   -   set used inputs manually if needed (e.g. us model)
• volume 0...98   -   set the volume level in percentage
• volumeStraight -80...18   -   set the volume level in dB
• volumeUp   -   increases the volume level
• volumeDown   -   decreases the volume level


Get
get <name> <what>

Currently, the following commands are defined:

• disconnect   -   disconnect AV receiver
• mediaInfo   -   refresh current media infos
• reconnect   -   reconnect AV receiver
• remoteControl   -   autocreate remote ccontrol
• statusRequest   -   refresh status
• some readings   -   see list below
• zone   -   autocreate zones

Generated Readings/Events:

The AV reciever sends some readings only if settings (e.g. ampAssign) have changed
or the reciever has been disconnected (power supply) for more than 5 min and connected again.


• ampAssign   -   amplifier settings for AV receiver (5.1, 7.1, 9.1,...)
• audioRestorer   -   audioRestorer Level (off, low, medium, high)
• autoStandby   -   auto standby state
• bass   -   bass level in dB
• currentAlbum   -   current album (mediaplayer, online music,...)
• currentArtist   -   current artist (mediaplayer, online music,...)
• currentBitrate   -   current bitrate (mediaplayer, online music,...)
• currentMedia   -   current media (mediaplayer, online music,...)
• currentStation   -   current station (online radio)
• currentTitle   -   current title (mediaplayer, online music,...)
• display   -   dim state of display
• dynamicCompression   -   dynamic compression state
• eco   -   eco state
• input   -   selected input
• level[speaker]   -   [speaker] level in dB (e.g. levelFrontRight)
• lowFrequencyEffects   -   low frequency effects (LFE) state
• mute   -   mute state
• playStatus   -   current playStatus (playing/paused/stopped)
• power   -   power state
• samplingRate   -   sampling rate
• signal   -   input signal sound
• sound   -   actual sound type
• state   -   state of AV reciever (on,off,disconnected)
• stateAV   -   state of AV reciever (on,off,absent,mute)
• surroundMode   -   actual surround mode (Auto, Stereo, Music,...)
• toneControl   -   tone control state
• treble   -   treble level in dB
• tuner[Information]   -   tuner settings [Band, Frequency, Mode, Preset]
• videoSelect   -   actual video select mode
• volume   -   actual volume
• volumeMax   -   actual maximum volume
• volumeStraight   -   actual volume straight
• zone   -   state of aviable zones (on/off)

Attributes


• brand   -   brand of AV receiver (Denon/Marantz) - to activate smartselect set attribute brand to Marantz
• connectionCheck   -   time to next connection check
• disable   -   defined device on/off
• dlnaName   -   name of Reciever in DLNARenderer module
• favorites   -   max entries for favorites
• maxFavorites   -   max entries in favorite list for "set favoriteList"
• maxPreset   -   max entries in preset list
• playTime   -   timespan to next playtime check (off, 1-60 sec)
• presetMode   -   preset list mode (numeric [00-55] or alphanumeric [A1-G8])
• sleep   -   break between commands for use with "set favoriteList"
• timeout   -   number of connection attempts
• type   -   reciever type (AVR oder Ceol), steps for volumeslider (0.5 or 1)
• unit   -   de-/activate units for readings (on or off)

DENON_AVR_ZONE

Define
define <name> DENON_AVR_ZONE <zonenumber>

This module controls DENON A/V receivers zones.


Example:


define avr_zone2 DENON_AVR_ZONE 2

define avr_zone2 DENON_AVR_ZONE 3




Set
set <name> <command> [<parameter>]

Currently, the following commands are defined:

• autoStandby   -   set auto standby time
• favorite   -   switches between favorite (only older models)
• input   -   switches between inputs
• mute on,off   -   controls volume mute
• muteT   -   toggle mute state
• off   -   turns the device in standby mode
• on   -   powers on the device
• quickselect   -   switches between quick select modes (1-5, only new models)
• rawCommand   -   send raw command to AV receiver
• remote   -   remote commands (play, stop, pause,...)
• surroundMode   -   set surround mode
• toggle   -   switch between on and off
• volume 0...98   -   set the volume level in percentage
• volumeStraight -80...18   -   set the volume level in dB
• volumeUp   -   increases the volume level
• volumeDown   -   decreases the volume level

Get
get <name> <what>

Currently, the following commands are defined:

• remoteControl   -   autocreate remote ccontrol
• some readings   -   see list below


Generated Readings/Events:


• autoStandby   -   auto standby state
• input   -   selected input
• mute   -   mute state
• power   -   power state
• state   -   state of AV reciever (on,off,disconnected)
• stateAV   -   state of AV reciever (on,off,absent,mute)
• treble   -   treble level in dB
• videoSelect   -   actual video select mode
• volume   -   actual volume
• volumeMax   -   actual maximum volume
• volumeStraight   -   actual volume straight

Attributes


• IODev   -   Input/Output Device

DFPlayerMini - FN-M16P Embedded MP3 Audio Module

This module integrates the DFPlayerMini - FN-M16P Embedded MP3 Audio Module device into fhem. See the datasheet of the module for technical details.
The MP3 player can be connected directly to a serial interface or via ethernet/WiFi by using a hardware with offers a transparent serial bridge over TCP/IP like ESPEasy Ser2Net.

It is also possible to use other fhem transport devices like MYSENSORS.

The module supports all commands of the DFPlayer and offers additional convenience functions like

• integration of Text2Speech for easy download of speech mp3 files
• easier control of which file to play by
• keeping a reference of all files the DFPlayer can play
• playing several files in succession (playlist)
• creating and playing files for speaking numbers

Define
define <name> DFPlayerMini {none | devicename[\@baudrate] | devicename\@directio | hostname:port}

• If directly connected <devicename> specifies the serial port to communicate with the DFPlayer Mini. The name of the serial-device depends on your distribution, under linux the cdc_acm kernel module is responsible, and usually a /dev/ttyACM0 or /dev/ttyUSB0 device will be created. You can also specify a baudrate if the device name contains the @ character, e.g.: /dev/ttyACM0@9600
  
  This is also the default baudrate and normally shouldn't be changed as the DFPlayer uses a fixed baudrate of 9600. If the baudrate is "directio" (e.g.: /dev/ttyACM0@directio), then the perl module Device::SerialPort is not needed, and fhem opens the device with simple file io. This might work if the operating system uses sane defaults for the serial parameters, e.g. some Linux distributions and OSX.
  
• If connected via TCP/IP <hostname:port> specifies the IP address and port of the device that provides the transparent serial bridge to the DFP, e.g. 192.168.2.28:23
• for other types of transport none can be specified as the device. In that case the attribute sendCmd should be specified and responses from the DFP should be given to this module with set response.

Attributes

• TTSDev
  The name of a Text2Speech device. This has to be defined beforehand with none as the <alsadevice> as a server device. It should be used for no other purposes than use by this module.
• requestAck
  The DFPlayer can send a response to any command sent to it to acknowledge that is has received the command. As this increases the communication overhead it can be switched off if the communication integrity is ensured by other means. If set the next command is only sent if the last one was acknowledged by the DFPlayer. This ensures that no command is lost if the the DFPlayer is busy/sleeping.
• sendCmd
  A fhem command that is used to send the command data generated by this module to the DFPlayer hardware. If this is set, no other way of communication with the DFP is used. This can be used integrate other transport devices than those supported natively.
  E. g. to communicate via a MySensors device named mys_dfp with an appropriate sketch use
  attr <dfp> sendCmd set mys_dfp value11 $msg
  The module will then send a command to the DFP replacing $msg with the actual payload using the fhem command set mys_dfp value11 <payload>
  See set response for a way to get the response of the DFPlayer received via a different device back into this module.
• uploadPath
  The DFPlayer plays files from an SD card or USB stick connected to it. The mp3/wav files have to be copied to this storage device by the user. The device expects the files with specific names and in specific folders, see the datasheet for details. Copying the files can also be done by this module if the storage device is accessible by the computer fhem is running on. It has to be mounted in a specific path with is specified with this attribute.
  See uploadTTS, uploadTTScache and readFiles commands where this is used.
• rememberMissingTTS
  If set tts commands without a matching file create a special reading. See set tts and set uploadTTScache.
• keepAliveInterval
  Specifies the interval in seconds for sending a keep alive message to the DFP. Can be used to check if the DFP is still working and to keep connections open.
  After three missing answers the status of the devices is set to disconnected.
  Set the interval to 0 to disable the keep alive feature. Default is 60 seconds.

Get

All query commands supported by the DFP have a corresponding get command:

get	DFP cmd byte	parameters	comment
storage	0x3F
status	0x42
volume	0x43
equalizer	0x44
noTracksRootUsb	0x47
noTracksRootSd	0x48
currentTrackUsb	0x4B
currentTrackSd	0x4C
noTracksInFolder	0x4E	folder number	1-99
noFolders	0x4F

Set

All commands supported by the DFP have a corresponding set command:

set	DFP cmd byte	parameters	comment
next	0x01	-
prev	0x02	-
trackNum	0x03	number of track in root directory	between 1 and 3000 (uses the order in which the files where created!)
volumeUp	0x04	-
volumeDown	0x05	-
volumeStraight	0x06	volume	0-30
equalizer	0x07	name of the equalizer mode	Normal, Pop, Rock, Jazz, Classic, Bass
repeatSingle	0x08	-
storage	0x09	SD or USB
sleep	0x0A	-	not supported by DFP, DFP needs power cycle to work again
wake	0x0B	-	not supported by DFP, but probably by FN-M22P
reset	0x0C	-
play	0x0D	-	plays the current track
play	0x0F, 0x12, 0x13, 0x14	a space separated list of files to play successively	the correct DFP command is used automatically. Files can be specified with either their reading name, reading value or folder name/track number. See set readFiles
pause	0x0E	-
amplification	0x10	level of amplification	0-31
repeatRoot	0x11	on, off
MP3TrackNum	0x12	tracknumber	1-3000, from folder MP3
intercutAdvert	0x13	tracknumber	1-3000, from folder ADVERT
folderTrackNum	0x0F	foldernumber tracknumber	folder: 1-99, track: 1-255
folderTrackNum3000	0x14	foldernumber tracknumber	folder: 1-15, track: 1-3000
stopAdvert	0x15	-
stop	0x16	-
repeatFolder	0x17	number of folder	1-99
shuffle	0x18	-
repeatCurrentTrack	0x19	on, off
DAC	0x1A	on, off

All other set commands are not sent to the DFP but offer convenience functions:

• close
• raw
  sends a command encoded in hex directly to the DFP without any validation
• reopen
• readFiles
  reads all files from the storage medium mounted at uploadPath. If these files are accessible by the DFP (i.e. they conform to the naming convention) a reading is created for the file. The reading name is File_<folder>/<tracknumber>. Folder can be ., MP3, ADVERT, 00 to 99. The reading value is the filename without the tracknumber and suffix.
  Example:
  For the file MP3/0003SongTitle.mp3 the reading File_MP3/0003 with value SongTitle is created.
  The set <dfp> play command can make use of these readings, i.e. it is possible to use either set <dfp> play File_MP3/0003, set <dfp> play MP3/3 or set <dfp> play SongTitle to play the same track.
• uploadTTS <destination path> <Text to translate to speech>
  The text specified is converted to a speech mp3 file using the Text2Speech device specified with attr TTSDev. The mp3 file is then copied into the given destination path within uploadPath.
  Examples:
  set <dfp> 01/0001Test Dies ist ein Test
set <dfp> ADVERT/0099Hinweis Achtung
• uploadTTScache
  upload all files from the cache directory of the TTSDev to uploadPath. Uploading starts with folder 01. After 3000 files the next folder is used. The MD5 hash is used as the filename. When the upload is finished set readFiles is executed. The command set tts makes use of the readings created by this.
• tts <text to translate to speech>
  TTSDev is used to calculate the MD5 hash of <text to translate to speech>. It then tries to play the file with this hash value. If no reading for such a file exists and if the attribute rememberMissingTTS is set, a new reading Missing_MD5<md5> with <text to translate to speech> as its value is created.
  Prerequisites:
  This only works if this text had been translated earlier and the resulting mp3 file was stored in the cache directory of TTSDev. The files in the cache have to be uploaded to the storage card with set uploadTTScache.
• uploadNumbers destinationFolder
  creates mp3 files for all tokens required to speak arbitrary german numbers.
  Example:
  set <dfp> uploadNumbers 99
  creates the 31 mp3 files required in folder 99.
• sayNumber number
  translates a number into speech and plays the required tracks. Requires that uploadNumbers command was used to create the speech files.
  Example:
  sayNumber -34.7
  is equivalent to
  play minus vier und dreissig komma sieben
• response
  10 bytes response message from DFP encoded as hex

DLNARenderer

DLNARenderer automatically discovers all your MediaRenderer devices in your local network and allows you to fully control them.
It also supports multiroom audio for Caskeid and Bluetooth Caskeid speakers (e.g. MUNET).

Note: The followig libraries are required for this module:
• SOAP::Lite
• LWP::Simple
• XML::Simple
• XML::Parser::Lite
• LWP::UserAgent


Define
define <name> DLNARenderer

Example:
define dlnadevices DLNARenderer
After about 2 minutes you can find all automatically created DLNA devices under "Unsorted".


Set

set <name> stream <value>
Set any URL to play.

set <name> on
Starts playing the last stream (reading stream).

set <name> off
Sends stop command to device.

set <name> stop
Stop playback.

set <name> volume 0-100
set <name> volume +/-0-100
Set volume of the device.

set <name> channel 1-10
Start playing channel X which must be configured as channel_X attribute first.
You can specify your channel also in DIDL-Lite XML format if your player doesn't support plain URIs.

set <name> mute on/off
Mute the device.

set <name> pause
Pause playback of the device. No toggle.

set <name> pauseToggle
Toggle pause/play for the device.

set <name> play
Initiate play command. Only makes your player play if a stream was loaded (currentTrackURI is set).

set <name> next
Play next track.

set <name> previous
Play previous track.

set <name> seek <seconds>
Seek to position of track in seconds.

set <name> speak "This is a test. 1 2 3."
Speak the text followed after speak within quotes. Works with Google Translate.

set <name> playEverywhere
Only available for Caskeid players.
Play current track on all available Caskeid players in sync.

set <name> stopPlayEverywhere
Only available for Caskeid players.
Stops multiroom audio.

set <name> addUnit <unitName>
Only available for Caskeid players.
Adds unit to multiroom audio session.

set <name> removeUnit <unitName>
Only available for Caskeid players.
Removes unit from multiroom audio session.

set <name> multiRoomVolume 0-100
set <name> multiRoomVolume +/-0-100
Only available for Caskeid players.
Set volume of all devices within this session.

set <name> enableBTCaskeid
Only available for Caskeid players.
Activates Bluetooth Caskeid for this device.

set <name> disableBTCaskeid
Only available for Caskeid players.
Deactivates Bluetooth Caskeid for this device.

set <name> stereo <left> <right> <pairName>
Only available for Caskeid players.
Sets stereo mode for left/right speaker and defines the name of the stereo pair.

set <name> standalone
Only available for Caskeid players.
Puts the speaker into standalone mode if it was member of a stereo pair before.

set <name> saveGroupAs <groupName>
Only available for Caskeid players.
Saves the current group configuration (e.g. saveGroupAs LivingRoom).

set <name> loadGroup <groupName>
Only available for Caskeid players.
Loads the configuration previously saved (e.g. loadGroup LivingRoom).

Attributes

ignoreUDNs
Define list (comma or blank separated) of UDNs which should prevent automatic device creation.
It is important that uuid: is also part of the UDN and must be included.

DOIF

DOIF is a universal module. It works event- and time-controlled.

It combines the functionality of a notify, at-, watchdog command with logical queries.

Complex problems can be solved with this module, which would otherwise be solved only with several modules at different locations in FHEM. This leads to clear solutions and simplifies their maintenance.

Logical queries are created in conditions using Perl operators. These are combined with information from states, readings, internals of devices or times in square brackets. Arbitrary Perl functions can also be specified that are defined in FHEM. The module is triggered by time or by events information through the Devices specified in the condition. If a condition is true, the associated FHEM- or Perl commands are executed.

Syntax FHEM-Mode:


define <name> DOIF (<condition>) (<commands>) DOELSEIF (<condition>) (<commands>) DOELSEIF ... DOELSE (<commands>)

Syntax Perl-Mode:


define <name> DOIF <Blockname> {<Perl with DOIF-Syntax>} <Blockname> {<Perl with DOIF-Syntax>} ...

The commands are always processed from left to right. There is only one command executed, namely the first, for which the corresponding condition in the processed sequence is true. In addition, only the conditions are checked, which include a matching device of the trigger (in square brackets).

Features


+ intuitive syntax, as used in branches (if - elseif-....elseif - else) in higher-level languages
+ in the condition of any logical queries can be made as well as perl functions are used (full perl support)
+ it can be any FHEM commands and perl commands are executed
+ syntax checking at the time of definition are identified missing brackets
+ status is specified with [<devicename>], readings with [<devicename>:<readingname>] or internals with [<devicename>:&<internal>]
+ time information on the condition: [HH:MM:SS] or [HH:MM] or [<seconds>]
+ indirect time on the condition: [[<devicename>]] or [[<devicename>:<readingname>]] or [{<perl-function>}]
+ time calculation on the condition: [(<time calculation in Perl with time syntax specified above>)]
+ time intervals: [<begin>-<end>] for <begin> and <end>, the above time format can be selected.
+ relative times preceded by a plus sign [+<time>] or [+<begin>-+<end>] combined with Perl functions
+ weekday control: [<time>|0123456789] or [<begin>-<end>|0123456789] (0-6 corresponds to Sunday through Saturday) such as 7 for $we, 8 for !$we, 9 for $we tomorrow ($twe)
+ statuses, readings, internals und time intervals for only queries without trigger with [?...]
+ DOELSEIF cases and DOELSE at the end are optional
+ delay specification with resetting is possible (watchdog function)
+ the execution part can be left out in each case. So that the module can be used for pure status display.
+ definition of the status display with use of any readings or statuses



Many examples with english identifiers - see german section.

DOIFtools

DOIFtools contains tools to support DOIF.


• create readingsGroup definitions for labeling frontend widgets.
• create a debug logfile for some DOIF and quoted devices with optional device listing each state or wait timer update.
• optional device listing in debug logfile each state or wait timer update.
• navigation between device listings in logfile if opened via DOIFtools.
• create userReadings in DOIF devices displaying real dates for weekday restricted timer.
• delete user defined readings in DOIF devices with multiple choice.
• delete visible readings in other devices with multiple choice, but not state.
• record statistics data about events.
• limitting recordig duration.
• generate a statistics report.
• lists every DOIF definition in probably associated with.
• access to DOIFtools from any DOIF device via probably associated with
• access from DOIFtools to existing DOIFtoolsLog logfiles
• show event monitor in device detail view and optionally in DOIFs detail view
• convert events to DOIF operands, a selected operand is copied to clipboard and the DEF editor will open
• check definitions and offer recommendations for DOIF MODEL FHEM
• create shortcuts
• optionally create a menu entry
• show a list of running wait timer
• scale values to color numbers and RGB values for coloration
• list subs declared by user in package DOIF

Just one definition per FHEM-installation is allowed. More in the german section.

DUOFERN

Support for DuoFern devices via the DuoFern USB Stick.


Define
define <name> DUOFERN <code>

<code> specifies the radio code of the DuoFern device

Example:

define myDuoFern DUOFERN 49ABCD


Set
Universal commands (available to most actors):


• remotePair
  Activates the pairing mode of the actor.
  Some actors accept this command in unpaired mode up to two hours afte power up.


• remoteUnpair
  Activates the unpairing mode of the actor.


• getStatus
  Sends a status request message to the DuoFern device.


• manualMode [on|off]
  Activates the manual mode. If manual mode is active all automatic functions will be ignored.


• timeAutomatic [on|off]
  Activates the timer automatic.


• sunAutomatic [on|off]
  Activates the sun automatic.


• dawnAutomatic [on|off]
  Activates the dawn automatic.


• duskAutomatic [on|off]
  Activates the dusk automatic.


• dusk
  Move roller shutter downwards or switch on switch/dimming actor if duskAutomatic is activated.


• dawn
  Move roller shutter upwards or switch off switch/dimming actor if dawnAutomatic is activated.


• sunMode [on|off]
  Activates the sun mode. If sun automatic is activated, the roller shutter will move to the sunPosition or a switch/dimming actor will shut off.


• reset [settings|full]
  settings: Clear all settings and endpoints of the actor.
  full: Complete reset of the actor including pairs.


Roller shutter actor commands:


• up [timer]
  Move the roller shutter upwards. If parameter timer is used the command will only be executed if timeAutomatic is activated.


• down [timer]
  Move the roller shutter downwards. If parameter timer is used the command will only be executed if timeAutomatic is activated.


• stop
  Stop motion.


• position <value> [timer]
  Set roller shutter to a desired absolut level. If parameter timer is used the command will only be executed if timeAutomatic is activated.


• toggle
  Switch the roller shutter through the sequence up/stop/down/stop.


• rainAutomatic [on|off]
  Activates the rain automatic.


• windAutomatic [on|off]
  Activates the wind automatic.


• sunPosition <value>
  Set the sun position.


• ventilatingMode [on|off]
  Activates the ventilating mode. If activated, the roller shutter will stop on ventilatingPosition when moving down.


• ventilatingPosition <value>
  Set the ventilating position.


• windMode [on|off]
  Activates the wind mode. If wind automatic and wind mode is activated, the roller shutter moves in windDirection and ignore any automatic or manual command.
  The wind mode ends 15 minutes after last activation automatically.


• windDirection [up|down]
  Movemet direction for wind mode.


• rainMode [on|off]
  Activates the rain mode. If rain automatic and rain mode is activated, the roller shutter moves in rainDirection and ignore any automatic command.
  The rain mode ends 15 minutes after last activation automatically.


• rainDirection [up|down]
  Movemet direction for rain mode.


• runningTime <sec>
  Set the motor running time.


• motorDeadTime [off|short|long]
  Set the motor dead time.


• reversal [on|off]
  Reversal of direction of rotation.


Switch/dimming actor commands:


• on [timer]
  Switch on the actor. If parameter timer is used the command will only be executed if timeAutomatic is activated.


• off [timer]
  Switch off the actor. If parameter timer is used the command will only be executed if timeAutomatic is activated.


• set extensions are supported.


• level <value> [timer]
  Set actor to a desired absolut level. If parameter timer is used the command will only be executed if timeAutomatic is activated.


• modeChange [on|off]
  Inverts the on/off state of a switch actor or change then modus of a dimming actor.


• stairwellFunction [on|off]
  Activates the stairwell function of a switch/dimming actor.


• stairwellTime <sec>
  Set the stairwell time.


Blind actor commands:


• blindsMode [on|off]
  Activates the blinds mode.


• slatPosition <value>
  Set the slat to a desired absolut level.


• defaultSlatPos <value>
  Set the default slat position.


• slatRunTime <msec>
  Set the slat running time.


• tiltInSunPos [on|off]
  Tilt slat after blind moved to sun position.


• tiltInVentPos [on|off]
  Tilt slat after blind moved to ventilation position.


• tiltAfterMoveLevel [on|off]
  Tilt slat after blind moved to an absolute position.


• tiltAfterStopDown [on|off]
  Tilt slat after stopping blind while moving down.


Thermostat commands:


• desired-temp <temp> [timer]
  Set desired temperature. <temp> must be between -40 and 80 Celsius, and precision is half a degree. If parameter timer is used the command will only be executed if timeAutomatic is activated.


• tempUp [timer]
  Increases the desired temperature by half a degree. If parameter timer is used the command will only be executed if timeAutomatic is activated.


• tempDown [timer]
  Decrease the desired temperature by half a degree. If parameter timer is used the command will only be executed if timeAutomatic is activated.


• temperatureThreshold[1|2|3|4] <temp>
  Set temperature threshold 1 to 4. <temp> must be between -40 and 80 Celsius, and precision is half a degree.


• actTempLimit [timer]
  Set desired temperature to the selected temperatureThreshold. If parameter timer is used the command will only be executed if timeAutomatic is activated.


Radiator Actuator commands:


• desired-temp <temp> [timer]
  Set desired temperature. <temp> must be between 4 and 35.5 Celsius, and precision is half a degree. If parameter timer is used the command will only be executed if timeAutomatic is activated.


• sendingInterval <minutes>
  Sets the transmission interval of the status responds.


SX5 commands:


• 10minuteAlarm [on|off]
  Activates the alarm sound of the SX5 when the door is left open for longer than 10 minutes.


• 2000cycleAlarm [on|off]
  Activates the alarm sounds of the SX5 when the SX5 has run 2000 cycles.


• automaticClosing [off|30|60|90|120|150|180|210|240]
  Set the automatic closing time of the SX5 (sec).


• openSpeed [11|15|19]
  Set the open speed of the SX5 (cm/sec).


• backJump [on|off]
  If activated the SX5 moves briefly in the respective opposite direction after reaching the end point.


• getConfig
  Sends a config request message to the weather sensor.


Weather sensor commands:


• getConfig
  Sends a configuration request message.


• getTime
  Sends a time request message.


• getWeather
  Sends a weather data request message.


• writeConfig
  Write the configuration back to the weather sensor.


• DCF [on|off]
  Switch the DCF receiver on or off.


• time
  Set the current system time to the weather sensor.


• interval <value>
  Set the interval time for automatic transmittion of the weather data.
  <value>: off or 1 to 100 minutes


• latitude <value>
  Set the latitude of the weather sensor position
  <value>: 0 to 90


• longitude <value>
  Set the longitude of the weather sensor position
  <value>: -90 to 90


• timezone <value>
  Set the time zone of the weather sensor
  <value>: 0 to 23


• triggerDawn <value1> ... [<value5>]
  Sets up to 5 trigger values for a dawn event.
  <value[n]>: off or 1 to 100 lux


• triggerDusk <value1> ... [<value5>]
  Sets up to 5 trigger values for a dusk event.
  <value[n]>: off or 1 to 100 Lux


• triggerRain [on|off]
  Switch the trigger of the rain event on or off.


• triggerSun <value1>:<sun1>:<shadow1>[:<temperature1>] ... [<value5>:<sun5>:<shadow5>[:<temperature5>]]
  Sets up to 5 trigger values for a sun event.
  <value[n]>: off or 1 to 100 kLux
  <sun[n]>: time to detect sun, 1 to 30 minutes
  <shadow[n]>: time to detect shadow, 1 to 30 minutes
  <temperature[n]>: optional minimum temperature, -5 to 26 °C


• triggerSunDirction <startangle1>:<width1> ... [<startangle5>:<width5>]
  If enabled, the respective sun event will only be triggered, if sunDirection is in the specified range.
  <startangle[n]>: off or 0 to 292.5 degrees (stepsize 22.5°)
  <width[n]>: 45 to 180 degrees (stepsize 45°)
  


• triggerSunHeight <startangle1>:<width1> ... [<startangle5>:<width5>]
  If enabled, the respective sun event will only be triggered, if sunHeight is in the specified range.
  <startangle[n]>: off or 0 to 65 degrees (stepsize 13°)
  <width[n]>: 26 or 52 degrees
  


• triggerTemperature <value1> ... [<value5>]
  Sets up to 5 trigger values for a temperature event.
  <value[n]>: off or -40 to 80 °C


• triggerWind <value1> ... [<value5>]
  Sets up to 5 trigger values for a wind event.
  <value[n]>: off or 1 to 31 m/s





Get
N/A

Attributes
• IODev


• timeout <sec>
  After sending a command to an actor, the actor must respond with its status within this time. If no status message is received, up to two getStatus commands are resend.
  Default 60s.


• toggleUpDown
  If attribute is set, a stop command is send instead of the up or down command if the roller shutter is moving.


• positionInverse
  If attribute is set, the position value of the roller shutter is inverted.


• positionDeviation
  Maximum deviation for displaying the desired position instead of the reported position.

DUOFERNSTICK

The DUOFERNSTICK is the fhem module for the Rademacher DuoFern USB stick.


Define
define <name> DUOFERNSTICK <device> <code>

<device> specifies the serial port to communicate with the DuoFern stick.
<code> specifies the radio code of the DuoFern stick.

The baud rate must be 115200 baud.
The code of the DuoFern stick must start with 6F.

Example:

define myDuoFernStick DUOFERNSTICK COM5@115200 6FEDCB
define myDuoFernStick DUOFERNSTICK /dev/serial/by-id/usb-Rademacher_DuoFern_USB-Stick_WR0455TN-if00-port0@115200 6FEDCB




Set

• pair
  Set the DuoFern stick in pairing mode for 60 seconds. Any DouFern device set into pairing mode in this time will be paired with the DuoFern stick.


• unpair
  Set the DuoFern stick in unpairing mode for 60 seconds. Any DouFern device set into unpairing mode in this time will be unpaired from the DuoFern stick.


• reopen
  Reopens the connection to the device and reinitializes it.


• statusBroadcast
  Sends a status request message to all DuoFern devices.


• remotePair <code>
  Activates the pairing mode on the device specified by the code.
  Some actors accept this command in unpaired mode up to two hours afte power up.


• raw <rawmsg>
  Sends a raw message.



Get
N/A

Attributes
N/A

DWD_OpenData

The Deutsche Wetterdienst (DWD) provides public weather related data via its Open Data Server. Any usage of the service and the data provided by the DWD is subject to the usage conditions on the Open Data Server webpage. An overview of the available content can be found at OpenData_weather_content.xls.

This module provides two elements of the available data:


• weather forecasts: Total lists of local forecasts of WMO, national and interpolated stations, all variables, 3, 9, 15, 21 UTC. More than 70 properties are available for worldwide POIs and the German DWD network. This data typically spans 10 days and is updated by the DWD every 6 hours.
  
  You can request forecasts for different stations in sequence using the command get forecast <station code> or for one station continuously using the attribute forecastStation. To get continuous mode for more than one station you need to create separate DWD_OpenData devices.
  
  In continuous mode the forecast data will be shifted by one day at midnight without requiring new data from the DWD.
  
  


• weather alerts: Warning status for Germany as union of referenced community/district warnings. This data is updated by the DWD as required.
  
  After updating the alerts cache using the command get updateAlertsCache <mode> you can request alerts for different warncells in sequence using the command get alerts <warncell id>. Setting the attribute alertArea will enable continuous mode. To get continuous mode for more than one station you need to create separate DWD_OpenData devices.
  
  Notes: This function is not suitable to rely on to ensure your safety! It will cause significant download traffic if used in continuous mode (more than 1 GB per day are possible). The device needs to keep all alerts for Germany in memory at all times to comply with the requirements of the common alerting protocol (CAP), even if only one warn cell is monitored. Depending on the weather activity this requires noticeable amounts of memory and CPU.

Installation notes:


• This module requires the additional Perl module XML::LibXML for weather alerts. It can be installed depending on your OS and your preferences (e.g. sudo apt-get install libxml-libxml-perl or using CPAN).


• Data is fetched from the DWD Open Data Server using the FHEM module HttpUtils. If you use a proxy for internet access you need to set the global attribute proxy to a suitable value in the format myProxyHost:myProxyPort.


• Verify that your FHEM time is correct by entering {localtime()} into the FHEM command line. If not, check the system time and timezone of your FHEM server and adjust appropriately. It may be necessary to add export TZ=`cat /etc/timezone` or something similar to your FHEM start script /etc/init.d/fhem or your system configuration file /etc/profile. If /etc/timezone does not exists or is undefined execute tzselect to find your timezone and write the result into this file. After making changes restart FHEM and enter {$ENV{TZ}} into the FHEM command line to verify. To fix the timezone temporarily without restarting FHEM enter {$ENV{TZ}='Europe/Berlin'} or something similar into the FHEM command line. Again use tzselect to fine a valid timezone name.


• The weekday of the forecast will be in the language of your FHEM system. Enter {$ENV{LANG}} into the FHEM command line to verify. If nothing is displayed or you see an unexpected language setting, add export LANG=de_DE.UTF-8 or something similar to your FHEM start script, restart FHEM and check again. If you get a locale warning when starting FHEM the required language pack might be missing. It can be installed depending on your OS and your preferences (e.g. dpkg-reconfigure locales, apt-get install language-pack-de or something similar).


• The digits in a warncell id of a communeunion or a district are mostly identical to an Amtliche Gemeindekennziffer if you strip of the 1st digit from the warncell id. You can lookup an Amtliche Gemeindekennziffer using the name of a communeunion or district e.g. at Statistische Ämter des Bundes und der Länder. Then add 8 for a communeunion or 1 or 9 for a district at the beginning and try to find an exact or near match in the Warncell-IDs for CAP alerts catalogue. This approach is an alternative to guessing the right warncell id by the name of a communeunion or district.


• Like some other Perl modules this module temporarily modifies the TZ environment variable for timezone conversions. This may cause unexpected results in multi threaded environments.


• The forecast reading names do not contain absolute days or hours to keep them independent of summertime adjustments. Forecast days are counted relative to "today" of the timezone defined by the attribute of the same name or the timezone specified by the Perl TZ environment variable if undefined.


• Starting on 17.09.2018 the forecast data from the DWD is no longer available in CSV format and is based on the KML format instead. While most of the properties of the CSV format are still available in KML format, their names have changed and you will have to adjust your existing installation accordingly.


• This module provides sun position related information that is not available from the DWD. The properties for sunrise, sunset and sun up are calculated for the upper solar limb at given altitude and typical atmospheric refraction.



Define

define <name> DWD_OpenData


Get


• get forecast [<station code>]
  Fetch forecast for a station from DWD and update readings. The station code is either a 5 digit WMO station code or an alphanumeric DWD station code from the MOSMIX station catalogue. If the attribute forecastStation is set, no station code must be provided.
  The operation is performed non-blocking.


• get alerts [<warncell id>]
  Set alert readings for given warncell id. A warncell id is a 9 digit numeric value from the Warncell-IDs for CAP alerts catalogue. Supported ids start with 8 (communeunion), 1 and 9 (district) or 5 (coast). If the attribute alertArea is set, no warncell id must be provided.
  If the alerts cache is empty or older than 15 minutes the cache is updated first and the operation is non-blocking. If the cache is valid the operation is blocking. If a cache update is already in progress the operation fails.
  To verify that alerts are provided for the warncell id you selected you should consult another source, wait for an alert situation and compare.


• get updateAlertsCache { communeUnions|districts|all }
  Fetch alerts to update the alerts cache. Note that 'coast' alerts are part of the 'communeUnion' cache data.
  The operation is performed non-blocking because it typically requires several seconds. If a cache update is already in progress the operation fails.
  This command can be used before querying several warncells in sequence or to force a higher update frequency than the built-in 15 minutes. Note that all DWD_OpenData devices share a single alerts cache so updating the cache via one of the devices is sufficient.


Attributes



• disable {0|1}, default: 0
  Disable fetching data.


• timezone <tz>, default: OS dependent
  IANA TZ string for date and time readings (e.g. "Europe/Berlin"), can be used to assume the perspective of a station that is in a different timezone or if your OS timezone settings do not match your local timezone. Alternatively you may use tzselect on the Linux command line to find a valid timezone string.


forecast related:


• forecastStation <station code>, default: none
  Setting forecastStation enables automatic updates every hour. The station code is either a 5 digit WMO station code or an alphanumeric DWD station code from the id column of the MOSMIX station catalogue.
  Note: When value is changed all existing forecast readings will be deleted.


• forecastDays <n>, default: 6
  Limits number of forecast days. Setting 0 will still provide forecast data for today. The maximum value is 9 (for today and 9 future days).


• forecastResolution {1|3|6}, default: 6 h
  Time resolution (number of hours between 2 samples).
  Note: When value is changed all existing forecast readings will be deleted.


• forecastProperties [<p1>[,<p2>]...], default: Tx, Tn, Tg, TTT, DD, FX1, Neff, RR6c, RRhc, Rh00, ww
  See the DWD forecast property defintions for more details.
  Notes:
  - Not all properties are available for all stations and for all hours.
  - If you remove a property from the list then already existing readings must be deleted manually in continuous mode.
  


• forecastWW2Text {0|1}, default: 0
  Create additional wwd readings containing the weather code as a descriptive text in German language.


• forecastPruning {0|1}, default: 0
  Search for and delete forecast readings that are more then one day older then other forecast readings of the same day. Pruning will be performed after a successful forecast update.
  Notes:
  - Intended to maintain data consistency e.g. when a forecast station changes the reporting hour of a forecast property.
  - Requires noticable extra computing resources and may cause side effects if your FHEM configuration depends on a reading that is deleted.
  


alert related:


• alertArea <warncell id>, default: none
  Setting alertArea enables automatic updates of the alerts cache every 15 minutes.
  A warncell id is a 9 digit numeric value from the Warncell-IDs for CAP alerts catalogue. Supported ids start with 7 and 8 (communeunion), 1 and 9 (district) or 5 (coast). To verify that alerts are provided for the warncell id you selected you should consult another source, wait for an alert situation and compare.
• alertLanguage [DE|EN], default: DE
  Language of descriptive alert properties.
• alertExcludeEvents <event code>, default: none
  Comma separated list of numeric events codes for which no alerts should be created.
  Only minor alerts may be suppressed. Use at your own risk!


Readings

The forecast readings are build like this:

fc<day>_[<sample>_]<property>

A description of the more than 70 properties available and their units of measurement can be found here. The units of measurement for temperatures and wind speeds are converted to °C and km/h respectively. Only a few choice properties are listed in the following paragraphs:


• day - relative day (0 .. 9) based on the timezone attribute where 0 is today


• sample - relative time (0 .. 3, 7 or 23) equivalent to multiples of 6, 3 or 1 hours UTC depending on the forecastResolution attribute


• day properties (typically for 06:00 station time, see raw data of station for actual time relation)
  • date - date based on the timezone attribute
  • weekday - abbreviated weekday based on the timezone attribute in the language of your FHEM system
  • Tn [°C] - minimum temperature of previous 12 hours
  • Tx [°C] - maximum temperature of previous 12 hours (typically at 18:00 station time)
  • Tm [°C] - average temperature of previous 24 hours
  • Tg [°C] - minimum temperature 5 cm above ground of previous 12 hours
  • PEvap [kg/m2] - evapotranspiration of previous 24 hours
  • SunD [s] - total sunshine duration of previous day


• hour properties
  • time - time based on the timezone attribute
  • TTT [°C] - dry bulb temperature at 2 meter above ground
  • Td [°C] - dew point temperature at 2 meter above ground
  • DD [°] - average wind direction 10 m above ground
  • FF [km/h] - average wind speed 10 m above ground
  • FX1 [km/h] - maximum wind speed in the last hour
  • SunD1 [s] - sunshine duration in the last hour
  • SunD3 [s] - sunshine duration in the last 3 hours
  • RR1c [kg/m2] - precipitation amount in the last hour
  • RR3c [kg/m2] - precipitation amount in the last 3 hours
  • RR6c [kg/m2] - precipitation amount in the last 6 hours
  • R600 [%] - probability of rain in the last 6 hours
  • RRhc [kg/m2] - precipitation amount in the last 12 hours
  • Rh00 [%] - probability of rain in the last 12 hours
  • RRdc [kg/m2] - precipitation amount in the last 24 hours
  • Rd00 [%] - probability of rain in the last 24 hours
  • ww - weather code (see WMO 4680/4677, SYNOP)
  • wwd - German weather code description
  • VV [m] - horizontal visibility
  • Neff [%] - effective cloud cover
  • Nl [%] - lower level cloud cover below 2000 m
  • Nm [%] - medium level cloud cover below 7000 m
  • Nh [%] - high level cloud cover above 7000 m
  • PPPP [hPa] - pressure equivalent at sea level
• extra day properties, not provided by the DWD
  • SunRise - time of sunrise based on the timezone attribute
  • SunSet - time of sunset based on the timezone attribute
• extra hour properties, not provided by the DWD
  • SunAz [°] - sun azimuth
  • SunEl [°] - sun elevation
  • SunUp - sun up (0: night, 1: day)

Additionally there are global forecast readings:
• fc_state - state of the last forecast update, possible values are 'updated' and 'error: ...'
• fc_station - forecast station code (WMO or DWD)
• fc_description - station description
• fc_coordinates - world coordinate and height of station
• fc_time - time the forecast was issued based on the timezone attribute
• fc_copyright - legal information, must be displayed with forecast data, see DWD usage conditions

The alert readings are ordered by onset and are build like this:

a_<index>_<property>


• index - alert index, starting with 0, total a_count, ordered by onset


• alert properties
  • category - 'Met' or 'Health'
  • event - numeric event code, see DWD documentation for details
  • eventDesc - short event description in selected language
  • eventGroup - event group, see DWD documentation for details
  • responseType - 'None' = no instructions, 'Prepare' = instructions, 'AllClear' = alert cleared
  • urgency - 'Immediate' = warning or 'Future' = information
  • severity - 'Minor', 'Moderate', 'Severe' or 'Extreme'
  • areaColor - RGB colour depending on urgency and severity, comma separated decimal triple
  • onset - start time of alert based on the timezone attribute
  • expires - end time of alert based on the timezone attribute
  • headline - headline in selected language, typically a combination of the properties urgency and event
  • description - description of the alert in selected language
  • instruction - safety instructions in selected language
  • area - numeric warncell id
  • areaDesc - description of area, e.g. 'Stadt Berlin'
  • altitude - min. altitude [m]
  • ceiling - max. altitude [m]


Additionally there are some global alert readings:


• a_state - state of the last alerts update, possible values are 'updated' and 'error: ...'
• a_time - time the last alerts update was downloaded, based on the timezone attribute
• a_count - number of alerts available for selected warncell id
• a_copyright - legal information, must be displayed with forecast data, see DWD usage conditions, not available if count is zero

Alerts should be considered active for onset <= now < expires and responseType != 'AllClear' independent of urgency.
Inactive alerts with responseType = 'AllClear' may provide relevant instructions.

Note that all alert readings are completely replaced and reindexed with each update!

Further information regarding the alert properties can be found in the documentation of the CAP DWS Profile.

Performance

Note that depending on your device configuration each forecast consists of quite a lot of readings and each reading update will cause a FHEM event that needs to be processed. Depending on your hardware and your FHEM configuration this will take several hundred milliseconds. If you need to improve overall performance you can limit the number of readings created by setting a) the attribute forecastProperties to the ones you actually use, b) the attribute forecastResolution to the highest value suitable for your purposes and c) the attribute forecastDays to the lowest number suitable for your purposes. To further reduce the event processing overhead you can set the attribute event-on-update-reading to a small list of important reading that really need events (e.g. state,fc_state,a_state). For almost the same reason be selective when creating a log device. If you use wildcards for all readings without filtering either at the source device with readingFnAttributes or at the destination device with a regexp you will get significant extra file IO when the readings are updated and quite a lot of data.

Dashboard

Creates a Dashboard in any group and/or devices can be arranged. The positioning may depend the objects and column width are made arbitrarily by drag'n drop. Also, the width and height of an object can be increased beyond the minimum size.

Note:
A group name in the dashboard respectively the attribute "dashboard_tabXgroups" equates the group name in FHEM and depict the devices which are contained in that group.

Define


• define <name> Dashboard
  
  Example:
  define anyViews Dashboard
  
  Bestpractice beginner configuration:
  define anyViews Dashboard
  attr anyViews dashboard_colcount 2
  attr anyviews dashboard_rowcentercolwidth 30,70
  attr anyViews dashboard_tab1groups <Group1>,<Group2>,<Group3>
  

Set


• set <name> activateTab <TabNo>
  The Tab with the defined number will be activated. If the attribute "dashboard_homeTab" is set, this defined tab will be reactivated at next browser refresh.
  
  
• set <name> lock
  Locks the Dashboard so that no position changes can be made.


• set <name> unlock
  Unlock the Dashboard,
  

Get
• get <name> config
  Delivers the configuration of the dashboard back.
  
  
• get <name> icon <icon name>
  Delivers the path and full name of the denoted icon back.
  
  Example:
  get <name> icon measure_power_meter
  


Attributes


• dashboard_backgroundimage
  Displays a background image for the complete dashboard. The image is not stretched in any way. So the size should match/extend the dashboard height/width. The relative path to "./www/images" has to be used.
  
  Example
  attr dashboard_backgroundimage dashboard/cam_video.PNG
  # File ./www/images/dashboard/cam_video.PNG is shown
  attr dashboard_backgroundimage cam_video.PNG
  # File ./www/images/cam_video.PNG is shown
  


• dashboard_backgroundimage
  Displays a background image for the complete dashboard. The image is not stretched in any way. So the size should match/extend the dashboard height/width. Only the filename has to be set.
  The file must be at any location below the directory "./www/images/".
  Suggestion: Create the directory "./www/images/dashboard" and put the image file into.
  
  Example
  attr dashboard_backgroundimage cam_video.PNG
  


• dashboard_colcount
  Number of columns in which the groups can be displayed. Nevertheless, it is possible to have multiple groups
  to be positioned in a column next to each other. This is depend on the width of columns and groups.
  Default: 1


• dashboard_debug
  Show Hiddenfields. Only for Maintainer's use.
  Default: 0


• dashboard_flexible
  If set to a value > 0, the widgets are not positioned in columns any more but can be moved freely to any position in the tab.
  The value for this parameter also defines the grid, in which the position "snaps in".
  Default: 0


• dashboard_hideGroupHeader
  If set, the header containing the group name and group icon above the pictured FHEM-group (see also dashboard_tab1groups) is hidden.
  Default: 0


• dashboard_homeTab
  Specifies which tab is activated. If it isn't set, the last selected tab will also be the active tab.
  Default: 1


• dashboard_row
  To select which rows are displayed. top only; center only; bottom only; top and center; center and bottom; top,center and bottom.
  Default: center


• dashboard_rowbottomheight
  Height of the bottom row in which the groups may be positioned.
  Default: 250


• dashboard_rowcenterheight
  Height of the center row in which the groups may be positioned.
  Default: 400


• dashboard_rowcentercolwidth
  About this attribute, the width of each column of the middle Dashboardrow can be set. It can be stored for each column a separate value. The values ​​must be separated by a comma (no spaces). Each value determines the column width in%! The first value specifies the width of the first column, the second value of the width of the second column, etc. Is the sum of the width greater than 100 it is reduced. If more columns defined as widths the missing widths are determined by the difference to 100. However, are less columns are defined as the values ​​of ignores the excess values​​.
  Default: 100


• dashboard_rowtopheight
  Height of the top row in which the groups may be positioned.
  Default: 250


• dashboard_showfullsize
  Hide FHEMWEB Roomliste (complete left side) and Page Header if Value is 1.
  Default: 0


• dashboard_showtabs
  Displays the Tabs/Buttonbar on top or bottom, or hides them. If the Buttonbar is hidden lockstate is "lock" is used.
  Default: tabs-and-buttonbar-at-the-top


• dashboard_showtogglebuttons
  Displays a Toogle Button on each Group do collapse.
  Default: 0


• dashboard_tab1backgroundimage
  Shows a background image for the tab. (also valid for further dashboard_tabXbackgroundimage)
  The image is not stretched in any way, it should therefore match the tab size or extend it. Only the filename has to be set.
  The file must be at any location below the directory "./www/images/".
  Suggestion: Create the directory "./www/images/dashboard" and put the image file into.
  
  Example
  attr dashboard_tab1backgroundimage cam_video.PNG
  


• dashboard_tab1colcount
  Number of columns for a specific tab in which the groups can be displayed. (also valid for further dashboard_tabXcolcount)
  Nevertheless, it is possible to have multiple groups to be positioned in a column next to each other. This depends on the width of columns and groups.
  Default: <dashboard_colcount>


• dashboard_tab1devices
  DevSpec list of devices that should appear in the tab. (also valid for further dashboard_tabXdevices)
  The format is:
  
  
  GROUPNAME:devspec1,devspec2,...,devspecX:ICONNAME
  
  
  ICONNAME is optional. Also GROUPNAME is optional. In case of missing GROUPNAME, the matching devices are not grouped, but shown as separate widgets without titles. For further details on the DevSpec format see DevSpec.


• dashboard_tab1groups
  Comma separated list of FHEM groups (see attribute "group" in a device) to be displayed in Tab. (also valid for further dashboard_tabXgroups)
  Each group can be given an icon for this purpose the group name, the following must be completed ":<icon>@<color>"
  
  Example:
  Light:Icon_Fisch@blue,AVIcon_Fisch@red,Single Lights:Icon_Fisch@yellow
  
  Additionally a group can contain a regular expression to show all groups matching a criteria.
  
  Example:
  .*Light.* to show all groups that contain the string "Light"


• dashboard_tab1icon
  Set the icon for a Tab. (also valid for further dashboard_tabXicon)
  There must exist an icon with the name ico.(png|svg) in the modpath directory. If the image is referencing an SVG icon, then you can use the @colorname suffix to color the image.


• dashboard_tab1name
  Title of Tab. (also valid for further dashboard_tabXname)


• dashboard_tab1sorting
  Contains the position of each group in Tab. (also valid for further dashboard_tabXsorting)
  Value is written by the "Set" button. It is not recommended to take manual changes.


• dashboard_noLinks
  No link generation to the detail view of the devices takes place.
  
  Note:
  Some device types deliver the links to their detail view integrated in the device. In such cases you have to deactivate the link generation inside of the device (for example in SMAPortalSPG).


• dashboard_webRefresh
  With this attribute the FHEMWEB-Devices are determined, which:
  
  
  • are activating the tab of a dashboard when the attribute "dashboard_homeTab" will be set
  • are positioning to the tab specified by command "set <name> activateTab"
  
  Default: all
  


• dashboard_width
  To determine the Dashboardwidth. The value can be specified, or an absolute width value (eg 1200) in pixels in% (eg 80%).
  Default: 100%

DbLog

With DbLog events can be stored in a database. SQLite, MySQL/MariaDB and PostgreSQL are supported databases.

Prereqisites

The Perl-modules DBI and DBD::<dbtype> are needed to be installed (use cpan -i <module> if your distribution does not have it).

On a debian based system you may install these modules for instance by:



DBI	: sudo apt-get install libdbi-perl
MySQL	: sudo apt-get install [mysql-server] mysql-client libdbd-mysql libdbd-mysql-perl (mysql-server only for local MySQL Server installation)
MariaDB	: sudo apt-get install [mariadb-server] mariadb-client libdbd-mariadb-perl (mariadb-server only for local MariaDB Server installation)
SQLite	: sudo apt-get install sqlite3 libdbi-perl libdbd-sqlite3-perl
PostgreSQL	: sudo apt-get install libdbd-pg-perl



Preparations

At first you need to install and setup the database. The installation of database system itself is not described here, please refer to the installation instructions of your database.

Note:
In case of fresh installed MySQL/MariaDB system don't forget deleting the anonymous "Everyone"-User with an admin-tool if existing.

Sample code and Scripts to prepare a MySQL/PostgreSQL/SQLite database you can find in SVN -> contrib/dblog/db_create_<DBType>.sql.
(Caution: The local FHEM-Installation subdirectory ./contrib/dblog doesn't contain the freshest scripts!)

The older standard installation of the MySQL/MariaDB database provided for the use of the utf8_bin collation. With this setting, characters up to 3 bytes long can be stored, which is generally sufficient. However, if characters with a length of 4 bytes (e.g. emojis) are to be stored in the database, the utf8mb4 character set must be used.
Accordingly, in this case the MySQL/MariaDB database would be created with the following statement:


CREATE DATABASE `fhem` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;

Note the key utf8 if the MySQL database driver is used (MODEL = MYSQL).

The database contains two tables: current and history.
The latter contains all events whereas the former only contains the last event for any given reading and device. Please consider the DbLogType implicitly to determine the usage of tables current and history.

The columns have the following meaning:



TIMESTAMP	: timestamp of event, e.g. 2007-12-30 21:45:22
DEVICE	: device name, e.g. Wetterstation
TYPE	: device type, e.g. KS300
EVENT	: event specification as full string, e.g. humidity: 71 (%)
READING	: name of reading extracted from event, e.g. humidity
VALUE	: actual reading extracted from event, e.g. 71
UNIT	: unit extracted from event, e.g. %



create index
Due to reading performance, e.g. on creation of SVG-plots, it is very important that the index "Search_Idx" or a comparable index (e.g. a primary key) is applied. A sample code for creation of that index is also available in mentioned scripts of SVN -> contrib/dblog/db_create_<DBType>.sql.

The index "Search_Idx" can be created, e.g. in database 'fhem', by these statements (also subsequently):



MySQL	: CREATE INDEX Search_Idx ON `fhem`.`history` (DEVICE, READING, TIMESTAMP);
MariaDB	: CREATE INDEX Search_Idx ON `fhem`.`history` (DEVICE, READING, TIMESTAMP);
SQLite	: CREATE INDEX Search_Idx ON `history` (DEVICE, READING, TIMESTAMP);
PostgreSQL	: CREATE INDEX "Search_Idx" ON history USING btree (device, reading, "timestamp");


For the connection to the database a configuration file is used. The configuration file is copied e.g. to /opt/fhem and has the structure shown below. The specifications are to be adapted according to the used environment (uncomment and change corresponding lines):



    ####################################################################################
    # database configuration file
    #
    # NOTE:
    # If you don't use a value for user / password please delete the leading hash mark
    # and write 'user => ""' respectively 'password => ""' instead !
    #
    #
    ## for MySQL
    ####################################################################################
    #%dbconfig= (
    #    connection => "mysql:database=fhem;host=<database host>;port=3306",
    #    # if want communication over socket-file instead of TCP/IP transport, use:
    #    # connection => "mysql:database=fhem;mysql_socket=</path/socket-file>",
    #    user => "fhemuser",
    #    password => "fhempassword",
    #    # optional enable UTF-8 support
    #    # (full UTF-8 support exists from DBD::mysql version 4.032, but installing
    #    # 4.042 is highly suggested)
    #    utf8 => 1,
    #    # optional enable communication compression between client and server
    #    compression => 1
    #);
    ####################################################################################
    #
    ## for MariaDB
    ####################################################################################
    #%dbconfig= (
    #    connection => "MariaDB:database=fhem;host=<database host>;port=3306",
    #    # if want communication over socket-file instead of TCP/IP transport, use:
    #    # connection => "MariaDB:database=fhem;mariadb_socket=</path/socket-file>",
    #    user => "fhemuser",
    #    password => "fhempassword",
    #    # optional enable communication compression between client and server
    #    compression => 1
    #);
    ####################################################################################
    #
    ## for PostgreSQL
    ####################################################################################
    #%dbconfig= (
    #    connection => "Pg:database=fhem;host=<database host>",
    #    user => "fhemuser",
    #    password => "fhempassword"
    #);
    ####################################################################################
    #
    ## for SQLite (username and password stay empty for SQLite)
    ####################################################################################
    #%dbconfig= (
    #    connection => "SQLite:dbname=/opt/fhem/fhem.db",
    #    user => "",
    #    password => ""
    #);
    ####################################################################################
    

If configDB is used, the configuration file has to be uploaded into the configDB!

Note about special characters:
If special characters, e.g. @,$ or % which have a meaning in the perl programming language are used in a password, these special characters have to be escaped. That means in this example you have to use: \@,\$ respectively \%.

DbLog specific events

DbLog generates events depending on the initialisation status of the DbLog device:



FRAME_INITIALIZED	- The basic framework is initialised. Blocking (Get) commands can be executed.
SUBPROC_INITIALIZED	- The SupProcess is ready for use. Non-blocking (set) commands and Data logging can be executed.
SUBPROC_DISCONNECTED	- The SupProcess was separated from the DB.
SUBPROC_STOPPED	- The SupProcess has been stopped.




Define


define <name> DbLog <configfilename> <regexp>

<configfilename> is the prepared configuration file.
<regexp> is identical to the specification of regex in the FileLog definition.

Example:
define myDbLog DbLog /etc/fhem/db.conf .*:.*
all events will stored into the database

After you have defined your DbLog-device it is recommended to run the configuration check


get <name> configCheck


This check reports some important settings and gives recommendations back to you if proposals are indentified.

DbLog distinguishes between the synchronous (default) and asynchronous logmode. The logmode is adjustable by the asyncMode. Since version 2.13.5 DbLog is supporting primary key (PK) set in table current or history. If you want use PostgreSQL with PK it has to be at lest version 9.5.

The content of VALUE will be optimized for automated post-processing, e.g. yes is translated to 1

The stored values can be retrieved by the following code like FileLog:

get myDbLog - - 2012-11-10 2012-11-10 KS300:temperature::

transfer FileLog-data to DbLog

There is the special module 98_FileLogConvert.pm available to transfer filelog-data to the DbLog-database.
The module can be downloaded here or from directory ./contrib instead. Further information and help you can find in the corresponding Forumthread .


Reporting and Management of DbLog database content

By using SVG database content can be visualized.
Beyond that the module DbRep can be used to prepare tabular database reports or you can manage the database content with available functions of that module.


Troubleshooting

If after successful definition the DbLog-device doesn't work as expected, the following notes may help:


• Have the preparatory steps as described in commandref been done ? (install software components, create tables and index)
• Was "get <name> configCheck" executed after definition and potential errors fixed or rather the hints implemented ?
• If configDB is used ... has the database configuration file been imported into configDB (e.g. by "configDB fileimport ./db.conf") ?
• When creating a SVG-plot and no drop-down list with proposed values appear -> set attribute "DbLogType" to "Current/History".

If the notes don't lead to success, please increase verbose level of the DbLog-device to 4 or 5 and observe entries in logfile relating to the DbLog-device. For problem analysis please post the output of "list <name>", the result of "get <name> configCheck" and the logfile entries of DbLog-device to the forum thread.



Set


• set <name> addCacheLine YYYY-MM-DD HH:MM:SS|<device>|<type>|<event>|<reading>|<value>|[<unit>]
  
  
  In asynchronous mode a new dataset is inserted to the Cache and will be processed at the next database sync cycle.
  
  Example:
  set <name> addCacheLine 2017-12-05 17:03:59|MaxBathRoom|MAX|valveposition: 95|valveposition|95|%
  
  
  
• set <name> addLog <devspec>:<Reading> [Value] [CN=<caller name>] [!useExcludes]
  
  
  Inserts an additional log entry of a device/reading combination into the database.
  Any readings specified in the "DbLogExclude" attribute (in the source device) will not be logged, unless they are included in the "DbLogInclude" attribute or the addLog call was made with the "!useExcludes" option.
  
  

  <devspec>:<Reading>	The device can be specified as device specification.
  	The specification of "Reading" is evaluated as a regular expression.
  	If the reading does not exist and the value "Value" is specified, the reading
  	will be inserted into the DB if it is not a regular expression and a valid reading name.
  Value	Optionally, "Value" can be specified for the reading value.
  	If Value is not specified, the current value of the reading is inserted into the DB.
  CN=<caller name>	With the key "CN=" (Caller Name) a string, e.g. the name of the calling device,
  	can be added to the addLog call.
  	With the help of the function stored in the attribute valueFn
  	this key can be evaluated via the variable $CN.
  !useExcludes	addLog by default takes into account the readings excluded with the "DbLogExclude" attribute.
  	With the keyword "!useExcludes" the set attribute "DbLogExclude" is ignored.

  
  The database field "EVENT" is automatically filled with "addLog".
  There will be no additional event created in the system!
  
  Examples:
  set <name> addLog SMA_Energymeter:Bezug_Wirkleistung
  set <name> addLog TYPE=SSCam:state
  set <name> addLog MyWetter:(fc10.*|fc8.*)
  set <name> addLog MyWetter:(wind|wind_ch.*) 20 !useExcludes
  set <name> addLog TYPE=CUL_HM:FILTER=model=HM-CC-RT-DN:FILTER=subType!=(virtual|):(measured-temp|desired-temp|actuator)
  
  set <name> addLog USV:state CN=di.cronjob
  
  In the valueFn function the caller "di.cronjob" is evaluated via the variable $CN and depending on this the timestamp of this addLog is corrected:
  
  valueFn = if($CN eq "di.cronjob" and $TIMESTAMP =~ m/\s00:00:[\d:]+/) { $TIMESTAMP =~ s/\s([^\s]+)/ 23:59:59/ }


• set <name> clearReadings
  
  
  This function clears readings which were created by different DbLog-functions.
  
  
• set <name> commitCache
  
  
  In asynchronous mode (asyncMode=1), the cached data in memory will be written into the database and subsequently the cache will be cleared.
  Thereby the internal timer for the asynchronous mode Modus will be set new.
  
  
• set <name> configCheck
  
  
  Checks some important settings and give recommendations back to you if proposals are identified.
  (Note: This command is deprecated and will be removed in next releases. Use "get <name> configCheck" instead.)
  
  
• set <name> count
  
  
  Determines the number of records in the tables current and history and writes the results to the readings countCurrent and countHistory.
  
  Note
  During the runtime of the command, data to be logged are temporarily stored in the memory cache and written to the database written to the database after the command is finished.


• set <name> deleteOldDays <n>
  
  
  Deletes records older than <n> days in table history. The number of deleted records is logged in Reading lastRowsDeleted.
  
  Note
  During the runtime of the command, data to be logged are temporarily stored in the memory cache and written to the database written to the database after the command is finished.


• set <name> eraseReadings
  
  
  This function deletes all readings except reading "state".
  
  
• set <name> exportCache [nopurge | purgecache]
  
  
  If DbLog is operated in asynchronous mode, the cache can be written to a text file with this command.
  The file is created by default in the directory (global->modpath)/log/. The destination directory can be changed with the expimpdir attribute.
  
  The name of the file is generated automatically and contains the prefix "cache_<name>" followed by the current timestamp.
  
  Example
  cache_LogDB_2017-03-23_22-13-55
  
  The "nopurge" and "purgecache" options determine whether or not the cache contents are to be deleted after the export. With "nopurge" (default) the cache content is preserved.
  The exportCacheAppend attribute determines whether with each export operation a new export file is created (default) or the cache content is appended to the latest existing export file.


• set <name> importCachefile <file>
  
  
  Imports a file written with "exportCache" into the database.
  The available files are searched by default in the directory (global->modpath)/log/ and a drop-down list is generated with the files are found.
  The source directory can be changed with the expimpdir attribute.
  Only the files matching the pattern "cache_<name>" are displayed.
  
  Example
  cache_LogDB_2017-03-23_22-13-55
  if the DbLog device is called "LogDB".
  
  After a successful import the file is prefixed with "impdone_" and no longer appears in the drop-down list. If a cache file is to be imported into a database other than the source database, the name of the DbLog device in the file name can be adjusted so that this file appears in the drop-down list.
  
  Note
  During the runtime of the command, data to be logged are temporarily stored in the memory cache and written to the database after the command is finished.


• set <name> listCache
  
  
  Lists the data cached in the memory cache.
  
  
• set <name> purgeCache
  
  
  In asynchronous mode (asyncMode=1), the in memory cached data will be deleted. With this command data won't be written from cache into the database.
  
  
• set <name> reduceLog <no>[:<nn>] [average[=day]] [exclude=device1:reading1,device2:reading2,...]
  
  
  Reduces historical records older than <no> days and (optionally) newer than <nn> days to one record (the first) per hour per device & reading.
  Inside device/reading SQL wildcards "%" and "_" can be used.
  
  The optional specification of 'average' or 'average=day' not only cleans the database, but also reduces all numerical values of an hour or a day are reduced to a single average value.
  
  Optionally, the last parameter "exclude=device1:reading1,device2:reading2,...." can be specified to exclude device/reading combinations from reduceLog.
  Instead of "exclude", "include=device:reading" can be specified as the last parameter in order to limit the SELECT query executed on the database. This reduces the RAM load and increases performance. The option "include" can only be specified with a device:reading combination.
  
  
  Examples:
  set <name> reduceLog 270 average include=Luftdaten_remote:%
  set <name> reduceLog 100:200 average exclude=SMA_Energymeter:Bezug_Wirkleistung
  
  Note
  During the runtime of the command, data to be logged is temporarily stored in the memory cache and written to the database after the command is finished.


• set <name> reopen [n]
  
  
  Closes the database and then immediately opens it again if no time [n] in seconds has been specified.
  If an optional delay time [n] in seconds has been specified, the connection to the database will be closed and reconnected only after [n] seconds have elapsed.
  During the time of the database closure, events to be logged are stored in the memory cache and written to the database after the reconnect.


• set <name> rereadcfg
  
  
  The configuration file is read in again.
  After reading, an existing database connection is terminated and re-established with the configured connection data.


• set <name> stopSubProcess
  
  
  A running SubProcess is terminated.
  As soon as a new subprocess is required by a Log operation, an automatic reinitialization of a process takes place.
  
  Note
  The re-initialization of the sub-process during runtime causes an increased RAM consumption until to a FHEM restart .


• set <name> userCommand <validSelectStatement>
  
  
  Executes simple SQL Select commands on the database.
  The result of the statement is written to the reading "userCommandResult". The result can be only one line.
  The execution of SQL commands in DbLog is deprecated. The DbRep evaluation module should be used for this purpose.
  
  Note
  During the runtime of the command, data to be logged are temporarily stored in the memory cache and written to the database written to the database after the command is finished.



Get


• get <name> configCheck
  
  
  A number of key settings are reviewed and recommendations are made if potential improvements are identified.


• get <name> ReadingsMaxVal[Timestamp] <Device> <Reading> <default>
  
  Determines the record with the largest value of the specified Device / Reading combination from the history table.
  Only the value or the combination of value and timestamp is returned as string "<Wert> , <Timestamp>".
  <default> specifies a defined return value if no value can be determined.
  
  Note:
  This database retrieval works blocking and influences FHEM if the database does not respond or not responds sufficiently fast. For non-blocking database queries is referred to the module DbRep. .


• get <name> ReadingsMinVal[Timestamp] <Device> <Reading> <default>
  
  
  Determines the record with the smallest value of the specified device / reading combination from the history table.
  Only the value or the combination of value and timestamp is returned as string "<Wert> , <Timestamp>".
  <default> specifies a defined return value if no value can be determined.
  
  Note:
  This database retrieval works blocking and influences FHEM if the database does not respond or not responds sufficiently fast. For non-blocking database queries is referred to the module DbRep.


• get <name> ReadingsAvgVal <Device> <Reading> <default>
  
  
  Determines the average value of the specified Device / Reading combination from the history table.
  The simple arithmetic average value is returned.
  <default> specifies a defined return value if no value can be determined.
  
  Note:
  This database retrieval works blocking and influences FHEM if the database does not respond or not responds sufficiently fast. For non-blocking database queries is referred to the module DbRep.


• get <name> ReadingsVal[Timestamp] <Device> <Reading> <default>
  
  
  Reads the last (newest) record stored in the history table of the specified Device / Reading combination.
  Only the value or the combination of value and timestamp is returned as string "<Wert> , <Timestamp>".
  <default> specifies a defined return value if no value can be determined.
  
  Note:
  This database retrieval works blocking and influences FHEM if the database does not respond or not responds sufficiently fast. For non-blocking database queries is referred to the module DbRep.


• get <name> ReadingsTimestamp <Device> <Reading> <default>
  
  
  Reads the timestamp of the last (newest) record stored in the history table of the specified Device/Reading combination and returns this value.
  <default> specifies a defined return value if no value is found in the database.
  
  Note:
  This database retrieval works blocking and influences FHEM if the database does not respond or not responds sufficiently fast. For non-blocking database queries is referred to the module DbRep.


• get <name> retrieve <querytype> <device|table> <reading> <from> <to> <offset> <limit>
  
  
  Reads data from the database table history and returns the results formatted as JSON.
  The query method or the desired query result is determined by the specified <querytype>.
  Each <querytype> may require additional parameters according to the following table. Parameters not entered must always be entered as "" if another parameter is entered afterwards.
  
  

  alldevices	Determines all devices stored in the database.
  allreadings	Determines all readings stored in the database for a specific device.
  	required parameters: <device>
  count	Returns the number of records of the specified table.
  	required parameters: <table> (history or current)
  fetchrows	Determines the stored records of a certain period.
  	The number of records in the defined period is returned as the "totalcount" key.
  	required parameters: <from>, <to>, <offset>, <limit>
  last	Lists the last 10 saved events.
  	possible parameters: <limit> (overwrites the default 10)
  timerange	Determines the stored data sets of the specified Device / Reading combination.
  	required parameters: <device>, <reading>, <from>, <to>
  hourstats	Calculates the statistics SUM, AVG, MIN, MAX, COUNT for one hour.
  	required parameters: <device>, <reading>, <from>, <to>
  daystats	Calculates the statistics SUM, AVG, MIN, MAX, COUNT for one day.
  	required parameters: <device>, <reading>, <from>, <to>
  weekstats	Calculates the statistics SUM, AVG, MIN, MAX, COUNT for one week.
  	required parameters: <device>, <reading>, <from>, <to>
  monthstats	Calculates the statistics SUM, AVG, MIN, MAX, COUNT for one month.
  	required parameters: <device>, <reading>, <from>, <to>
  yearstats	Calculates the statistics SUM, AVG, MIN, MAX, COUNT for one year.
  	required parameters: <device>, <reading>, <from>, <to>

  
  Note:
  This database retrieval works blocking and influences FHEM if the database does not respond or not responds sufficiently fast. For non-blocking database queries is referred to the module DbRep.
  
  Examples:
  • get LogSQLITE3 retrieve alldevices
  • get LogSQLITE3 retrieve allreadings MySTP_5000
  • get LogSQLITE3 retrieve last "" "" "" "" "" 50
  • get LogSQLITE3 retrieve count history
  • get LogSQLITE3 retrieve timerange MySTP_5000 etotal 2023-01-01_00:00:00 2023-01-25_00:00:00
  • get LogSQLITE3 retrieve fetchrows MySTP_5000 "" 2023-01-01_00:00:00 2023-01-25_00:00:00 0 100
  • get LogSQLITE3 retrieve fetchrows "" etotal 2023-01-01_00:00:00 2023-01-25_00:00:00 0 100
  • get LogSQLITE3 retrieve hourstats MySTP_5000 etotal 2023-01-01_00:00:00 2023-01-25_00:00:00


Get for the use of SVG plots


• get <name> <in> <out> <from> <to> <column_spec>
  
  Read data from the Database used by frontends to plot data without direct access to the Database.
  
  
  • <in>
    A parameter to establish compatibility with Filelog.
    In the definition of an SVG device this parameter corresponds to the specification of :<logfile> at the end of the definition.
    The following characteristics are allowed:
    
    • current: the values are read from the "current" table.
    • history: the values are read from the "history" table.
    • table_<table>: the values are read from the specified alternative table. The table (name) must be created in the database with lowercase letters.
      (example: table_energy, "energy" is the alternative table created in the database)
    • -: identical as "history
  
  
  • <out>
    A dummy parameter for FileLog compatibility. Setting by default to - to check the output for plot-computing.
    Set it to the special keyword all to get all columns from Database.
    • ALL: get all colums from table, including a header
    • Array: get the columns as array of hashes
    • INT: internally used by generating plots
    • -: default
  
  
  • <from> / <to>
    Used to select the data. Please use the following timeformat or an initial substring of it:
    
    YYYY-MM-DD_HH24:MI:SS
  
  
  • <column_spec>
    For each column_spec return a set of data separated by a comment line on the current connection.
    
    Syntax: <device>:<reading>:<default>:<fn>:<regexp>
    
    
    • <device>
      The name of the device. Case sensitive. Using a the joker "%" is supported.
    
    
    • <reading>
      The reading of the given device to select. Case sensitive. Using a the joker "%" is supported.
    
    
    • <default>
      no implemented yet
    
    
    • <fn> One of the following:
      • int
        Extract the integer at the beginning of the string. Used e.g. for constructs like 10%
      
      
      • int<digit>
        Extract the decimal digits including negative character and decimal point at the beginning og the string. Used e.g. for constructs like 15.7°C
      
      
      • delta-h / delta-d
        Return the delta of the values for a given hour or a given day. Used if the column contains a counter, as is the case for the KS300 rain column.
      
      
      • delta-ts
        Replaced the original value with a measured value of seconds since the last and the actual logentry.
      
      
    • <regexp>
      The string is evaluated as a perl expression. The regexp is executed before <fn> parameter.
      Note: The string/perl expression cannot contain spaces, as the part after the space will be considered as the next column_spec.
      
      Keywords
    • $val is the current value returned from the Database.
    • $ts is the current timestamp returned from the Database.
    • This Logentry will not print out if $val contains th keyword "hide".
    • This Logentry will not print out and not used in the following processing if $val contains th keyword "ignore".
  
  
  Examples:
  • get myDbLog - - 2012-11-10 2012-11-20 KS300:temperature
  
  
  • get myDbLog current ALL - - %:temperature
    you will get all actual readings "temperature" from all logged devices. Be careful by using "history" as inputfile because a long execution time will be expected!
  
  
  • get myDbLog - - 2012-11-10_10 2012-11-10_20 KS300:temperature::int1
    like from 10am until 08pm at 10.11.2012
  
  
  • get myDbLog - all 2012-11-10 2012-11-20 KS300:temperature
  
  
  • get myDbLog - - 2012-11-10 2012-11-20 KS300:temperature KS300:rain::delta-h KS300:rain::delta-d
  
  
  • get myDbLog - - 2012-11-10 2012-11-20 MyFS20:data:::$val=~s/(on|off).*/$1eq"on"?1:0/eg
    return 1 for all occurance of on* (on|on-for-timer etc) and 0 for all off*
  
  
  • get myDbLog - - 2012-11-10 2012-11-20 Bodenfeuchte:data:::$val=~s/.*B:\s([-\.\d]+).*/$1/eg
    Example of OWAD: value like this: "A: 49.527 % B: 66.647 % C: 9.797 % D: 0.097 V"
    and output for port B is like this: 2012-11-20_10:23:54 66.647
  
  
  • get DbLog - - 2013-05-26 2013-05-28 Pumpe:data::delta-ts:$val=~s/on/hide/
    Setting up a "Counter of Uptime". The function delta-ts gets the seconds between the last and the actual logentry. The keyword "hide" will hide the logentry of "on" because this time is a "counter of Downtime"

Get when used for webcharts


• get <name> <in> <out> <from> <to> <device> <querytype> <xaxis> <yaxis> <savename> <chartconfig> <pagingstart> <paginglimit>
  
  Query the Database to retrieve JSON-Formatted Data, which is used by the charting frontend (German Wiki: Neues Charting Frontend).
  
  
  • <name>
    The name of the defined DbLog, like it is given in fhem.cfg.
  
  
  • <in>
    Always set to -
  
  
  • <out>
    Is to be set to webchart.
  
  
  • <from> / <to>
    Used to select the data. Please use the following timeformat:
    
    YYYY-MM-DD_HH24:MI:SS
  
  
  • <device>
    A string which represents the device to query.
  
  
  • <querytype>
    A string which represents the method the query should use. Actually supported values are:
    getreadings to retrieve the possible readings for a given device
    getdevices to retrieve all available devices
    timerange to retrieve charting data, which requires a given xaxis, yaxis, device, to and from
    savechart to save a chart configuration in the database. Requires a given xaxis, yaxis, device, to and from, and a 'savename' used to save the chart
    deletechart to delete a saved chart. Requires a given id which was set on save of the chart
    getcharts to get a list of all saved charts.
    getTableData to get jsonformatted data from the database. Uses paging Parameters like start and limit.
    hourstats to get statistics for a given value (yaxis) for an hour.
    daystats to get statistics for a given value (yaxis) for a day.
    weekstats to get statistics for a given value (yaxis) for a week.
    monthstats to get statistics for a given value (yaxis) for a month.
    yearstats to get statistics for a given value (yaxis) for a year.
    
  
  
  • <xaxis>
    A string which represents the xaxis. It must be a valid field name, typically 'TIMESTAMP', of the history table.
  
  
  • <yaxis>
    A string representing the Y-axis to be set to the name of the reading to be evaluated.
  
  
  • <savename>
    A string which represents the name a chart will be saved with.
  
  
  • <chartconfig>
    A jsonstring which represents the chart to save.
  
  
  • <pagingstart>
    An integer used to determine the start for the sql used for query 'getTableData'.
  
  
  • <paginglimit>
    An integer used to set the limit for the sql used for query 'getTableData'.
  
  
  Examples:
  • get logdb - webchart "" "" "" getcharts
    Retrieves all saved charts from the Database
  
  
  • get logdb - webchart "" "" "" getdevices
    Retrieves all available devices from the Database
  
  
  • get logdb - webchart "" "" ESA2000_LED_011e getreadings
    Retrieves all available Readings for a given device from the Database
  
  
  • get logdb - webchart 2013-02-11_00:00:00 2013-02-12_00:00:00 ESA2000_LED_011e timerange TIMESTAMP day_kwh
    Retrieves charting data, which requires a given xaxis, yaxis, device, to and from
    Will ouput a JSON like this: [{'TIMESTAMP':'2013-02-11 00:10:10','VALUE':'0.22431388090756'},{'TIMESTAMP'.....}]
  
  
  • get logdb - webchart 2013-02-11_00:00:00 2013-02-12_00:00:00 ESA2000_LED_011e savechart TIMESTAMP day_kwh tageskwh
    Will save a chart in the database with the given name and the chart configuration parameters
  
  
  • get logdb - webchart "" "" "" deletechart "" "" 7
    Will delete a chart from the database with the given id

Attributes


• addStateEvent [0|1]
  
  
  As you probably know the event associated with the state Reading is special, as the "state: " string is stripped, i.e event is not "state: on" but just "on".
  Mostly it is desireable to get the complete event without "state: " stripped, so it is the default behavior of DbLog. That means you will get state-event complete as "state: xxx".
  In some circumstances, e.g. older or special modules, it is a good idea to set addStateEvent to "0". Try it if you have trouble with the default adjustment.
  


• asyncMode [0|1]
  
  
  This attribute sets the processing procedure according to which the DbLog device writes the data to the database.
  DbLog uses a sub-process to write the log data into the database and processes the data generally not blocking for FHEM.
  Thus, the writing process to the database is generally not blocking and FHEM is not affected in the case the database is not performing or is not available (maintenance, error condition).
  
  

  0 -	Synchronous log mode. The data to be logged is only briefly cached and immediately
  	written to the database. (default)
  	Advantages:
  	In principle, the data is immediately available in the database.
  	Very little to no data is lost when FHEM crashes.
  	Disadvantages:
  	An alternative storage in the file system (in case of database problems) is not supported.
  1 -	Asynchroner Log-Modus. The data to be logged is first cached in a memory cache and written to the database
  	depending on a time interval or fill level of the cache.
  	Advantages:
  	The data is cached and will not be lost if the database is unavailable or malfunctions.
  	The alternative storage of data in the file system is supported.
  	Disadvantages:
  	The data is available in the database with a time delay.
  	If FHEM crashes, all data cached in the memory will be lost.



• commitMode [basic_ta:on | basic_ta:off | ac:on_ta:on | ac:on_ta:off | ac:off_ta:on]
  
  
  Change the usage of database autocommit- and/or transaction- behavior.
  If transaction "off" is used, not saved datasets are not returned to cache in asynchronous mode.
  This attribute is an advanced feature and should only be used in a concrete situation or support case.
  
  
  • basic_ta:on - autocommit server basic setting / transaktion on (default)
  • basic_ta:off - autocommit server basic setting / transaktion off
  • ac:on_ta:on - autocommit on / transaktion on
  • ac:on_ta:off - autocommit on / transaktion off
  • ac:off_ta:on - autocommit off / transaktion on (autocommit "off" set transaktion "on" implicitly)


• cacheEvents [2|1|0]
  
  

  0 -	No events are generated for CacheUsage.
  1 -	Events are generated for the Reading CacheUsage when a new record is added to the cache.
  2 -	Events are generated for the Reading CacheUsage when the write cycle to the database starts in
  	asynchronous mode. CacheUsage contains the number of records in the cache at this time.

  (default: 0)
  


• cacheLimit <n>
  
  
  In asynchronous logging mode the content of cache will be written into the database and cleared if the number <n> datasets in cache has reached. Thereby the timer of asynchronous logging mode will be set new to the value of attribute "syncInterval". In case of error the next write attempt will be started at the earliest after syncInterval/2.
  (default: 500)


• cacheOverflowThreshold <n>
  
  
  In asynchronous log mode, sets the threshold of <n> records above which the cache contents are exported to a file instead of writing the data to the database.
  The executed function corresponds to the set command "exportCache purgecache" and uses its settings.
  
  This attribute can be used to prevent an overload of the server memory if the database is not available for a longer period of time (e.g. in case of error or maintenance). If the attribute value is less than or equal to the value of the cacheLimit attribute, the value of cacheLimit is used for cacheOverflowThreshold.
  In this case the cache will always be written to a file instead of to the database if the threshold value has been reached.
  With this setting, the data can be written to one or more files in order to import them into the database at a later time with the set command "importCachefile".


• colEvent <n>
  
  
  The field length of database field EVENT is adapted user-specifically. The attribute can be used to change the default value in the module if the field length in the database was changed manually. With colEvent=0 the database field EVENT is not filled.
  Note:
  With set attribute all field length limits are also valid for SQLite DB as shown in Internal COLUMNS!
  


• colReading <n>
  
  
  The field length of database field READING is adapted user-specifically. BThe attribute can be used to change the default value in the module if the field length in the database was changed manually. With colReading=0 the database field READING is not filled.
  Note:
  With set attribute all field length limits are also valid for SQLite DB as shown in Internal COLUMNS!
  


• colType <n>
  
  
  The field length for the database field TYPE is adapted user-specifically. The attribute can be used to change the default value in the module if the field length in the database was changed manually. With colType=0 the database field TYPE is not filled.
  Note:
  With set attribute all field length limits are also valid for SQLite DB as shown in Internal COLUMNS!
  


• colValue <n>
  
  
  The field length of database field VALUE is adapted user-specifically. The attribute can be used to change the default value in the module if the field length in the database was changed manually. With colValue=0 the database field VALUE is not filled.
  Note:
  With set attribute all field length limits are also valid for SQLite DB as shown in Internal COLUMNS!
  


• convertTimezone [UTC | none]
  
  
  UTC - the local timestamp of the event will be converted to UTC.
  (default: none)
  
  Note:
  The Perl modules 'DateTime' and 'DateTime::Format::Strptime' must be installed!


• DbLogType [Current|History|Current/History]
  
  
  This attribute determines which table or which tables in the database are wanted to use. If the attribute isn't set, the adjustment history will be used as default.
  The meaning of the adjustments in detail are:
  
  

  Current	Events are only logged into the current-table. The entries of current-table will evaluated with SVG-creation.
  History	Events are only logged into the history-table. No dropdown list with proposals will created with the SVG-creation.
  Current/History	Events will be logged both the current- and the history-table. The entries of current-table will evaluated with SVG-creation.
  SampleFill/History	Events are only logged into the history-table. The entries of current-table will evaluated with SVG-creation and can be filled up with a customizable extract of the history-table by using a DbRep-device command "set <DbRep-name> tableCurrentFillup" (advanced feature).

  
  
  Note:
  The current-table has to be used to get a Device:Reading-DropDown list when a SVG-Plot will be created.
  


• DbLogSelectionMode [Exclude|Include|Exclude/Include]
  
  
  This attribute, specific to DbLog devices, influences how the device-specific attributes DbLogExclude and DbLogInclude are evaluated. DbLogExclude and DbLogInclude are set in the source devices.
  If the DbLogSelectionMode attribute is not set, "Exclude" is the default.
  
  
  • Exclude: Readings are logged if they match the regex specified in the DEF. Excluded are the readings that match the regex in the DbLogExclude attribute.
    The DbLogInclude attribute is not considered in this case.
  
  
  • Include: Only readings are logged which are included via the regex in the attribute DbLogInclude are included.
    The DbLogExclude attribute is not considered in this case, nor is the regex in DEF.
  
  
  • Exclude/Include: Works basically like "Exclude", except that both the attribute DbLogExclude attribute and the DbLogInclude attribute are checked. Readings that were excluded by DbLogExclude, but are included by DbLogInclude are therefore still included in the logging.


• DbLogInclude Regex[:MinInterval][:force],[Regex[:MinInterval][:force]], ...
  
  
  The DbLogInclude attribute defines the readings to be stored in the database.
  The definition of the readings to be stored is done by a regular expression and all readings that match the regular expression are stored in the database.
  The optional <MinInterval> addition specifies that a value is saved when at least <MinInterval> seconds have passed since the last save.
  Regardless of the expiration of the interval, the reading is saved if the value of the reading has changed.
  With the optional modifier "force" the specified interval <MinInterval> can be forced to be kept even if the value of the reading has changed since the last storage.
  
  

          | Modifier |            within interval           | outside interval |
          |          | Value equal        | Value changed   |                  |
          |----------+--------------------+-----------------+------------------|
          | <none>   | ignore             | store           | store            |
          | force    | ignore             | ignore          | store            |
        

  
  Notes:
  The DbLogInclude attribute is propagated in all devices when DbLog is used.
  The DbLogSelectionMode attribute must be set accordingly to enable DbLogInclude.
  With the defaultMinInterval attribute a default for <MinInterval> can be specified.
  
  Example
  attr MyDevice1 DbLogInclude .*
attr MyDevice2 DbLogInclude state,(floorplantext|MyUserReading):300,battery:3600
attr MyDevice2 DbLogInclude state,(floorplantext|MyUserReading):300:force,battery:3600:force


• DbLogExclude Regex[:MinInterval][:force],[regex[:MinInterval][:force]] ...
  
  
  The DbLogExclude attribute defines the readings that should not be stored in the database.
  The definition of the readings to be excluded is done via a regular expression and all readings matching the regular expression are excluded from logging to the database.
  Readings that have not been excluded via the regex are logged in the database. The behavior of the storage is controlled with the following optional specifications.
  The optional <MinInterval> addition specifies that a value is saved when at least <MinInterval> seconds have passed since the last storage.
  Regardless of the expiration of the interval, the reading is saved if the value of the reading has changed.
  With the optional modifier "force" the specified interval <MinInterval> can be forced to be kept even if the value of the reading has changed since the last storage.
  
  

          | Modifier |            within interval           | outside interval |
          |          | Value equal        | Value changed   |                  |
          |----------+--------------------+-----------------+------------------|
          | <none>   | ignore             | store           | store            |
          | force    | ignore             | ignore          | store            |
        

  
  Notes:
  The DbLogExclude attribute is propagated in all devices when DbLog is used.
  The DbLogSelectionMode attribute can be set appropriately to disable DbLogExclude.
  With the defaultMinInterval attribute a default for <MinInterval> can be specified.
  
  Example
  attr MyDevice1 DbLogExclude .*
attr MyDevice2 DbLogExclude state,(floorplantext|MyUserReading):300,battery:3600
attr MyDevice2 DbLogExclude state,(floorplantext|MyUserReading):300:force,battery:3600:force


• DbLogValueFn {}
  
  
  If DbLog is used, the DbLogValueFn attribute is propagated in all devices. This attribute is set in the source devices and allows to change the values before logging or exclude the record from logging.
  
  The variables $TIMESTAMP, $READING, $VALUE (value of the reading) and $UNIT (unit of the reading value) can be accessed and modified before logging to the database.
  Read access is available to $DEVICE (the name of the source device), $EVENT, $LASTTIMESTAMP, and $LASTVALUE.
  
  The variables $LASTTIMESTAMP and $LASTVALUE contain time and value of the last logged record of $DEVICE / $READING.
  If $TIMESTAMP is to be changed, the form "yyyy-mm-dd hh:mm:ss" must be followed. Otherwise the changed $TIMESTAMP variable will not be applied. By setting the variable "$IGNORE=1" the record is excluded from logging.
  
  The device specific function in "DbLogValueFn" is applied to the record before the function in the "valueFn" attribute of the DbLog device.
  
  Example
  

  attr SMA_Energymeter DbLogValueFn
  {
    if ($READING eq "Bezug_WirkP_Kosten_Diff") {
      $UNIT="Diff-W";
    }
    if ($READING =~ /Einspeisung_Wirkleistung_Zaehler/ && $VALUE < 2) {
      $IGNORE=1;
    }
  }
  

• dbSchema <schema>
  
  
  This attribute is available for database types MySQL/MariaDB and PostgreSQL. The table names (current/history) are extended by its database schema. It is an advanced feature and normally not necessary to set.
  


• defaultMinInterval <devspec>::<MinInterval>[::force],[<devspec>::<MinInterval>[::force]] ...
  
  
  With this attribute a default minimum interval for devspec is defined. If a defaultMinInterval is set, the logentry is dropped if the defined interval is not reached and the value vs. lastvalue is equal.
  If the optional parameter "force" is set, the logentry is also dropped even though the value is not equal the last one and the defined interval is not reached.
  Potential set DbLogExclude / DbLogInclude specifications in source devices are having priority over defaultMinInterval and are not overwritten by this attribute.
  This attribute can be specified as multiline input.
  
  Examples
  attr dblog defaultMinInterval .*::120::force
  # Events of all devices are logged only in case of 120 seconds are elapsed to the last log entry (reading specific) independent of a possible value change.
  attr dblog defaultMinInterval (Weather|SMA)::300
  # Events of devices "Weather" and "SMA" are logged only in case of 300 seconds are elapsed to the last log entry (reading specific) and the value is equal to the last logged value.
  attr dblog defaultMinInterval TYPE=CUL_HM::600::force
  # Events of all devices of Type "CUL_HM" are logged only in case of 600 seconds are elapsed to the last log entry (reading specific) independent of a possible value change.


• excludeDevs <devspec1>[#Reading],<devspec2>[#Reading],<devspec...>
  
  
  The device/reading-combinations "devspec1#Reading", "devspec2#Reading" up to "devspec.." are globally excluded from logging into the database.
  The specification of a reading is optional.
  Thereby devices are explicit and consequently excluded from logging without consideration of another excludes or includes (e.g. in DEF). The devices to exclude can be specified as device-specification.
  
  Examples
  attr <device> excludeDevs global,Log.*,Cam.*,TYPE=DbLog
  # The devices global respectively devices starting with "Log" or "Cam" and devices with Type=DbLog are excluded from database logging.
  attr <device> excludeDevs .*#.*Wirkleistung.*
  # All device/reading-combinations which contain "Wirkleistung" in reading are excluded from logging.
  attr <device> excludeDevs SMA_Energymeter#Bezug_WirkP_Zaehler_Diff
  # The event containing device "SMA_Energymeter" and reading "Bezug_WirkP_Zaehler_Diff" are excluded from logging.
  


• expimpdir <directory>
  
  
  If the cache content will be exported by exportCache command, the file will be written into or read from that directory. The default directory is "(global->modpath)/log/". Make sure the specified directory is existing and writable.
  
  Example
  attr <device> expimpdir /opt/fhem/cache/
  


• exportCacheAppend [1|0]
  
  
  If set, the export of cache ("set <device> exportCache") appends the content to the newest available export file. If there is no exististing export file, it will be new created.
  If the attribute not set, every export process creates a new export file . (default)
  


• headerLinks [text|icon]
  
  
  The links offered in the header area of the device for executing various functions are displayed either as icons (default) or text. The text language is defined by the global attribute 'language'.


• insertMode [1|0]
  
  
  Toggles the insert mode of the database interface.
  
  

  0 -	The data is passed as an array to the database interface. (default)
  	It is in most cases the most performant way to insert a lot of data into the database at once.
  1 -	The records are passed sequentially to the database interface and inserted into the DB.



• noSupportPK [1|0]
  
  
  Deactivates the support of a set primary key by the module.
  


• plotInputFieldLength <Ganzzahl>
  
  
  Width of the Plot Editor input fields for Device:Reading and Function.
  If the drop-down list is used as input help for Device:Reading, the width of the field is set automatically.
  (default: 40)


• SQLiteCacheSize <number of memory pages used for caching>
  
  
  The default is about 4MB of RAM to use for caching (page_size=1024bytes, cache_size=4000).
  Embedded devices with scarce amount of RAM can go with 1000 pages or less. This will impact the overall performance of SQLite.
  (default: 4000)


• SQLiteJournalMode [WAL|off]
  
  
  Determines how SQLite databases are opened. Generally the Write-Ahead-Log (WAL) is the best choice for robustness and data integrity.
  Since WAL about doubles the spaces requirements on disk it might not be the best fit for embedded devices using a RAM backed disk. off will turn the journaling off. In case of corruption, the database probably won't be possible to repair and has to be recreated!
  (default: WAL)


• syncEvents [1|0]
  
  
  events of reading syncEvents will be created.
  


• showproctime [1|0]
  
  
  If set, the reading "sql_processing_time" shows the required processing time (in seconds) for the SQL execution of the executed function. This does not consider a single SQL statement, but the sum of all executed SQL commands within the respective function is considered.
  The reading "background_processing_time" shows the time used in the SubProcess.


• showNotifyTime [1|0]
  
  
  If set, the reading "notify_processing_time" shows the required processing time (in seconds) for the processing of the DbLog notify function.
  The attribute is suitable for performance analyses and also helps to determine the differences in the time required for event processing in synchronous or asynchronous mode.
  (default: 0)
  
  Hinweis:
  The reading "notify_processing_time" generates a lot of events and burdens the system. Therefore, when using the the event generation should be limited by setting the attribute "event-min-interval" to e.g. "notify_processing_time:30".


• syncInterval <n>
  
  
  If the asynchronous mode is set in the DbLog device (asyncMode=1), this attribute sets the interval (seconds) for writing data to the database.
  (default: 30)


• suppressAddLogV3 [1|0]
  
  
  If set, verbose 3 Logfileentries done by the addLog-function will be suppressed.
  


• suppressUndef
  
  
  Suppresses all undef values when returning data from the DB via get.


• timeout <n>
  
  
  Sets the timeout value for the operations in the SubProcess in seconds.
  If a started operation (logging, command) is not finished within the timeout value, the running subprocess is terminated and a new process is started.
  (default: 86400)


• traceFlag <ALL|SQL|CON|ENC|DBD|TXN>
  
  
  Trace flags are used to enable tracing of specific activities within the DBI and drivers. The attribute is only used for tracing of errors in case of support.
  
  

  ALL	turn on all DBI and driver flags
  SQL	trace SQL statements executed (Default)
  CON	trace connection process
  ENC	trace encoding (unicode translations etc)
  DBD	trace only DBD messages
  TXN	trace transactions

  
  


• traceLevel <0|1|2|3|4|5|6|7>
  
  
  Switch on the tracing function of the module.
  Caution ! The attribute is only used for tracing errors or in case of support. If switched on very much entries will be written into the FHEM Logfile !
  
  

  0	Trace disabled. (Default)
  1	Trace top-level DBI method calls returning with results or errors.
  2	As above, adding tracing of top-level method entry with parameters.
  3	As above, adding some high-level information from the driver and some internal information from the DBI.
  4	As above, adding more detailed information from the driver.
  5-7	As above but with more and more internal information.

  
  


• useCharfilter [0|1]
  
  
  If set, only ASCII characters from 32 to 126 are accepted in event. That are the characters " A-Za-z0-9!"#$%&'()*+,-.\/:;<=>?@[\\]^_`{|}~" .
  Mutated vowel and "€" are transcribed (e.g. ä to ae). (default: 0).
  


• valueFn {}
  
  
  This attribute is set in the DbLog device and allows to modify the values before logging or exclude the record from logging.
  
  It is possible to access the variables $TIMESTAMP, $DEVICE (source device), $DEVICETYPE, $EVENT, $READING, $VALUE (reading value) and $UNIT (unit of reading value) can be accessed and modified before logging to the database.
  Read only access exists to $LASTTIMESTAMP, $LASTVALUE and $NAME (Name of the DbLog Device).
  
  The variables $LASTTIMESTAMP and $LASTVALUE contain time and value of the last logged record of $DEVICE / $READING.
  If $TIMESTAMP is to be changed, the form "yyyy-mm-dd hh:mm:ss" must be followed. Otherwise the changed $TIMESTAMP variable will not be applied. By setting the variable "$IGNORE=1" the record is excluded from logging.
  
  Examples
  attr <device> valueFn {if ($DEVICE eq "living_Clima" && $VALUE eq "off" ){$VALUE=0;} elsif ($DEVICE eq "e-power"){$VALUE= sprintf "%.1f", $VALUE;}}
  # change value "off" to "0" of device "living_Clima" and rounds value of e-power to 1f
  
  attr <device> valueFn {if ($DEVICE eq "SMA_Energymeter" && $READING eq "state"){$IGNORE=1;}}
  # don't log the dataset of device "SMA_Energymeter" if the reading is "state"
  
  attr <device> valueFn {if ($DEVICE eq "Dum.Energy" && $READING eq "TotalConsumption"){$UNIT="W";}}
  # set the unit of device "Dum.Energy" to "W" if reading is "TotalConsumption"
  
  


• verbose4Devs <device1>,<device2>,<device..>
  
  
  If verbose level 4/5 is used, only output of devices set in this attribute will be reported in FHEM central logfile. If this attribute isn't set, output of all relevant devices will be reported if using verbose level 4/5. The given devices are evaluated as Regex.
  
  Example
  attr <device> verbose4Devs sys.*,.*5000.*,Cam.*,global
  # The devices starting with "sys", "Cam" respectively devices are containing "5000" in its name and the device "global" will be reported in FHEM central Logfile if verbose=4 is set.
  

DbRep

The purpose of this module is browsing and managing the content of DbLog-databases. The searchresults can be evaluated concerning to various aggregations and the appropriate Readings will be filled. The data selection will been done by declaration of device, reading and the time settings of selection-begin and selection-end.

Almost all database operations are implemented nonblocking. If there are exceptions it will be suggested to. Optional the execution time of SQL-statements in background can also be determined and provided as reading. (refer to attributes).
All existing readings will be deleted when a new operation starts. By attribute "readingPreventFromDel" a comma separated list of readings which are should prevent from deletion can be provided.

Currently the following functions are provided:


• Selection of all datasets within adjustable time limits.
• Exposure of datasets of a Device/Reading-combination within adjustable time limits.
• Selection of datasets by usage of dynamically calclated time limits at execution time.
• Highlighting doublets when select and display datasets (fetchrows)
• Calculation of quantity of datasets of a Device/Reading-combination within adjustable time limits and several aggregations.
• The calculation of summary-, difference-, maximum-, minimum- and averageValues of numeric readings within adjustable time limits and several aggregations.
• write back results of summary-, difference-, maximum-, minimum- and average calculation into the database
• The deletion of datasets. The containment of deletion can be done by Device and/or Reading as well as fix or dynamically calculated time limits at execution time.
• export of datasets to file (CSV-format).
• import of datasets from file (CSV-Format).
• rename of device/readings in datasets
• change of reading values in the database (changeValue)
• automatic rename of device names in datasets and other DbRep-definitions after FHEM "rename" command (see DbRep-Agent)
• Execution of arbitrary user specific SQL-commands (non-blocking)
• Execution of arbitrary user specific SQL-commands (blocking) for usage in user own code (sqlCmdBlocking)
• creation of backups of the database in running state non-blocking (MySQL, SQLite)
• transfer dumpfiles to a FTP server after backup incl. version control
• restore of SQLite- and MySQL-Dumps non-blocking
• optimize the connected database (optimizeTables, vacuum)
• report of existing database processes (MySQL)
• purge content of current-table
• fill up the current-table with a (tunable) extract of the history-table
• delete consecutive datasets with different timestamp but same values (clearing up consecutive doublets)
• Repair of a corrupted SQLite database ("database disk image is malformed")
• transmission of datasets from source database into another (Standby) database (syncStandby)
• reduce the amount of datasets in database (reduceLog)
• delete of duplicate records (delDoublets)
• drop and (re)create of indexes which are needed for DbLog and DbRep (index)

To activate the function Autorename the attribute "role" has to be assigned to a defined DbRep-device. The standard role after DbRep definition is "Client". Please read more in section DbRep-Agent about autorename function.

DbRep provides a UserExit function. With this interface the user can execute own program code dependent from free definable Reading/Value-combinations (Regex). The interface works without respectively independent from event generation. Further informations you can find as described at userExitFn attribute.

Once a DbRep-Device is defined, the Perl function DbReadingsVal provided as well as and the FHEM command dbReadingsVal. With this function you can, similar to the well known ReadingsVal, get a reading value from database.
The function is executed blocking with a standard timeout of 10 seconds to prevent a permanent blocking of FHEM. The timeout is adjustable with the attribute timeout.


The command syntax for the Perl function is:

DbReadingsVal("<name>","<device:reading>","<timestamp>","<default>")

Example:


  $ret = DbReadingsVal("Rep.LogDB1","MyWetter:temperature","2018-01-13_08:00:00","");
  attr <name> userReadings oldtemp {DbReadingsVal("Rep.LogDB1","MyWetter:temperature","2018-04-13_08:00:00","")}
  attr <name> userReadings todayPowerIn
    {
       my ($sec,$min,$hour,$mday,$month,$year,$wday,$yday,$isdst) = localtime(gettimeofday());
       $month++;
       $year+=1900;
       my $today = sprintf('%04d-%02d-%02d', $year,$month,$mday);
       DbReadingsVal("Rep.LogDB1","SMA_Energymeter:Bezug_Wirkleistung_Zaehler",$today."_00:00:00",0)
    }
  

The command syntax for the FHEM command is:

dbReadingsVal <name> <device:reading> <timestamp> <default>

Example:
dbReadingsVal Rep.LogDB1 MyWetter:temperature 2018-01-13_08:00:00 0



<name>	: name of the DbRep-Device to request
<device:reading>	: device:reading whose value is to deliver
<timestamp>	: timestamp of reading whose value is to deliver (*) in format "YYYY-MM-DD_hh:mm:ss"
<default>	: default value if no reading value can be retrieved


(*) If no value can be retrieved at the <timestamp> exactly requested, the chronological most convenient reading value is delivered back.

FHEM-Forum:
Modul 93_DbRep - Reporting and Management of database content (DbLog).

Preparations

The module requires the usage of a DbLog instance and the credentials of the database definition will be used.
Only the content of table "history" will be included if isn't other is explained.

Overview which other Perl-modules DbRep is using:

Net::FTP (only if FTP-Transfer after database dump is used)
Net::FTPSSL (only if FTP-Transfer with encoding after database dump is used)
POSIX
Time::HiRes
Time::Local
Scalar::Util
DBI
Color (FHEM-module)
IO::Compress::Gzip
IO::Uncompress::Gunzip
Blocking (FHEM-module)

Definition

define <name> DbRep <name of DbLog-instance>

(<name of DbLog-instance> - name of the database instance which is wanted to analyze needs to be inserted)

Due to a good operation performance, the database should contain the index "Report_Idx". Please create it after the DbRep device definition by the following set command if it isn't already existing on the database:


set <name> index recreate_Report_Idx

Set

Currently following set-commands are included. They are used to trigger the evaluations and define the evaluation option option itself. The criteria of searching database content and determine aggregation is carried out by setting several attributes.

Note:
If you are in detail view it could be necessary to refresh the browser to see the result of operation as soon in DeviceOverview section "state = done" will be shown.


• adminCredentials <User> <Passwort>
  
  Save a user / password for the privileged respectively administrative database access. The user is required for database operations which has to be executed by a privileged user. Please see also attribute useAdminCredentials.


• averageValue [display | writeToDB | writeToDBSingle | writeToDBSingleStart | writeToDBInTime]
  
  Calculates an average value of the database field "VALUE" in the time limits of the possible time.*-attributes.
  
  The reading to be evaluated must be specified in the attribute reading must be specified. With the attribute averageCalcForm the calculation variant is used for Averaging defined.
  
  If none or the option display is specified, the results are only displayed. With the options writeToDB, writeToDBSingle, writeToDBSingleStart or writeToDBInTime the calculation results are written with a new reading name into the database.
  
  

  writeToDB	: writes one value each with the time stamps XX:XX:01 and XX:XX:59 within the respective evaluation period
  writeToDBSingle	: writes only one value with the time stamp XX:XX:59 at the end of an evaluation period
  writeToDBSingleStart	: writes only one value with the time stamp XX:XX:01 at the begin of an evaluation period
  writeToDBInTime	: writes a value at the beginning and end of the time limits of an evaluation period

  
  The new reading name is formed from a prefix and the original reading name, where the original reading name can be replaced by the attribute "readingNameMap". The prefix consists of the educational function and the aggregation.
  The timestamp of the new readings in the database is determined by the set aggregation period if no clear time of the result can be determined. The field "EVENT" is filled with "calculated".
  
  
  Example of building a new reading name from the original reading "totalpac":
  avgam_day_totalpac
  # <creation function>_<aggregation>_<original reading>
  
  
  Summarized the relevant attributes to control this function are:
  
  

  averageCalcForm	: choose the calculation variant for average determination
  device	: include or exclude <device> from selection
  executeBeforeProc	: execution of FHEM command (or Perl-routine) before operation
  executeAfterProc	: execution of FHEM command (or Perl-routine) after operation
  reading	: include or exclude <reading> from selection
  time.*	: a number of attributes to limit selection by time
  valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.

  
  
  
• cancelDump
  
  Stops a running database dump.


• changeValue old="<old String>" new="<new String>"
  
  Changes the stored value of a reading.
  If the selection is limited to certain device/reading combinations by the attributes device or reading, they are taken into account in the same way as set time limits (time.* attributes).
  If these constraints are missing, the entire database is searched and the specified value is is changed.
  
  The "string" can be:
  

  <old String> :	a simple string with/without spaces, e.g. "OL 12"
  	a string with use of SQL wildcard, e.g. "%OL%"
  <new String> :	a simple string with/without spaces, e.g. "12 kWh"
  	Perl code enclosed in {"..."} including quotes, e.g. {"($VALUE,$UNIT) = split(" ",$VALUE)"}
  	The variables $VALUE and $UNIT are passed to the Perl expression. They can be changed
  	within the Perl code. The returned value of $VALUE and $UNIT is stored
  	in the VALUE or UNIT field of the record.

  
  Examples:
  set <name> changeValue old="OL" new="12 OL"
  # the old field value "OL" is changed to "12 OL".
  
  set <name> changeValue old="%OL%" new="12 OL"
  # contains the field VALUE the substring "OL", it is changed to "12 OL".
  
  set <name> changeValue old="12 kWh" new={"($VALUE,$UNIT) = split(" ",$VALUE)"}
  # the old field value "12 kWh" is splitted to VALUE=12 and UNIT=kWh and saved into the database fields
  
  set <name> changeValue old="24%" new={"$VALUE = (split(" ",$VALUE))[0]"}
  # if the old field value begins with "24", it is splitted and VALUE=24 is saved (e.g. "24 kWh")
  
  Summarized the relevant attributes to control function changeValue are:
  
  

  device	: include or exclude <device> from selection
  reading	: include or exclude <reading> from selection
  time.*	: a number of attributes to limit selection by time
  executeBeforeProc	: execute a FHEM command (or Perl-routine) before start of changeValue
  executeAfterProc	: execute a FHEM command (or Perl-routine) after changeValue is finished
  valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.

  
  
  
• countEntries [history|current]
  
  Provides the number of table entries (default: history) between time period set by time.* -attributes if set. If time.* attributes not set, all entries of the table will be count. The device and reading can be used to limit the evaluation.
  By default the summary of all counted datasets, labeled by "ALLREADINGS", will be created. If the attribute countEntriesDetail is set, the number of every reading is reported additionally.
  
  The relevant attributes for this function are:
  
  

  aggregation	: aggregatiion/grouping of time intervals
  countEntriesDetail	: detailed report the count of datasets (per reading)
  device	: include or exclude <device> from selection
  reading	: include or exclude <reading> from selection
  executeBeforeProc	: execution of FHEM command (or Perl-routine) before operation
  executeAfterProc	: execution of FHEM command (or Perl-routine) after operation
  time.*	: a number of attributes to limit selection by time
  valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.




• delDoublets [adviceDelete | delete] - show respectively delete duplicate/multiple datasets. Therefore the fields TIMESTAMP, DEVICE, READING and VALUE of records are compared.
  The attributes to define the scope of aggregation, time period, device and reading are considered. If attribute aggregation is not set or set to "no", it will change to the default aggregation period "day".
  
  

  adviceDelete	: simulates the datasets to delete in database (nothing will be deleted !)
  delete	: deletes the doublets

  
  The amount of datasets to show by commands "delDoublets adviceDelete" is initially limited and can be adjusted by limit attribute. The adjustment of "limit" has no impact to the "delDoublets delete" function, but affects ONLY the display of the data.
  Before and after this "delDoublets" it is possible to execute a FHEM command or Perl script (please see attributes executeBeforeProc, executeAfterProc).
  
  
  Example:
  
  Output of records to delete included their amount by "delDoublets adviceDelete":
  
  2018-11-07_14-11-38__Dum.Energy__T 260.9_|_2
  2018-11-07_14-12-37__Dum.Energy__T 260.9_|_2
  2018-11-07_14-15-38__Dum.Energy__T 264.0_|_2
  2018-11-07_14-16-37__Dum.Energy__T 264.0_|_2
  
  In the created readings after "_|_" the amount of the appropriate records to delete is shown. The records are deleted by command "delDoublets delete".
  
  Zusammengefasst sind die zur Steuerung dieser Funktion relevanten Attribute:
  
  

  aggregation	: choose the aggregation period
  limit	: limits ONLY the count of datasets to display
  device	: include or exclude <device> from selection
  reading	: include or exclude <reading> from selection
  executeBeforeProc	: execute a FHEM command (or Perl-routine) before start of the function
  executeAfterProc	: execute a FHEM command (or Perl-routine) after the function is finished
  time.*	: a number of attributes to limit selection by time
  valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.

  
  
  
• delEntries [<no>[:<nn>]]
  
  Deletes all database entries or only the database entries specified by attributes device and/or reading.
  
  The time limits are considered according to the available time.*-attributes:
  
  
  "timestamp_begin" is set -> deletes db entries from this timestamp until current date/time
  "timestamp_end" is set -> deletes db entries until this timestamp
  both Timestamps are set -> deletes db entries between these timestamps
  "timeOlderThan" is set -> delete entries older than current time minus "timeOlderThan"
  "timeDiffToNow" is set -> delete db entries from current time minus "timeDiffToNow" until now
  
  
  Time limits (days) can be specified as an option. In this case, any time.*-attributes set are overmodulated. Records older than <no> days and (optionally) newer than <nn> days are considered.
  
  The relevant attributes to control function changeValue delEntries are:
  
  

  device	: include or exclude <device> from selection
  reading	: include or exclude <reading> from selection
  time.*	: a number of attributes to limit selection by time
  executeBeforeProc	: execute a FHEM command (or Perl-routine) before start of delEntries
  executeAfterProc	: execute a FHEM command (or Perl-routine) after delEntries is finished

  
  
  


• delSeqDoublets [adviceRemain | adviceDelete | delete] - show respectively delete identical sequentially datasets. Therefore Device,Reading and Value of the sequentially datasets are compared. Not deleted are the first und the last dataset of a aggregation period (e.g. hour,day,week and so on) as well as the datasets before or after a value change (database field VALUE).
  The attributes to define the scope of aggregation, time period, device and reading are considered. If attribute aggregation is not set or set to "no", it will change to the default aggregation period "day". For datasets containing numerical values it is possible to determine a variance with attribute seqDoubletsVariance. Up to this value consecutive numerical datasets are handled as identical and should be deleted.
  
  

  adviceRemain	: simulates the remaining datasets in database after delete-operation (nothing will be deleted !)
  adviceDelete	: simulates the datasets to delete in database (nothing will be deleted !)
  delete	: deletes the consecutive doublets (see example)

  
  The amount of datasets to show by commands "delSeqDoublets adviceDelete", "delSeqDoublets adviceRemain" is initially limited (default: 1000) and can be adjusted by attribute limit. The adjustment of "limit" has no impact to the "delSeqDoublets delete" function, but affects ONLY the display of the data.
  Before and after this "delSeqDoublets" it is possible to execute a FHEM command or Perl-script (please see executeBeforeProc and executeAfterProc).
  
  
  Example - the remaining datasets after executing delete-option are are marked as bold:
  
  
  2017-11-25_00-00-05__eg.az.fridge_Pwr__power 0
  2017-11-25_00-02-26__eg.az.fridge_Pwr__power 0
  2017-11-25_00-04-33__eg.az.fridge_Pwr__power 0
  2017-11-25_01-06-10__eg.az.fridge_Pwr__power 0
  2017-11-25_01-08-21__eg.az.fridge_Pwr__power 0
  2017-11-25_01-08-59__eg.az.fridge_Pwr__power 60.32
  2017-11-25_01-11-21__eg.az.fridge_Pwr__power 56.26
  2017-11-25_01-27-54__eg.az.fridge_Pwr__power 6.19
  2017-11-25_01-28-51__eg.az.fridge_Pwr__power 0
  2017-11-25_01-31-00__eg.az.fridge_Pwr__power 0
  2017-11-25_01-33-59__eg.az.fridge_Pwr__power 0
  2017-11-25_02-39-29__eg.az.fridge_Pwr__power 0
  2017-11-25_02-41-18__eg.az.fridge_Pwr__power 105.28
  2017-11-25_02-41-26__eg.az.fridge_Pwr__power 61.52
  2017-11-25_03-00-06__eg.az.fridge_Pwr__power 47.46
  2017-11-25_03-00-33__eg.az.fridge_Pwr__power 0
  2017-11-25_03-02-07__eg.az.fridge_Pwr__power 0
  2017-11-25_23-37-42__eg.az.fridge_Pwr__power 0
  2017-11-25_23-40-10__eg.az.fridge_Pwr__power 0
  2017-11-25_23-42-24__eg.az.fridge_Pwr__power 1
  2017-11-25_23-42-24__eg.az.fridge_Pwr__power 1
  2017-11-25_23-45-27__eg.az.fridge_Pwr__power 1
  2017-11-25_23-47-07__eg.az.fridge_Pwr__power 0
  2017-11-25_23-55-27__eg.az.fridge_Pwr__power 0
  2017-11-25_23-48-15__eg.az.fridge_Pwr__power 0
  2017-11-25_23-50-21__eg.az.fridge_Pwr__power 59.1
  2017-11-25_23-55-14__eg.az.fridge_Pwr__power 52.31
  2017-11-25_23-58-09__eg.az.fridge_Pwr__power 51.73
  
  
  Summarized the relevant attributes to control this function are:
  
  

  aggregation	: choose the aggregation period
  limit	: limits ONLY the count of datasets to display
  device	: include or exclude <device> from selection
  reading	: include or exclude <reading> from selection
  executeBeforeProc	: execute a FHEM command (or Perl-routine) before start of the function
  executeAfterProc	: execute a FHEM command (or Perl-routine) after the function is finished
  seqDoubletsVariance	: Up to this value consecutive numerical datasets are handled as identical and should be deleted
  time.*	: a number of attributes to limit selection by time
  valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.




• deviceRename <old_name>,<new_name>
  
  Renames the device name of a device inside the connected database (Internal DATABASE). The devicename will allways be changed in the entire database. Possibly set time limits or restrictions by device and/or reading will not be considered.
  
  
  Example:
  set <name> deviceRename ST_5000,ST5100
  # The amount of renamed device names (datasets) will be displayed in reading "device_renamed".
  # If the device name to be renamed was not found in the database, a WARNUNG will appear in reading "device_not_renamed".
  # Appropriate entries will be written to Logfile if verbose >= 3 is set.
  
  
  Note:
  Even though the function itself is designed non-blocking, make sure the assigned DbLog-device is operating in asynchronous mode to avoid FHEMWEB from blocking.
  
  The relevant attributes to control this function are:
  
  

  executeBeforeProc	: execution of FHEM command (or Perl-routine) before operation
  executeAfterProc	: execution of FHEM command (or Perl-routine) after operation

  
  
  
• diffValue [display | writeToDB] - calculates the difference of database column "VALUE" in the given time period. (see also the several time*-attributes).
  The reading to evaluate must be defined in attribute reading.
  This function is mostly reasonable if values are increasing permanently and don't write value differences into the database. The difference will always be generated between all consecutive datasets (VALUE-Field) and add them together, in doing add carry value of the previous aggregation period to the next aggregation period in case the previous period contains a value.
  A possible counter overrun (restart with value "0") will be considered (compare attribute diffAccept).
  
  If only one dataset will be found within the evalution period, the difference can be calculated only in combination with the balanced difference of the previous aggregation period. In this case a logical inaccuracy according the assignment of the difference to the particular aggregation period can be possible. Hence in warning in "state" will be placed and the reading "less_data_in_period" with a list of periods with only one dataset found in it will be created.
  
  
  Note:
  Within the evaluation respectively aggregation period (day, week, month, etc.) you should make available at least one dataset at the beginning and one dataset at the end of each aggregation period to take the difference calculation as much as possible.
  
  
  Is no or the option "display" specified, the results are only displayed. Using option "writeToDB" the calculation results are stored in the database with a new reading name.
  The new readingname is built of a prefix and the original reading name, in which the original reading name can be partly replaced by the value of attribute readingNameMap. The prefix is made up of the creation function and the aggregation.
  The timestamp of the new stored readings is deviated from aggregation period, unless no unique point of time of the result can be determined. The field "EVENT" will be filled with "calculated".
  
  
  Example of building a new reading name from the original reading "totalpac":
  diff_day_totalpac
  # <creation function>_<aggregation>_<original reading>
  
  
  Summarized the relevant attributes to control this function are:
  
  

  aggregation	: choose the aggregation period
  diffAccept	: the accepted maximum difference between sequential records
  device	: include or exclude <device> from selection
  executeBeforeProc	: execution of FHEM command (or Perl-routine) before operation
  executeAfterProc	: execution of FHEM command (or Perl-routine) after operation
  reading	: include or exclude <reading> from selection
  readingNameMap	: rename the resulted reading name
  time.*	: a number of attributes to limit selection by time
  valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.

  
  
  


• dumpMySQL [clientSide | serverSide]
  
  Creates a dump of the connected MySQL database.
  Depending from selected option the dump will be created on Client- or on Server-Side.
  The variants differs each other concerning the executing system, the creating location, the usage of attributes, the function result and the needed hardware ressources.
  The option "clientSide" e.g. needs more powerful FHEM-Server hardware, but saves all available tables inclusive possibly created views.
  With attribute "dumpCompress" a compression of dump file after creation can be switched on.
  
  
  Option clientSide
  The dump will be created by client (FHEM-Server) and will be saved in FHEM log-directory ((typical /opt/fhem/log/)) by default. The target directory can be set by attribute dumpDirLocal and has to be writable by the FHEM process.
  Before executing the dump a table optimization can be processed optionally (see attribute "optimizeTablesBeforeDump") as well as a FHEM-command (attribute "executeBeforeProc"). After the dump a FHEM-command can be executed as well (see attribute "executeAfterProc").
  
  Note:
  To avoid FHEM from blocking, you have to operate DbLog in asynchronous mode if the table optimization want to be used !
  
  By the attributes dumpMemlimit and dumpSpeed the run-time behavior of the function can be controlled to optimize the performance and demand of ressources.
  
  The attributes relevant for function "dumpMySQL clientSide" are:
  
  

  dumpComment	: User comment in head of dump file
  dumpCompress	: compress of dump files after creation
  dumpDirLocal	: the local destination directory for dump file creation
  dumpMemlimit	: limits memory usage
  dumpSpeed	: limits CPU utilization
  dumpFilesKeep	: number of dump files to keep
  executeBeforeProc	: execution of FHEM command (or Perl-routine) before dump
  executeAfterProc	: execution of FHEM command (or Perl-routine) after dump
  optimizeTablesBeforeDump	: table optimization before dump

  
  After a successfull finished dump the old dumpfiles are deleted and only the number of files defined by attribute "dumpFilesKeep" (default: 3) remain in the target directory "dumpDirLocal". If "dumpFilesKeep = 0" is set, all dumpfiles (also the current created file), are deleted. This setting can be helpful, if FTP transmission is used and the created dumps are only keep remain in the FTP destination directory.
  
  The naming convention of dump files is: <dbname>_<date>_<time>.sql[.gzip]
  
  To rebuild the database from a dump file the command:
  
  
  set <name> restoreMySQL <filename>
  
  
  can be used.
  
  The created dumpfile (uncompressed) can imported on the MySQL-Server by:
  
  
  mysql -u <user> -p <dbname> < <filename>.sql
  
  
  as well to restore the database from dump file.
  
  
  Option serverSide
  The dump will be created on the MySQL-Server and will be saved in its Home-directory by default.
  The whole history-table (not the current-table) will be exported CSV-formatted without any restrictions.
  Before executing the dump a table optimization can be processed optionally (see attribute "optimizeTablesBeforeDump") as well as a FHEM-command (attribute "executeBeforeProc").
  
  Note:
  To avoid FHEM from blocking, you have to operate DbLog in asynchronous mode if the table optimization is used !
  
  After the dump a FHEM-command can be executed as well (see attribute "executeAfterProc").
  
  The attributes relevant for function "dumpMySQL serverSide" are:
  
  

  dumpDirRemote	: destination directory of dump file on remote server
  dumpCompress	: compress of dump files after creation
  dumpDirLocal	: the local mounted directory dumpDirRemote
  dumpFilesKeep	: number of dump files to keep
  executeBeforeProc	: execution of FHEM command (or Perl-routine) before dump
  executeAfterProc	: execution of FHEM command (or Perl-routine) after dump
  optimizeTablesBeforeDump	: table optimization before dump

  
  The target directory can be set by dumpDirRemote attribute. It must be located on the MySQL-Host and has to be writable by the MySQL-server process.
  The used database user must have the FILE privilege (see Wiki).
  
  Note:
  If the internal version management of DbRep should be used and the size of the created dumpfile be reported, you have to mount the remote MySQL-Server directory "dumpDirRemote" on the client and publish it to the DbRep-device by fill out the dumpDirLocal attribute.
  Same is necessary if ftp transfer after dump is to be used (attribute "ftpUse" respectively "ftpUseSSL").
  
  
  Example:
  attr <name> dumpDirRemote /volume1/ApplicationBackup/dumps_FHEM/
  attr <name> dumpDirLocal /sds1/backup/dumps_FHEM/
  attr <name> dumpFilesKeep 2
  
  # The dump will be created remote on the MySQL-Server in directory '/volume1/ApplicationBackup/dumps_FHEM/'.
  # The internal version management searches in local mounted directory '/sds1/backup/dumps_FHEM/' for present dumpfiles and deletes these files except the last two versions.
  
  
  If the internal version management is used, after a successfull finished dump old dumpfiles will be deleted and only the number of attribute "dumpFilesKeep" (default: 3) would remain in target directory "dumpDirLocal" (the mounted "dumpDirRemote"). In that case FHEM needs write permissions to the directory "dumpDirLocal".
  
  The naming convention of dump files is: <dbname>_<date>_<time>.csv[.gzip]
  
  You can start a restore of table history from serverSide-Backup by command:
  
  
  set <name> <restoreMySQL> <filename>.csv[.gzip]
  
  
  
  
  FTP-Transfer after Dump
  If those possibility is be used, the attribute ftpUse or ftpUseSSL has to be set. The latter if encoding for FTP is to be used. The module also carries the version control of dump files in FTP-destination by attribute "ftpDumpFilesKeep".
  Further attributes are:
  
  

  ftpUse	: FTP Transfer after dump will be switched on (without SSL encoding)
  ftpUser	: User for FTP-server login, default: anonymous
  ftpUseSSL	: FTP Transfer with SSL encoding after dump
  ftpDebug	: debugging of FTP communication for diagnostics
  ftpDir	: directory on FTP-server in which the file will be send into (default: "/")
  ftpDumpFilesKeep	: leave the number of dump files in FTP-destination <ftpDir> (default: 3)
  ftpPassive	: set if passive FTP is to be used
  ftpPort	: FTP-Port, default: 21
  ftpPwd	: password of FTP-User, not set by default
  ftpServer	: name or IP-address of FTP-server. absolutely essential !
  ftpTimeout	: timeout of FTP-connection in seconds (default: 30).

  
  
  


• dumpSQLite - creates a dump of the connected SQLite database.
  This function uses the SQLite Online Backup API and allow to create a consistent backup of the database during the normal operation. The dump will be saved in FHEM log-directory by default. The target directory can be defined by the dumpDirLocal attribute and has to be writable by the FHEM process.
  Before executing the dump a table optimization can be processed optionally (see attribute "optimizeTablesBeforeDump").
  
  Note:
  To avoid FHEM from blocking, you have to operate DbLog in asynchronous mode if the table optimization want to be used !
  
  Before and after the dump a FHEM-command can be executed (see attribute "executeBeforeProc", "executeAfterProc").
  
  The attributes relevant for function "dumpMySQL serverSide" are:
  
  

  dumpCompress	: compress of dump files after creation
  dumpDirLocal	: Target directory of the dumpfiles
  dumpFilesKeep	: number of dump files to keep
  executeBeforeProc	: execution of FHEM command (or Perl-routine) before dump
  executeAfterProc	: execution of FHEM command (or Perl-routine) after dump
  optimizeTablesBeforeDump	: table optimization before dump

  
  After a successfull finished dump the old dumpfiles are deleted and only the number of attribute "dumpFilesKeep" (default: 3) remain in the target directory "dumpDirLocal". If "dumpFilesKeep = 0" is set, all dumpfiles (also the current created file), are deleted. This setting can be helpful, if FTP transmission is used and the created dumps are only keep remain in the FTP destination directory.
  
  The naming convention of dump files is: <dbname>_<date>_<time>.sqlitebkp[.gzip]
  
  The database can be restored by command "set <name> restoreSQLite <filename>"
  The created dump file can be transfered to a FTP-server. Please see explanations about FTP- transfer in topic "dumpMySQL".
  
  


• eraseReadings
  
  Deletes all created readings in the device, except reading "state" and readings, which are contained in exception list defined by attribute readingPreventFromDel.


• exportToFile [</path/file>] [MAXLINES=<lines>] - exports DB-entries to a file in CSV-format of time period specified by time attributes.
  
  The filename can be defined by the expimpfile attribute.
  Optionally a file can be specified as a command option (/path/file) and overloads a possibly defined attribute "expimpfile". The maximum number of datasets which are exported into one file can be specified with the optional parameter "MAXLINES". In this case several files with extensions "_part1", "_part2", "_part3" and so on are created (pls. remember it when you import the files !).
  Limitation of selections can be done by attributes device and/or reading. The filename may contain wildcards as described in attribute section of "expimpfile".
  By setting attribute "aggregation" the export of datasets will be splitted into time slices corresponding to the specified aggregation. If, for example, "aggregation = month" is set, the data are selected in monthly packets and written into the exportfile. Thereby the usage of main memory is optimized if very large amount of data is exported and avoid the "died prematurely" error.
  
  The attributes relevant for this function are:
  
  

  aggregation	: determination of selection time slices
  device	: include or exclude <device> from selection
  reading	: include or exclude <reading> from selection
  time.*	: a number of attributes to limit selection by time
  executeBeforeProc	: execution of FHEM command (or Perl-routine) before export
  executeAfterProc	: execution of FHEM command (or Perl-routine) after export
  expimpfile	: the name of exportfile
  time.*	: a number of attributes to limit selection by time
  valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.



• fetchrows [history|current] - provides all table entries (default: history) of time period set by time.*-attributes respectively selection conditions by attributes "device" and "reading". An aggregation set will not be considered.
  The direction of data selection can be determined by the fetchRoute attribute.
  
  Every reading of result is composed of the dataset timestring , an index, the device name and the reading name. The function has the capability to reconize multiple occuring datasets (doublets). Such doublets are marked by an index > 1. Optional a Unique-Index is appended if datasets with identical timestamp, device and reading but different value are existing.
  Doublets can be highlighted in terms of color by setting attribut e"fetchMarkDuplicates".
  
  Note:
  Highlighted readings are not displayed again after restart or rereadcfg because of they are not saved in statefile.
  
  This attribute is preallocated with some colors, but can be changed by colorpicker-widget:
  
  
  attr <DbRep-Device> widgetOverride fetchMarkDuplicates:colorpicker
  
  The readings of result are composed like the following sceme:
  
  
  Example:
  2017-10-22_03-04-43__1__SMA_Energymeter__Bezug_WirkP_Kosten_Diff__[1]
  # <date>_<time>__<index>__<device>__<reading>__[Unique-Index]
  
  For a better overview the relevant attributes are listed here in a table:
  
  

  device	: include or exclude <device> from selection
  fetchRoute	: direction of selection read in database
  fetchMarkDuplicates	: Highlighting of found doublets
  fetchValueFn	: the displayed value of the VALUE database field can be changed by a function before the reading is created
  limit	: limits the number of datasets to select and display
  reading	: include or exclude <reading> from selection
  executeBeforeProc	: execution of FHEM command (or Perl-routine) before operation
  executeAfterProc	: execution of FHEM command (or Perl-routine) after operation
  time.*	: A number of attributes to limit selection by time
  valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.

  
  
  Note:
  Although the module is designed non-blocking, a huge number of selection result (huge number of rows) can overwhelm the browser session respectively FHEMWEB. Due to the sample space can be limited by limit attribute. Of course ths attribute can be increased if your system capabilities allow a higher workload.
  
  


• index <Option> - Reports the existing indexes in the database or creates the index which is needed. If the index is already created, it will be renewed (dropped and new created)
  
  The possible options are:
  
  

  list_all	: reports the existing indexes
  recreate_Search_Idx	: create or renew (if existing) the index Search_Idx in table history (index for DbLog)
  drop_Search_Idx	: delete the index Search_Idx in table history
  recreate_Report_Idx	: create or renew (if existing) the index Report_Idx in table history (index for DbRep)
  drop_Report_Idx	: delete the index Report_Idx in table history

  
  For a better overview the relevant attributes for this operation are listed here:
  
  

  useAdminCredentials

  : use privileged user for the operation

  
  
  Note:
  The MySQL database user used requires the ALTER, CREATE and INDEX privilege.
  These rights can be set with:
  
  
  set <Name> sqlCmd GRANT INDEX, ALTER, CREATE ON `<db>`.* TO '<user>'@'%';
  
  The useAdminCredentials attribute must usually be set to be able to change the rights of the used user.


• insert <Date>,<Time>,<Value>,[<Unit>],[<Device>],[<Reading>] - Manual insertion of a data record into the table "history". Input values for date, time and value are obligatory. The values for the DB fields TYPE and EVENT are filled with "manual".
  If Device, Reading are not set, these values are taken from the corresponding attributes device, reading.
  
  Note:
  Unused fields within the insert command must be enclosed within the string in "," within the string.
  
  
  Examples:
  set <name> insert 2016-08-01,23:00:09,12.03,kW
  set <name> insert 2021-02-02,10:50:00,value with space
  set <name> insert 2022-05-16,10:55:00,1800,,SMA_Wechselrichter,etotal
  set <name> insert 2022-05-16,10:55:00,1800,,,etotal
  
  
  The relevant attributes to control this function are:
  
  

  executeBeforeProc	: execution of FHEM command (or Perl-routine) before operation
  executeAfterProc	: execution of FHEM command (or Perl-routine) after operation

  
  
  
• importFromFile [<file>] - imports data in CSV format from file into database.
  The filename can be defined by attribute expimpfile.
  Optionally a file can be specified as a command option (/path/file) and overloads a possibly defined attribute "expimpfile". The filename may contain wildcards as described in attribute section of "expimpfile".
  
  
  dataset format:
  "TIMESTAMP","DEVICE","TYPE","EVENT","READING","VALUE","UNIT"
  
  # The fields "TIMESTAMP","DEVICE","TYPE","EVENT","READING" and "VALUE" have to be set. The field "UNIT" is optional. The file content will be imported transactional. That means all of the content will be imported or, in case of error, nothing of it. If an extensive file will be used, DON'T set verbose = 5 because of a lot of datas would be written to the logfile in this case. It could lead to blocking or overload FHEM !
  
  Example for a source dataset:
  "2016-09-25 08:53:56","STP_5000","SMAUTILS","etotal: 11859.573","etotal","11859.573",""
  
  The attributes relevant for this function are:
  
  

  executeBeforeProc	: execution of FHEM command (or Perl-routine) before import
  executeAfterProc	: execution of FHEM command (or Perl-routine) after import
  expimpfile	: the name of exportfile

  
  
  
  
• maxValue [display | writeToDB | deleteOther]
  br> Calculates the maximum value of database column "VALUE" between period given by attributes timestamp_begin, "timestamp_end" / "timeDiffToNow / timeOlderThan" and so on. The reading to evaluate must be defined using attribute reading. The evaluation contains the timestamp of the last appearing of the identified maximum value within the given period.
  
  If no option or the option display is specified, the results are only displayed. Using option writeToDB the calculated results are stored in the database with a new reading name.
  The new readingname is built of a prefix and the original reading name, in which the original reading name can be replaced by the value of attribute readingNameMap. The prefix is made up of the creation function and the aggregation.
  The timestamp of the new stored readings is deviated from aggregation period, unless no unique point of time of the result can be determined. The field "EVENT" will be filled with "calculated".
  
  With option deleteOther all datasets except the dataset with the maximum value are deleted.
  
  
  Example of building a new reading name from the original reading "totalpac":
  max_day_totalpac
  # <creation function>_<aggregation>_<original reading>
  
  
  Summarized the relevant attributes to control this function are:
  
  aggregation, device, reading, readingNameMap, executeBeforeProc, executeAfterProc, valueFilter, userExitFn, time.*-attributes
  
  


• migrateCollation <Collation>
  
  Migrates the used character set/collation of the database and the tables current and history to the specified format.
  
  Relevant attributes are:
  
  executeBeforeProc, executeAfterProc, useAdminCredentials, userExitFn
  
  


• minValue [display | writeToDB | deleteOther]
  
  Calculates the minimum value of database column "VALUE" between period given by attributes timestamp_begin, "timestamp_end" / "timeDiffToNow / timeOlderThan" and so on. The reading to evaluate must be defined using attribute reading. The evaluation contains the timestamp of the first appearing of the identified minimum value within the given period.
  
  If no option or the option display is specified, the results are only displayed. Using option writeToDB the calculated results are stored in the database with a new reading name.
  The new readingname is built of a prefix and the original reading name, in which the original reading name can be replaced by the value of attribute readingNameMap. The prefix is made up of the creation function and the aggregation.
  The timestamp of the new stored readings is deviated from aggregation period, unless no unique point of time of the result can be determined. The field "EVENT" will be filled with "calculated".
  
  With option deleteOther all datasets except the dataset with the maximum value are deleted.
  
  
  Example of building a new reading name from the original reading "totalpac":
  min_day_totalpac
  # <creation function>_<aggregation>_<original reading>
  
  
  Relevant attributes are:
  
  aggregation, device, executeBeforeProc, executeAfterProc, reading, readingNameMap, valueFilter, userExitFn, time.*-Attribute
  
  


• multiCmd {<Befehl-Hash>}
  
  Executes several set commands sequentially in a definable order.
  The commands and certain modifiable attributes that are relevant for the commands are transferred in a hash.
  The commands to be executed (key cmd) and the attributes to be set for them are defined via keys in the transferred hash. The order in which the commands are processed is determined via the command index in the hash which must not be '0'.
  
  Attribute keys that can be defined in the hash are:
  
  autoForward, averageCalcForm, device, executeBeforeProc, executeAfterProc, reading, readingNameMap, seqDoubletsVariance, timestamp_begin, timestamp_end, timeDiffToNow, timeOlderThan, timeYearPeriod, userExitFn,
  
  Note: All of the above attributes are deleted before each command index is executed.
  The attributes specified in the respective command index are set before the step is executed.
  
  Example of the definition of a command hash:
  

          {
            1  => { executeBeforeProc => 'set LogDB reopen 900',
                    timestamp_begin   => '2023-12-17 00:00:00',
                    timestamp_end     => '2023-12-17 01:00:00',
                    device            => 'SMA_Energymeter',
                    reading           => 'Einspeisung_Wirkleistung_Zaehler',
                    cmd               => 'countEntries history'
                  },
            2  => { timestamp_begin   => '2023-12-15 11:00:00',
                    timestamp_end     => 'previous_day_end',
                    device            => 'SMA_Energymeter',
                    reading           => 'Einspeisung_Wirkleistung_Zaehler',
                    cmd               => 'countEntries'
                  },
            3  => { timeDiffToNow     => 'd:2',
                    readingNameMap    => 'COUNT',
                    autoForward       => '{ ".*COUNT.*" => "Dum.Rep.All" }',
                    device            => 'SMA_%,MySTP.*',
                    reading           => 'etotal,etoday,Ein% EXCLUDE=%Wirkleistung',
                    cmd               => 'countEntries history'
                  },
            4  => { timeDiffToNow     => 'd:2',
                    readingNameMap    => 'SUM',
                    autoForward       => '{ ".*SUM.*" => "Dum.Rep.All" }',
                    device            => 'SMA_%,MySTP.*',
                    reading           => 'etotal,etoday,Ein% EXCLUDE=%Wirkleistung',
                    cmd               => 'sumValue'
                  },
            5  => { executeAfterProc  => 'set LogDB reopen',
                    cmd               => 'sqlCmd select count(*) from current'
                  },
          }
        



• optimizeTables [showInfo | execute]
  
  Optimize tables in the connected database (MySQL).
  
  

  showInfo	: shows information about the used / free space within the database
  execute	: performs optimization of all tables in the database

  
  Relevant attributes are:
  
  executeBeforeProc, executeAfterProc, userExitFn
  
  
• readingRename <[device:]oldreadingname>,<newreadingname>
  
  Renames the reading name of a device inside the connected database (see Internal DATABASE). The readingname will allways be changed in the entire database. Possibly set time limits or restrictions by attributes device and/or reading will not be considered.
  As an option a device can be specified. In this case only the old readings of this device will be renamed.
  
  
  Examples:
  set <name> readingRename TotalConsumtion,L1_TotalConsumtion
  set <name> readingRename Dum.Energy:TotalConsumtion,L1_TotalConsumtion
  
  
  The amount of renamed reading names (datasets) will be displayed in reading "reading_renamed".
  If the reading name to be renamed was not found in the database, a WARNING will appear in reading "reading_not_renamed".
  Appropriate entries will be written to Logfile if verbose >= 3 is set.
  
  Relevant attributes are:
  
  executeBeforeProc, executeAfterProc, userExitFn
  
  
  
• reduceLog [<no>[:<nn>]] [mode] [EXCLUDE=device1:reading1,device2:reading2,...] [INCLUDE=device:reading]
  
  Reduces historical data sets.
  
  Operation without specifying command line operators
  
  The data is cleaned within the time limits defined by the time.*-attributes. At least one of the time.* attributes must be set (see table below). The respective missing time accrual is determined by the module in this case.
  The working mode is determined by the optional specification of mode:
  
  

  without specification of mode	: the data is reduced to the first entry per hour per device & reading
  average	: numerical values are reduced to an average value per hour per device & reading, otherwise as without mode
  average=day	: numeric values are reduced to one mean value per day per device & reading, otherwise as without mode
  	The FullDay option (full days are always selected) is used implicitly.
  max	: numeric values are reduced to the maximum value per hour per device & reading, otherwise as without mode
  max=day	: numeric values are reduced to the maximum value per day per device & reading, otherwise as without mode
  	The FullDay option (full days are always selected) is used implicitly.
  min	: numeric values are reduced to the minimum value per hour per device & reading, otherwise as without mode
  min=day	: numeric values are reduced to the minimum value per day per device & reading, otherwise as without mode
  	The FullDay option (full days are always selected) is used implicitly.
  sum	: numeric values are reduced to the sum per hour per Device & Reading, otherwise as without mode
  sum=day	: numeric values are reduced to the sum per day per Device & Reading, otherwise as without mode
  	The FullDay option (full days are always selected) is used implicitly.

  
  With the attributes device and reading the data records to be considered can be included or be excluded. Both restrictions reduce the selected data and reduce the resource requirements. The read "reduceLogState" contains the execution result of the last reduceLog command.
  
  Relevant attributes are:
  
  executeBeforeProc, executeAfterProc, device, reading, numDecimalPlaces, timeOlderThan, timeDiffToNow, timestamp_begin, timestamp_end, valueFilter, userExitFn
  
  Examples:
  
  
  attr <name> timeOlderThan d:200
  set <name> reduceLog
  # Records older than 200 days are written to the first entry per hour per Device & Reading.
  
  attr <name> timeDiffToNow d:200
  set <name> reduceLog average=day
  # Records newer than 200 days are limited to one entry per day per Device & Reading.
  
  attr <name> timeDiffToNow d:30
  attr <name> device TYPE=SONOSPLAYER EXCLUDE=Sonos_Kueche
  attr <name> reading room% EXCLUDE=roomNameAlias
  set <name> reduceLog
  # Records newer than 30 days that are devices of type SONOSPLAYER (except Device "Sonos_Kitchen") and the readings start with "room" (except "roomNameAlias") are reduced to the first entry per hour per Device & Reading.
  
  attr <name> timeDiffToNow d:10
  attr <name> timeOlderThan d:5
  attr <name> device Luftdaten_remote
  set <name> reduceLog average
  # Records older than 5 and newer than 10 days and containing DEVICE "Luftdaten_remote are adjusted. Numerical values of an hour are reduced to an average value
  
  
  
  Operation with specification of command line operators
  
  Es werden Datensätze berücksichtigt die älter sind als <no> Tage und (optional) neuer sind als <nn> Tage. Records are considered that are older than <no> days and (optionally) newer than <nn> days. The working mode is determined by the optional specification of mode as described above.
  
  The additions "EXCLUDE" or "INCLUDE" can be added to exclude or include device/reading combinations in reduceLog and override the "device" and "reading" attributes, which are ignored in this case.
  The specification in "EXCLUDE" is evaluated as a regex. Inside "INCLUDE", SQL wildcards can be used. (for more information on SQL wildcards, see with get <name> versionNotes 6)
  
  Examples:
  
  
  set <name> reduceLog 174:180 average EXCLUDE=SMA_Energymeter:Bezug_Wirkleistung INCLUDE=SMA_Energymeter:%
  # Records older than 174 and newer than 180 days are reduced to average per hour.
  # All readings from the device "SMA_Energymeter" except "Bezug_Wirkleistung" are taken reduced.
  
  
  Note:
  Although the function itself is designed non-blocking, the assigned DbLog device should be operated in asynchronous mode to avoid blocking FHEMWEB (table lock).
  Furthermore it is strongly recommended to create the standard INDEX 'Search_Idx' in the table 'history' !
  The processing of this command may take an extremely long time (without INDEX).
  
  


• repairSQLite [sec]
  
  Repairs a corrupted SQLite database.
  
  A corruption is usally existent when the error message "database disk image is malformed" appears in reading "state" of the connected DbLog-device. If the command was started, the connected DbLog-device will firstly disconnected from the database for 10 hours (36000 seconds) automatically (breakup time). After the repair is finished, the DbLog-device will be connected to the (repaired) database immediately.
  As an argument the command can be completed by a differing breakup time (in seconds).
  The corrupted database is saved as <database>.corrupt in same directory.
  
  Relevant attributes are:
  
  executeBeforeProc, executeAfterProc, userExitFn
  
  Example:
  
  set <name> repairSQLite
  # the database is trying to repair, breakup time is 10 hours
  set <name> repairSQLite 600
  # the database is trying to repair, breakup time is 10 minutes
  
  
  Note:
  It can't be guaranteed, that the repair attempt proceed successfully and no data loss will result. Depending from corruption severity data loss may occur or the repair will fail even though no error appears during the repair process. Please make sure a valid backup took place !
  
  


• restoreMySQL <File> - restore a database from serverSide- or clientSide-Dump.
  
  The function provides a drop-down-list of files which can be used for restore.
  
  Usage of serverSide-Dumps
  The content of history-table will be restored from a serverSide-Dump. Therefore the remote directory "dumpDirRemote" of the MySQL-Server has to be mounted on the Client and make it usable to the DbRep device by setting attribute dumpDirLocal to the appropriate value.
  All files with extension "csv[.gzip]" and if the filename is beginning with the name of the connected database (see Internal DATABASE) are listed.
  
  Usage of clientSide-Dumps
  The used database user needs the FILE privilege (see Wiki).
  All tables and views (if present) are restored. The directory which contains the dump files has to be set by attribute dumpDirLocal to make it usable by the DbRep device.
  All files with extension "sql[.gzip]" and if the filename is beginning with the name of the connected database (see Internal DATABASE) are listed.
  The restore speed depends of the server variable "max_allowed_packet". You can change this variable in file my.cnf to adapt the speed. Please consider the need of sufficient ressources (especially RAM).
  
  The database user needs rights for database management, e.g.:
  CREATE, ALTER, INDEX, DROP, SHOW VIEW, CREATE VIEW
  
  Relevant attributes are:
  
  executeBeforeProc, executeAfterProc, dumpDirLocal, userExitFn
  
  


• restoreSQLite <File>.sqlitebkp[.gzip]
  
  Restores a backup of SQLite database.
  The function provides a drop-down-list of files which can be used for restore. The data stored in the current database are deleted respectively overwritten. All files with extension "sqlitebkp[.gzip]" and if the filename is beginning with the name of the connected database will are listed.
  
  Relevant attributes are:
  
  executeBeforeProc, executeAfterProc, userExitFn
  
  


• sqlCmd
  
  Executes any user-specific command.
  sqlCmd also accepts the setting of SQL session variables such as. "SET @open:=NULL, @closed:=NULL;" or the use of SQLite PRAGMA prior to the execution of the SQL statement. If the session variable or PRAGMA has to be set every time before executing a SQL statement, the attribute sqlCmdVars can be set.
  
  If the attributes device, reading, timestamp_begin respectively timestamp_end set in the module are to be taken into account in the statement, the placeholders §device§, §reading§, §timestamp_begin§ respectively §timestamp_end§ can be used for this purpose.
  It should be noted that the placeholders §device§ and §reading§ complex are resolved and should be applied accordingly as in the example below.
  
  If you want update a dataset, you have to add "TIMESTAMP=TIMESTAMP" to the update-statement to avoid changing the original timestamp.
  
  Examples of SQL-statements:
  
  
  • set <name> sqlCmd select DEVICE, count(*) from history where TIMESTAMP >= "2017-01-06 00:00:00" group by DEVICE having count(*) > 800
  • set <name> sqlCmd select DEVICE, count(*) from history where TIMESTAMP >= "2017-05-06 00:00:00" group by DEVICE
  • set <name> sqlCmd select DEVICE, count(*) from history where TIMESTAMP >= §timestamp_begin§ group by DEVICE
  • set <name> sqlCmd select * from history where DEVICE like "Te%t" order by `TIMESTAMP` desc
  • set <name> sqlCmd select * from history where `TIMESTAMP` > "2017-05-09 18:03:00" order by `TIMESTAMP` desc
  • set <name> sqlCmd select * from current order by `TIMESTAMP` desc
  • set <name> sqlCmd select sum(VALUE) as 'Einspeisung am 04.05.2017', count(*) as 'Anzahl' FROM history where `READING` = "Einspeisung_WirkP_Zaehler_Diff" and TIMESTAMP between '2017-05-04' AND '2017-05-05'
  • set <name> sqlCmd delete from current
  • set <name> sqlCmd delete from history where TIMESTAMP < "2016-05-06 00:00:00"
  • set <name> sqlCmd update history set TIMESTAMP=TIMESTAMP,VALUE='Val' WHERE VALUE='TestValue'
  • set <name> sqlCmd select * from history where DEVICE = "Test"
  • set <name> sqlCmd insert into history (TIMESTAMP, DEVICE, TYPE, EVENT, READING, VALUE, UNIT) VALUES ('2017-05-09 17:00:14','Test','manuell','manuell','Tes§e','TestValue','°C')
  • set <name> sqlCmd select DEVICE, count(*) from history where §device§ AND TIMESTAMP >= §timestamp_begin§ group by DEVICE
  • set <name> sqlCmd select DEVICE, READING, count(*) from history where §device§ AND §reading§ AND TIMESTAMP >= §timestamp_begin§ group by DEVICE, READING
  
  Here you can see examples of a more complex statement (MySQL) with setting SQL session variables and the SQLite PRAGMA usage:
  
  
  • set <name> sqlCmd SET @open:=NULL, @closed:=NULL; SELECT TIMESTAMP, VALUE,DEVICE, @open AS open, @open := IF(VALUE = 'open', TIMESTAMP, NULL) AS curr_open, @closed := IF(VALUE = 'closed', TIMESTAMP, NULL) AS closed FROM history WHERE DATE(TIMESTAMP) = CURDATE() AND DEVICE = "HT_Fensterkontakt" AND READING = "state" AND (VALUE = "open" OR VALUE = "closed") ORDER BY TIMESTAMP;
  • set <name> sqlCmd PRAGMA temp_store=MEMORY; PRAGMA synchronous=FULL; PRAGMA journal_mode=WAL; PRAGMA cache_size=4000; select count(*) from history;
  • set <name> sqlCmd PRAGMA temp_store=FILE; PRAGMA temp_store_directory = '/opt/fhem/'; VACUUM;
  
  The formatting of result can be choosen by attribute sqlResultFormat, as well as the used field separator can be determined by attribute sqlResultFieldSep.
  
  The module provides a command history once a sqlCmd command was executed successfully. To use this option, activate the attribute sqlCmdHistoryLength with list lenght you want.
  
  An SQL statement can be executed by specifying its list index:
  
  
  set <name> sqlCmd ckey:<Index>      (e.g. ckey:4)
  
  The list index "ckey:latest" executes the last statement saved in the SQL history.
  
  Relevant attributes are:
  
  executeBeforeProc, executeAfterProc, sqlResultFormat, sqlResultFieldSep, sqlCmdHistoryLength, sqlCmdVars, sqlFormatService, useAdminCredentials, userExitFn
  
  Note:
  Even though the module works non-blocking regarding to database operations, a huge sample space (number of rows/readings) could block the browser session respectively FHEMWEB.
  If you are unsure about the result of the statement, you should preventively add a limit to the statement.
  
  


• sqlCmdHistory
  
  If activated with the attribute sqlCmdHistoryLength, a stored SQL statement can be selected from a list and executed.
  The SQL cache is automatically saved when FHEM is closed and restored when the system is started.
  The following entries execute special functions:
  
  
  

  ___purge_sqlhistory___	: deletes the history cache
  ___list_sqlhistory___	: shows the SQL statements currently in the cache, including their cache key (ckey)
  ___save_sqlhistory___	: backs up the history cache manually
  ___restore_sqlhistory___	: restores the last backup of the history cache

  
  Relevant attributes are:
  
  executeBeforeProc, executeAfterProc, sqlResultFormat, sqlResultFieldSep, sqlCmdHistoryLength, sqlCmdVars, sqlFormatService, useAdminCredentials, userExitFn
  
  


• sqlSpecial
  
  This function provides a drop-down list with a selection of prepared reportings.
  The statements result is depicted in reading "SqlResult". The result can be formatted by attribute sqlResultFormat a well as the used field separator by attribute sqlResultFieldSep.
  
  

  50mostFreqLogsLast2days	reports the 50 most occuring log entries of the last 2 days
  allDevCount	all devices occuring in database and their quantity
  allDevReadCount	all device/reading combinations occuring in database and their quantity
  50DevReadCount	the 50 most frequently included device/reading combinations in the database
  recentReadingsOfDevice	determines the newest records of a device available in the database. The
  	device must be defined in attribute device
  readingsDifferenceByTimeDelta	determines the value difference of successive data records of a reading. The
  	device and reading must be defined in the attribute device or reading.
  	The time limits of the evaluation are defined by the time.*-attributes.

  
  Relevant attributes are:
  
  executeBeforeProc, executeAfterProc, sqlResultFormat, sqlResultFieldSep, sqlFormatService, device, reading, userExitFn
  
  
  


• sumValue [display | writeToDB | writeToDBSingle | writeToDBInTime]
  
  Calculates the total values of the database field "VALUE" in the time limits of the possible time.*-attributes.
  
  The reading to be evaluated must be specified in the attribute reading. This function is useful if continuous value differences of a reading are written into the database.
  
  If none or the option display is specified, the results are only displayed. With the options writeToDB, writeToDBSingle or writeToDBInTime the calculation results are written with a new reading name into the database.
  
  

  writeToDB	: writes one value each with the time stamps XX:XX:01 and XX:XX:59 within the respective aggregation period
  writeToDBSingle	: writes only one value with the time stamp XX:XX:59 at the end of an aggregation period
  writeToDBInTime	: writes a value at the beginning and end of the time limits of an aggregation period

  
  The new reading name is formed from a prefix and the original reading name, where the original reading name can be replaced by the attribute "readingNameMap". The prefix consists of the educational function and the aggregation.
  The timestamp of the new reading in the database is determined by the set aggregation period if no clear time of the result can be determined. The field "EVENT" is filled with "calculated".
  
  
  Example of building a new reading name from the original reading "totalpac":
  sum_day_totalpac
  # <creation function>_<aggregation>_<original reading>
  
  
  Relevant attributes are:
  
  executeBeforeProc, executeAfterProc, aggregation, device, reading, readingNameMap, valueFilter, userExitFn, time.*-attributes
  
  
  


• syncStandby <DbLog-Device Standby>
  
  Datasets of the connected database (source) are transmitted into another database (Standby-database).
  Here the "<DbLog-Device Standby>" is the DbLog-Device what is connected to the Standby-database.
  
  All the datasets which are determined by timestamp_begin attribute or respectively the attributes "device", "reading" are transmitted.
  The datasets are transmitted in time slices accordingly to the adjusted aggregation. If the attribute "aggregation" has value "no" or "month", the datasets are transmitted automatically in daily time slices into standby-database. Source- and Standby-database can be of different types.
  
  Relevant attributes are:
  
  executeBeforeProc, executeAfterProc, aggregation, device, reading, readingNameMap, valueFilter, userExitFn, time.*-attributes
  
  
  


• tableCurrentFillup
  
  The current-table will be filled u with an extract of the history-table.
  The attributes for limiting time and device, reading are considered.
  Thereby the content of the extract can be affected.
  In the associated DbLog-device the attribute "DbLogType" should be set to "SampleFill/History".
  
  Relevant attributes are:
  
  executeBeforeProc, executeAfterProc, device, reading, valueFilter, userExitFn, time.*-attributes
  
  
  
• tableCurrentPurge
  
  Deletes the content of current-table.
  There are no limits, e.g. by attributes timestamp_begin, timestamp_end, device or reading considered.
  
  Relevant attributes are:
  
  executeBeforeProc, executeAfterProc, userExitFn
  
  
  
• vacuum
  
  Optimizes the tables in the connected database (SQLite, PostgreSQL).
  Especially for SQLite databases it is strongly recommended to temporarily close the connection of the relevant DbLog device to the database (see DbLog reopen command).
  
  Relevant attributes are:
  
  executeBeforeProc, executeAfterProc, userExitFn
  
  Note:
  When the vacuum command is executed, the PRAGMA auto_vacuum = FULL is automatically applied to SQLite databases.
  The vacuum command requires additional temporary memory. If there is not enough space in the default TMPDIR directory, SQLite can be assigned a sufficiently large directory by setting the environment variable SQLITE_TMPDIR.
  (see also: www.sqlite.org/tempfiles)

Get

The get-commands of DbRep provide to retrieve some metadata of the used database instance. Those are for example adjusted server parameter, server variables, datadasestatus- and table informations. THe available get-functions depending of the used database type. So for SQLite curently only "get svrinfo" is usable. The functions nativ are delivering a lot of outpit values. They can be limited by function specific attributes. The filter has to be setup by a comma separated list. SQL-Wildcard (%) can be used to setup the list arguments.

Note:
After executing a get-funktion in detail view please make a browser refresh to see the results !


• blockinginfo
  List the current system wide running background processes (BlockingCalls) together with their informations. If character string is too long (e.g. arguments) it is reported shortened.



• dbstatus
  Lists global information about MySQL server status (e.g. informations related to cache, threads, bufferpools, etc. ). Initially all available informations are reported. Using the attribute showStatus the quantity of results can be limited to show only the desired values. Further detailed informations of items meaning are explained here.
  
  
  Example
  attr <name> showStatus %uptime%,%qcache%
  get <name> dbstatus
  # Only readings containing "uptime" and "qcache" in name will be created



• dbvars
  Lists global informations about MySQL system variables. Included are e.g. readings related to InnoDB-Home, datafile path, memory- or cache-parameter and so on. The Output reports initially all available informations. Using the attribute showVariables the quantity of results can be limited to show only the desired values. Further detailed informations of items meaning are explained here.
  
  
  Example
  attr <name> showVariables %version%,%query_cache%
  get <name> dbvars
  # Only readings containing "version" and "query_cache" in name will be created



• initData
  Determines some database properties relevant for the module function. The command is executed implicitly at the first database connection.



• minTimestamp - Identifies the oldest timestamp in the database (will be executed implicitely at FHEM start). The timestamp is used as begin of data selection if no time attribut is set to determine the start date.



• procinfo - Reports the existing database processes in a summary table (only MySQL).
  Typically only the own processes of the connection user (set in DbLog configuration file) will be reported. If all precesses have to be reported, the global "PROCESS" right has to be granted to the user.
  As of MariaDB 5.3 for particular SQL-Statements a progress reporting will be provided (table row "PROGRESS"). So you can track, for instance, the degree of processing during an index creation.
  Further informations can be found here.
  



• sqlCmdBlocking <SQL-statement>
  
  Executes the specified SQL statement blocking with a default timeout of 10 seconds. The timeout can be set with the attribute timeout.
  
  
  Examples:
  { fhem("get <name> sqlCmdBlocking select device,count(*) from history where timestamp > '2018-04-01' group by device") }
  { CommandGet(undef,"Rep.LogDB1 sqlCmdBlocking select device,count(*) from history where timestamp > '2018-04-01' group by device") }
  get <name> sqlCmdBlocking select device,count(*) from history where timestamp > '2018-04-01' group by device
  

Because of its mode of operation this function is particular convenient for user own perl scripts.
The input accepts multi line commands and delivers multi line results as well. This command also accept the setting of SQL session variables like "SET @open:=NULL, @closed:=NULL;" or PRAGMA for SQLite.
If several fields are selected and passed back, the fieds are separated by the separator defined by attribute sqlResultFieldSep (default "|"). Several result lines are separated by newline ("\n").
This function only set/update status readings, the userExitFn function isn't called.

If you create a little routine in 99_myUtils, for example:


sub dbval {
  my $name = shift;
  my $cmd) = shift;
  my $ret = CommandGet(undef,"$name sqlCmdBlocking $cmd");
  return $ret;
}
    

it can be accessed with e.g. those calls:


Examples:
{ dbval("<name>","select count(*) from history") }
$ret = dbval("<name>","select count(*) from history");




• storedCredentials - Reports the users / passwords stored for database access by the device.
  (only valid if database type is MYSQL)



• svrinfo - Common database server informations, e.g. DBMS-version, server address and port and so on. The quantity of elements to get depends on the database type. Using the attribute showSvrInfo the quantity of results can be limited to show only the desired values. Further detailed informations of items meaning are explained here.
  
  
  Example
  attr <name> showSvrInfo %SQL_CATALOG_TERM%,%NAME%
  get <name> svrinfo
  # Only readings containing "SQL_CATALOG_TERM" and "NAME" in name will be created



• tableinfo - Access detailed informations about tables in MySQL database which is connected by the DbRep-device. All available tables in the connected database will be selected by default. Using the attribute showTableInfo the results can be limited to tables you want to show. Further detailed informations of items meaning are explained here.
  
  
  Example
  attr <name> showTableInfo current,history
  get <name> tableinfo
  # Only informations related to tables "current" and "history" are going to be created



• versionNotes [hints | rel | <key>] - Shows realease informations and/or hints about the module.
  
  

  rel	: shows only release information
  hints	: shows only hints
  <key>	: the note with the specified number is displayed


It contains only main release informations for module users.
If no options are specified, both release informations and hints will be shown. "rel" shows only release informations and "hints" shows only hints. By the <key>-specification only the hint with the specified number is shown.

Attributes

Using the module specific attributes you are able to define the scope of evaluation and the aggregation.
The listed attrbutes are not completely relevant for every function of the module. The help of set/get-commands contain explicitly which attributes are relevant for the specific command.

Note for SQL-Wildcard Usage:
Within the attribute values of "device" and "reading" you may use SQL-Wildcard "%", Character "_" is not supported as a wildcard. The character "%" stands for any characters.
This rule is valid to all functions except "insert", "importFromFile" and "deviceRename".
The function "insert" doesn't allow setting the mentioned attributes containing the wildcard "%".
In readings the wildcard character "%" will be replaced by "/" to meet the rules of allowed characters in readings.


• aggregation
  
  Creation of the function results in time slices within the selection period.
  
  

  no	- No aggregation (default)
  minute	- the function results are summarized per minute
  hour	- the function results are summarized per hour
  day	- the function results are summarized per calendar day
  week	- the function results are summarized per calendar week
  month	- the function results are summarized per calendar month
  year	- the functional results are summarized per calendar year



• autoForward
  
  If activated, the result threads of a function are transferred to one or more devices.
  The definition takes the form:
  

    {
     "<source-reading>" => "<dest.device> [=> <dest.-reading>]",
     "<source-reading>" => "<dest.device> [=> <dest.-reading>]",
     ...
    }
    

  Wildcards (.*) are permitted in the specification <source-reading>.
  
  Example:

    {
      ".*"        => "Dum.Rep.All",
      ".*AVGAM.*" => "Dum.Rep     => average",
      ".*SUM.*"   => "Dum.Rep.Sum => summary",
    }
    # All readings are transferred to device "Dum.Rep.All", reading name remains in the target
    # readings with "AVGAM" in the name are transferred to the "Dum.Rep" device in the reading "average"
    # readings with "SUM" in the name are transferred to the device "Dum.Rep.Sum" in the reading "summary"
    



• averageCalcForm
  
  Defines the calculation variant for determining the average value with "averageValue".
  
  Currently the following variants are implemented:
  
  

  avgArithmeticMean:	The arithmetic average is calculated. (default)
  avgDailyMeanGWS:	Calculates the daily medium temperature according the
  	specifications of german weather service. (see also "get <name> versionNotes 2")
  	This variant uses aggregation "day" automatically.
  avgDailyMeanGWSwithGTS:	Same as "avgDailyMeanGWS" and additionally calculates the grassland temperature sum.
  	If the value 200 is reached, the reading "reachedGTSthreshold" is created with the
  	date of the first time this threshold value is reached.
  	Note: the attribute timestamp_begin must be set to the beginning of a year !
  	Note: The attribute timestamp_begin must be set to the beginning of a year!
  	(see also "get <name> versionNotes 5")
  avgTimeWeightMean:	Calculates the time-weighted average.
  	Note: There must be at least two data points per aggregation period.



• countEntriesDetail
  
  If set, the function countEntries creates a detailed report of counted datasets of every reading. By default only the summary of counted datasets is reported.


• device - Selection of particular or several devices.
  You can specify a list of devices separated by "," or use device specifications (devspec).
  In that case the device names are derived from the device specification and the existing devices in FHEM before carry out the SQL selection.
  If the the device, list or device specification is prepended by "EXCLUDE=", the devices are excluded from database selection.
  The database selection is executed as a logical AND operation of "device" and the attribute reading.
  
  
  Examples:
  attr <name> device TYPE=DbRep
attr <name> device MySTP_5000
attr <name> device SMA.*,MySTP.*
attr <name> device SMA_Energymeter,MySTP_5000
attr <name> device %5000
attr <name> device TYPE=SSCam EXCLUDE=SDS1_SVS
attr <name> device TYPE=SSCam,TYPE=ESPEasy EXCLUDE=SDS1_SVS
attr <name> device EXCLUDE=SDS1_SVS
attr <name> device EXCLUDE=TYPE=SSCam
  
  
  If you need more information about device specifications, execute "get <name> versionNotes 3".
  
  
• diffAccept - valid for function diffValue. diffAccept determines the threshold, up to that a calaculated difference between two straight sequently datasets should be commenly accepted (default = 20).
  Hence faulty DB entries with a disproportional high difference value will be eliminated and don't tamper the result. If a threshold overrun happens, the reading "diff_overrun_limit_<diffLimit>" will be generated (<diffLimit> will be substituted with the present prest attribute value).
  The reading contains a list of relevant pair of values. Using verbose=3 this list will also be reported in the FHEM logfile.
  
  
  Example report in logfile if threshold of diffAccept=10 overruns:
  
  DbRep Rep.STP5000.etotal -> data ignored while calc diffValue due to threshold overrun (diffAccept = 10):
  2016-04-09 08:50:50 0.0340 -> 2016-04-09 12:42:01 13.3440
  
  # The first dataset with a value of 0.0340 is untypical low compared to the next value of 13.3440 and results a untypical high difference value.
  # Now you have to decide if the (second) dataset should be deleted, ignored of the attribute diffAccept should be adjusted.
  
  
• dumpComment
  User-specific comment which is entered in the header of the file generated by "dumpMyQL clientSide".


• dumpCompress
  If set, the file created by "dumpMySQL" or "dumpSQLite" is then compressed and the uncompressed source file is deleted.


• dumpDirLocal
  
  
  Destination directory for creating dumps with "dumpMySQL clientSide" or "dumpSQLite".
  Setting this attribute activates the internal version management. In this directory backup files are searched and deleted if the found number exceeds the attribute value "dumpFilesKeep". The attribute is also used to make a locally mounted directory "dumpDirRemote" (for dumpMySQL serverSide) known to DbRep.
  (default: "{global}{modpath}/log/")
  
  Example:
  attr <Name> dumpDirLocal /sds1/backup/dumps_FHEM/
  
  
• dumpDirRemote - Target directory of database dumps by command "dumpMySQL serverSide" (default: the Home-directory of MySQL-Server on the MySQL-Host).


• dumpMemlimit - tolerable memory consumption for the SQL-script during generation period (default: 100000 characters). Please adjust this parameter if you may notice memory bottlenecks and performance problems based on it on your specific hardware.


• dumpSpeed - Number of Lines which will be selected in source database with one select by dump-command "dumpMySQL ClientSide" (default: 10000). This parameter impacts the run-time and consumption of resources directly.


• dumpFilesKeep
  
  
  The integrated version management leaves the specified number of backup files in the backup directory.
  Version management must be enabled by setting the "dumpDirLocal" attribute.
  If there are more (older) backup files, they will be deleted after a new backup has been successfully created. The global attribute "archivesort" is taken into account.
  (default: 3)
  
  
• executeAfterProc
  
  You can specify a FHEM command or Perl code that should be executed after the command is processed.
  Perl code is to be enclosed in {...}. The variables $hash (hash of the DbRep device) and $name (name of the DbRep device) are available.
  
  
  Example:
  
  attr <name> executeAfterProc set og_gz_westfenster off;
  attr <name> executeAfterProc {adump ($name)}
  
  # "adump" is a function defined in 99_myUtils.
  

  sub adump {
      my ($name) = @_;
      my $hash   = $defs{$name};
      # the own function, e.g.
      Log3($name, 3, "DbRep $name -> Dump is finished");
  
      return;
  }
  

• executeBeforeProc
  
  A FHEM command or Perl code can be specified which is to be executed before the command is processed.
  Perl code is to be enclosed in {...}. The variables $hash (hash of the DbRep device) and $name (name of the DbRep device) are available.
  
  
  Example:
  
  attr <name> executeBeforeProc set og_gz_westfenster on;
  attr <name> executeBeforeProc {bdump ($name)}
  
  # "bdump" is a function defined in 99_myUtils.
  

  sub bdump {
      my ($name) = @_;
      my $hash   = $defs{$name};
      # the own function, e.g.
      Log3($name, 3, "DbRep $name -> Dump starts");
  
      return;
  }
  

• expimpfile </path/file> [MAXLINES=<lines>] - Path/filename for data export/import.
  
  The maximum number of datasets which are exported into one file can be specified with the optional parameter "MAXLINES". In this case several files with extensions "_part1", "_part2", "_part3" and so on are created.
  The filename may contain wildcards which are replaced by corresponding values (see subsequent table). Furthermore filename can contain %-wildcards of the POSIX strftime function of the underlying OS (see your strftime manual).
  
  

  %L	: is replaced by the value of global logdir attribute
  %TSB	: is replaced by the (calculated) value of the start timestamp of the data selection
  	Common used POSIX-wildcards are:
  %d	: day of month (01..31)
  %m	: month (01..12)
  %Y	: year (1970...)
  %w	: day of week (0..6); 0 represents Sunday
  %j	: day of year (001..366)
  %U	: week number of year with Sunday as first day of week (00..53)
  %W	: week number of year with Monday as first day of week (00..53)

  
  
  Examples:
  attr <name> expimpfile /sds1/backup/exptest_%TSB.csv
attr <name> expimpfile /sds1/backup/exptest_%Y-%m-%d.csv
  
  
  About POSIX wildcard usage please see also explanations in Filelog.
  
  
  
• fastStart - Usually every DbRep device is making a short connect to its database when FHEM is started to retrieve some important informations and the reading "state" switches to "connected" on success. If this attrbute is set, the initial database connection is executed not till then the DbRep device is processing its first command.
  While the reading "state" is remaining in state "initialized" after FHEM-start.
  (default: 1 for TYPE Client)


• fetchMarkDuplicates - Highlighting of multiple occuring datasets in result of "fetchrows" command


• fetchRoute [descent | ascent] - specify the direction of data selection of the fetchrows-command.
  
  
  descent - the data are read descent (default). If amount of datasets specified by attribut "limit" is exceeded, the newest x datasets are shown.
  
  ascent - the data are read ascent . If amount of datasets specified by attribut "limit" is exceeded, the oldest x datasets are shown.
  



• fetchValueFn - When fetching the database content, you are able to manipulate the value fetched from the VALUE database field before create the appropriate reading. You have to insert a Perl function which is enclosed in {} .
  The value of the database field VALUE is provided in variable $VALUE.
  
  
  Example:
  attr <name> fetchValueFn { $VALUE =~ s/^.*Used:\s(.*)\sMB,.*/$1." MB"/e }
  # From a long line a specific pattern is extracted and will be displayed als VALUE instead the whole line



• ftpUse - FTP Transfer after dump will be switched on (without SSL encoding). The created database backup file will be transfered non-blocking to the FTP-Server (Attribut "ftpServer").


• ftpUseSSL - FTP Transfer with SSL encoding after dump. The created database backup file will be transfered non-blocking to the FTP-Server (Attribut "ftpServer").


• ftpUser - User for FTP-server login, default: "anonymous".


• ftpDebug - debugging of FTP communication for diagnostics.


• ftpDir - directory on FTP-server in which the file will be send into (default: "/").


• ftpDumpFilesKeep - leave the number of dump files in FTP-destination <ftpDir> (default: 3). Are there more (older) dump files present, these files are deleted after a new dump was transfered successfully.


• ftpPassive - set if passive FTP is to be used


• ftpPort - FTP-Port, default: 21


• ftpPwd - password of FTP-User, is not set by default


• ftpServer - name or IP-address of FTP-server. absolutely essential !


• ftpTimeout - timeout of FTP-connection in seconds (default: 30).


• limit - limits the number of selected datasets by the "fetchrows", or the shown datasets of "delSeqDoublets adviceDelete", "delSeqDoublets adviceRemain" commands (default: 1000). This limitation should prevent the browser session from overload and avoids FHEMWEB from blocking. Please change the attribut according your requirements or change the selection criteria (decrease evaluation period).


• numDecimalPlaces - Sets the number of decimal places for readings with numeric results.
  Excludes results from user-specific queries (sqlCmd).
  (default: 4)


• optimizeTablesBeforeDump - if set to "1", the database tables will be optimized before executing the dump (default: 0). Thereby the backup run-time time will be extended.
  
  
  Note
  The table optimizing cause locking the tables and therefore to blocking of FHEM if DbLog isn't working in asynchronous mode (DbLog-attribute "asyncMode") !
  


• reading - Selection of particular or several readings. More than one reading can be specified by a comma separated list.
  SQL wildcard (%) can be used.
  If the reading or the reading list is prepended by "EXCLUDE=", those readings are not included.
  The database selection is executed as a logical AND operation of "reading" and the attribute device.
  
  
  Examples:
  attr <name> reading etotal
attr <name> reading et%
attr <name> reading etotal,etoday
attr <name> reading eto%,Einspeisung EXCLUDE=etoday
attr <name> reading etotal,etoday,Ein% EXCLUDE=%Wirkleistung
  
  
  
  
• readingNameMap
  
  The part between the first and last double underscore ('__') of the created reading name is replaced with the specified string.


• role
  
  The role of the DbRep-device. Standard role is "Client".
  The role "Agent" is described in section DbRep-Agent.


• readingPreventFromDel
  
  Comma separated list of readings which are should prevent from deletion when a new operation starts.
  The readings can be specified as a regular expression.
  (default: state)
  
  
  Example:
  attr <name> readingPreventFromDel .*Count.*,.*Summary1.*,.*Summary2.*


• seqDoubletsVariance <positive variance [negative variance] [EDGE=negative|positive]>
  
  Accepted variance for the command "set <name> delSeqDoublets".
  The value of this attribute describes the variance up to consecutive numeric values (VALUE) of datasets are handled as identical. If only one numeric value is declared, it is used as postive as well as negative variance and both form the "deletion corridor". Optional a second numeric value for a negative variance, separated by blank,can be declared. Always absolute, i.e. positive numeric values, have to be declared.
  If the supplement "EDGE=negative" is declared, values at a negative edge (e.g. when value is changed from 4.0 -> 1.0) are not deleted although they are in the "deletion corridor". Equivalent is valid with "EDGE=positive" for the positive edge (e.g. the change from 1.2 -> 2.8).
  
  
  Examples:
  attr <name> seqDoubletsVariance 0.0014
attr <name> seqDoubletsVariance 1.45
attr <name> seqDoubletsVariance 3.0 2.0
attr <name> seqDoubletsVariance 1.5 EDGE=negative
  
  
  
  
• showproctime - if set, the reading "sql_processing_time" shows the required execution time (in seconds) for the sql-requests. This is not calculated for a single sql-statement, but the summary of all sql-statements necessara for within an executed DbRep-function in background.


• showStatus - limits the sample space of command "get <name> dbstatus". SQL-Wildcard (%) can be used.
  
  
  Example:
  attr <name> showStatus %uptime%,%qcache%
  # Only readings with containing "uptime" and "qcache" in name will be shown
  
  
  
• showVariables - limits the sample space of command "get <name> dbvars". SQL-Wildcard (%) can be used.
  
  
  Example:
  attr <name> showVariables %version%,%query_cache%
  # Only readings with containing "version" and "query_cache" in name will be shown
  
  
  
• showSvrInfo - limits the sample space of command "get <name> svrinfo". SQL-Wildcard (%) can be used.
  
  
  Example:
  attr <name> showSvrInfo %SQL_CATALOG_TERM%,%NAME%
  # Only readings with containing "SQL_CATALOG_TERM" and "NAME" in name will be shown
  
  
  
• showTableInfo
  
  Limits the result set of the command "get <name> tableinfo". SQL wildcard (%) can be used.
  
  
  Example:
  attr <name> showTableInfo current,history
  # Only information from the "current" and "history" tables is displayed.
  
  
  
• sqlCmdHistoryLength
  
  Activates the command history of "sqlCmd" with a value > 0 and defines the number of SQL statements to be stored.
  (default: 0)


• sqlCmdVars
  
  Sets the specified SQL session variable(s) or PRAGMA before each SQL statement executed with sqlCmd. SQL statement.
  
  
  Example:
  attr <name> sqlCmdVars SET @open:=NULL, @closed:=NULL;
  attr <name> sqlCmdVars PRAGMA temp_store=MEMORY;PRAGMA synchronous=FULL;PRAGMA journal_mode=WAL;
  
  
  


• sqlFormatService
  
  Automated formatting of SQL statements can be activated via an online service.
  This option is especially useful for complex SQL statements of the setters sqlCmd, sqlCmdHistory, and sqlSpecial to improve structuring and readability.
  An internet connection is required and the global attribute dnsServer should be set.
  (default: none)


• sqlResultFieldSep
  
  Sets the used field separator in the result of the command "set ... sqlCmd".
  (default: "|")


• sqlResultFormat - determines the formatting of the "set <name> sqlCmd" command result. Possible options are:
  
  
  separated - every line of the result will be generated sequentially in a single reading. (default)
  
  mline - the result will be generated as multiline in Reading SqlResult.
  
  sline - the result will be generated as singleline in Reading SqlResult. Datasets are separated by "]|[".
  
  table - the result will be generated as an table in Reading SqlResult.
  
  json - creates the Reading SqlResult as a JSON coded hash. Every hash-element consists of the serial number of the dataset (key) and its value.
  
  To process the result, you may use a userExitFn in 99_myUtils for example:
  

          sub resfromjson {
            my ($name,$reading,$value) = @_;
            my $hash   = $defs{$name};
  
            if ($reading eq "SqlResult") {
              # only reading SqlResult contains JSON encoded data
              my $data = decode_json($value);
  
              foreach my $k (keys(%$data)) {
  
                # use your own processing from here for every hash-element
                # e.g. output of every element that contains "Cam"
                my $ke = $data->{$k};
                if($ke =~ m/Cam/i) {
                  my ($res1,$res2) = split("\\|", $ke);
                  Log3($name, 1, "$name - extract element $k by userExitFn: ".$res1." ".$res2);
                }
              }
            }
          return;
          }
          

  
  
• timeYearPeriod <Month>-<Day> <Month>-<Day>
  An annual period is determined for the database selection. The annual period is calculated dynamically at execution time. It is not possible to provide information during the year.
  This attribute is primarily intended to create evaluations synchronized with a billing period, e.g. that of an energy or gas supplier.
  
  
  Example:
  
  attr <name> timeYearPeriod 06-25 06-24
  
  Evaluates the database in the time limits June 25 AAAA to June 24 BBBB.
  The year AAAA or BBBB is calculated depending on the current date.
  If the current date is >= June 25 and <= December 31, then AAAA = current year and BBBB = current year+1
  If the current date is >= January 01 and <= June 24, then AAAA = current year-1 and BBBB = current year
  
  
  
• timestamp_begin - begin of data selection
  The format of timestamp is as used with DbLog "YYYY-MM-DD HH:MM:SS". For the attributes "timestamp_begin", "timestamp_end" you can also use one of the following entries. The timestamp-attribute will be dynamically set to:
  
  
  current_year_begin : matches "<current year>-01-01 00:00:00"
  current_year_end : matches "<current year>-12-31 23:59:59"
  previous_year_begin : matches "<previous year>-01-01 00:00:00"
  previous_year_end : matches "<previous year>-12-31 23:59:59"
  current_month_begin : matches "<current month first day> 00:00:00"
  current_month_end : matches "<current month last day> 23:59:59"
  previous_month_begin : matches "<previous month first day> 00:00:00"
  previous_month_end : matches "<previous month last day> 23:59:59"
  current_week_begin : matches "<first day of current week> 00:00:00"
  current_week_end : matches "<last day of current week> 23:59:59"
  previous_week_begin : matches "<first day of previous week> 00:00:00"
  previous_week_end : matches "<last day of previous week> 23:59:59"
  current_day_begin : matches "<current day> 00:00:00"
  current_day_end : matches "<current day> 23:59:59"
  previous_day_begin : matches "<previous day> 00:00:00"
  previous_day_end : matches "<previous day> 23:59:59"
  next_day_begin : matches "<next day> 00:00:00"
  next_day_end : matches "<next day> 23:59:59"
  current_hour_begin : matches "<current hour>:00:00"
  current_hour_end : matches "<current hour>:59:59"
  previous_hour_begin : matches "<previous hour>:00:00"
  previous_hour_end : matches "<previous hour>:59:59"
  
  
  
  
• timestamp_end - end of data selection. If not set the current date/time combination will be used.
  The format of timestamp is as used with DbLog "YYYY-MM-DD HH:MM:SS". For the attributes "timestamp_begin", "timestamp_end" you can also use one of the following entries. The timestamp-attribute will be dynamically set to:
  
  
  current_year_begin : matches "<current year>-01-01 00:00:00"
  current_year_end : matches "<current year>-12-31 23:59:59"
  previous_year_begin : matches "<previous year>-01-01 00:00:00"
  previous_year_end : matches "<previous year>-12-31 23:59:59"
  current_month_begin : matches "<current month first day> 00:00:00"
  current_month_end : matches "<current month last day> 23:59:59"
  previous_month_begin : matches "<previous month first day> 00:00:00"
  previous_month_end : matches "<previous month last day> 23:59:59"
  current_week_begin : matches "<first day of current week> 00:00:00"
  current_week_end : matches "<last day of current week> 23:59:59"
  previous_week_begin : matches "<first day of previous week> 00:00:00"
  previous_week_end : matches "<last day of previous week> 23:59:59"
  current_day_begin : matches "<current day> 00:00:00"
  current_day_end : matches "<current day> 23:59:59"
  previous_day_begin : matches "<previous day> 00:00:00"
  previous_day_end : matches "<previous day> 23:59:59"
  next_day_begin : matches "<next day> 00:00:00"
  next_day_end : matches "<next day> 23:59:59"
  current_hour_begin : matches "<current hour>:00:00"
  current_hour_end : matches "<current hour>:59:59"
  previous_hour_begin : matches "<previous hour>:00:00"
  previous_hour_end : matches "<previous hour>:59:59"
  
  
  Make sure that "timestamp_begin" < "timestamp_end" is fulfilled.
  
  
  Example:
  
  attr <name> timestamp_begin current_year_begin
  attr <name> timestamp_end current_year_end
  
  # Analyzes the database between the time limits of the current year.
  
  
  
  Note
  If the attribute "timeDiffToNow" will be set, the attributes "timestamp_begin" respectively "timestamp_end" will be deleted if they were set before. The setting of "timestamp_begin" respectively "timestamp_end" causes the deletion of attribute "timeDiffToNow" if it was set before as well.
  
  
• timeDiffToNow - the begin time of data selection will be set to the timestamp "<current time> - <timeDiffToNow>" dynamically. The time period will be calculated dynamically at execution time. Optional can with the additional entry "FullDay" the selection start time and the selection end time be expanded to the begin / end of the involved days (take only effect if adjusted time difference is >= 1 day).
  
  
  Examples for input format:
  attr <name> timeDiffToNow 86400
  # the start time is set to "current time - 86400 seconds"
  attr <name> timeDiffToNow d:2 h:3 m:2 s:10
  # the start time is set to "current time - 2 days 3 hours 2 minutes 10 seconds"
  attr <name> timeDiffToNow m:600
  # the start time is set to "current time - 600 minutes" gesetzt
  attr <name> timeDiffToNow h:2.5
  # the start time is set to "current time - 2,5 hours"
  attr <name> timeDiffToNow y:1 h:2.5
  # the start time is set to "current time - 1 year and 2,5 hours"
  attr <name> timeDiffToNow y:1.5
  # the start time is set to "current time - 1.5 years"
  attr <name> timeDiffToNow d:8 FullDay
  # the start time is set to "current time - 8 days", the selection time period is expanded to the begin / end of the involved days
  
  
  If both attributes "timeDiffToNow" and "timeOlderThan" are set, the selection period will be calculated between of these timestamps dynamically.
  
  
• timeOlderThan - the end time of data selection will be set to the timestamp "<aktuelle Zeit> - <timeOlderThan>" dynamically. Always the datasets up to timestamp "<current time> - <timeOlderThan>" will be considered. The time period will be calculated dynamically at execution time. Optional can with the additional entry "FullDay" the selection start time and the selection end time be expanded to the begin / end of the involved days (take only effect if adjusted time difference is >= 1 day).
  
  
  Examples for input format:
  attr <name> timeOlderThan 86400
  # the selection end time is set to "current time - 86400 seconds"
  attr <name> timeOlderThan d:2 h:3 m:2 s:10
  # the selection end time is set to "current time - 2 days 3 hours 2 minutes 10 seconds"
  attr <name> timeOlderThan m:600
  # the selection end time is set to "current time - 600 minutes" gesetzt
  attr <name> timeOlderThan h:2.5
  # the selection end time is set to "current time - 2,5 hours"
  attr <name> timeOlderThan y:1 h:2.5
  # the selection end time is set to "current time - 1 year and 2,5 hours"
  attr <name> timeOlderThan y:1.5
  # the selection end time is set to "current time - 1.5 years"
  attr <name> timeOlderThan d:8 FullDay
  # the end time is set to "current time - 8 days", the selection time period is expanded to the begin / end of the involved days
  
  
  If both attributes "timeDiffToNow" and "timeOlderThan" are set, the selection period will be calculated between of these timestamps dynamically.
  
  
• timeout - set the timeout-value for Blocking-Call Routines in background in seconds (default 86400)


• useAdminCredentials - If set, a before with "set <aame> adminCredentials" saved privileged user is used for particular database operations.
  (only valid if database type is MYSQL and DbRep-type "Client")


• userExitFn - provides an interface for executing custom user code.
  Basically, the interface works without event generation or does not require an event to function. The interface can be used with the following variants.
  
  
  1. call a subroutine, e.g. in 99_myUtils.pm
  
  . The subroutine to be called is created in 99_myUtils.pm according to the following pattern:
  

  sub UserFunction {
    my $name    = shift;         # the name of the DbRep device.
    my $reading = shift;         # the name of the reading to create
    my $value   = shift;         # the value of the reading
    my $hash    = $defs{$name};
    ...
    # e.g. log passed data
    Log3 $name, 1, "UserExitFn $name called - transfer parameters are Reading: $reading, Value: $value " ;
    ...
  return;
  }
  

  In the attribute the subroutine and optionally a Reading:Value regex must be specified as an argument. Without this specification all Reading:Value combinations are evaluated as "true" and passed to the subroutine (equivalent to .*:.*).
  
  
  Example:
  attr userExitFn UserFunction Meter:Energy.*
  # "UserFunction" is the subroutine in 99_myUtils.pm.
  
  The regex is checked after the creation of each reading. If the check is true, the specified function is called.
  
  2. Direct input of custom code
  
  . The custom code is enclosed in curly braces. The code is called after the creation of each reading. In the code, the following variables are available for evaluation:
  
  
  • $NAME - the name of the DbRep device
  • $READING - the name of the reading created
  • $VALUE - the value of the reading
  
  
  Example:
  

  {
    if ($READING =~ /PrEnergySumHwc1_0_value__DIFF/) {
      my $mpk  = AttrVal($NAME, 'multiplier', '0');
      my $tarf = AttrVal($NAME, 'Tariff', '0');                                      # cost €/kWh
      my $m3   = sprintf "%.3f", $VALUE/10000 * $mpk;                                # consumed m3
      my $kwh  = sprintf "%.3f", $m3 * AttrVal($NAME, 'Calorific_kWh/m3', '0');      # conversion m3 -> kWh
      my $cost = sprintf "%.2f", $kwh * $tarf;
  
      my $hash = $defs{$NAME};
  
      readingsBulkUpdate ($hash, 'gas_consumption_m3', $m3);
      readingsBulkUpdate ($hash, 'gas_consumption_kwh', $kwh);
      readingsBulkUpdate ($hash, 'gas_costs_euro', $cost);
    }
  }
  

  # The readings gas_consumption_m3, gas_consumption_kwh and gas_costs_euro are calculated And generated in the DbRep device.



• valueFilter - Regular expression (REGEXP) to filter datasets within particular functions. The REGEXP is applied to a particular field or to the whole selected dataset (inclusive Device, Reading and so on). Please consider the explanations within the set-commands. Further information is available with command "get <name> versionNotes 4".

Readings

Regarding to the selected operation the reasults will be shown as readings. At the beginning of a new operation all old readings will be deleted to avoid that unsuitable or invalid readings would remain.

In addition the following readings will be created:


• state - contains the current state of evaluation. If warnings are occured (state = Warning) compare Readings "diff_overrun_limit_<diffLimit>" and "less_data_in_period"


• errortext - description about the reason of an error state


• background_processing_time - the processing time spent for operations in background/forked operation


• sql_processing_time - the processing time wasted for all sql-statements used for an operation


• diff_overrun_limit_<diffLimit> - contains a list of pairs of datasets which have overrun the threshold (<diffLimit>) of calculated difference each other determined by attribute "diffAccept" (default=20).


• less_data_in_period - contains a list of time periods within only one dataset was found. The difference calculation considers the last value of the aggregation period before the current one. Valid for function "diffValue".


• SqlResult - result of the last executed sqlCmd-command. The formatting can be specified by attribute sqlResultFormat


• sqlCmd - contains the last executed sqlCmd-command

DbRep Agent - automatic change of device names in databases and DbRep-definitions after FHEM "rename" command

By the attribute "role" the role of DbRep-device will be configured. The standard role is "Client". If the role has changed to "Agent", the DbRep device react automatically on renaming devices in your FHEM installation. The DbRep device is now called DbRep-Agent.

By the DbRep-Agent the following features are activated when a FHEM-device has being renamed:


• in the database connected to the DbRep-Agent (Internal Database) dataset containing the old device name will be searched and renamed to the to the new device name in all affected datasets.


• in the DbLog-Device assigned to the DbRep-Agent the definition will be changed to substitute the old device name by the new one. Thereby the logging of the renamed device will be going on in the database.


• in other existing DbRep-definitions with Type "Client" a possibly set attribute "device = old device name" will be changed to "device = new device name". Because of that, reporting definitions will be kept consistent automatically if devices are renamed in FHEM.


The following restrictions take place if a DbRep device was changed to an Agent by setting attribute "role" to "Agent". These conditions will be activated and checked:


• within a FHEM installation only one DbRep-Agent can be configured for every defined DbLog-database. That means, if more than one DbLog-database is present, you could define same numbers of DbRep-Agents as well as DbLog-devices are defined.


• after changing to DbRep-Agent role only the set-command "renameDevice" will be available and as well as a reduced set of module specific attributes will be permitted. If a DbRep-device of privious type "Client" has changed an Agent, furthermore not permitted attributes will be deleted if set.


All activities like database changes and changes of other DbRep-definitions will be logged in FHEM Logfile with verbose=3. In order that the renameDevice function don't running into timeout set the timeout attribute to an appropriate value, especially if there are databases with huge datasets to evaluate. As well as all the other database operations of this module, the autorename operation will be executed nonblocking.


Example of definition of a DbRep-device as an Agent:

define Rep.Agent DbRep LogDB
attr Rep.Agent devStateIcon connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen
attr Rep.Agent icon security
attr Rep.Agent role Agent
attr Rep.Agent room DbLog
attr Rep.Agent showproctime 1
attr Rep.Agent stateFormat { ReadingsVal($name, 'state', '') eq 'running' ? 'renaming' : ReadingsVal($name, 'state', ''). ' »; ProcTime: '.ReadingsVal($name, 'sql_processing_time', '').' sec'}
attr Rep.Agent timeout 86400


Note:
Even though the function itself is designed non-blocking, make sure the assigned DbLog-device is operating in asynchronous mode to avoid FHEMWEB from blocking.

DoorBird

The DoorBird module establishes the communication between the DoorBird - door intercommunication unit and the fhem home automation based on the official API, published by the manufacturer. Please make sure, that the user has been enabled the API-Operator button in the DoorBird Android/iPhone APP under "Administration -> User -> Edit -> Permission -> API-Operator". The following packet - installations are pre-requisite if not already installed by other modules (Examples below tested on Raspbian): sudo apt install sox sudo apt install libsox-fmt-all sudo apt install libsodium-dev sudo apt install gstreamer1.0-tools sudo cpan install Crypt::Argon2 sudo cpan install Sodium::FFI sudo cpan install IO::String module sudo cpan install IO::Socket




Define

define <name> DoorBird <IPv4-address> <Username> <Password>

<name> : The name of the device. Recommendation: "myDoorBird".

<IPv4-address> : A valid IPv4 address of the KMxxx. You might look into your router which DHCP address has been given to the DoorBird unit.

<Username> : The username which is required to sign on the DoorBird.

<Password> : The password which is required to sign on the DoorBird.




Set

The set function is able to change or activate the following features as follows:

set Light_On : Activates the IR lights of the DoorBird unit. The IR - light deactivates automatically by the default time within the Doorbird unit

set Live_Audio <on:off> : Activate/Deactivate the Live Audio Stream of the DoorBird on or off and toggles the direct link in the hidden Reading .AudioURL

set Live_Video <on:off> : Activate/Deactivate the Live Video Stream of the DoorBird on or off and toggles the direct link in the hidden Reading .VideoURL

set Open_Door <Value> : Activates the Relay of the DoorBird unit with the given address. The list of installed relay addresses are imported with the initialization of parameters.

set OpsMode<Value>DoorbellAudio : A selection of the audio files stored in the directory which is defined in the attribute "AudioFileDir". This file will be converted and send to the DoorBird to be played in case of doorbell activation.

set OpsMode<Value>DoorbellRelay : A selection of the installed relays which shall be activated in case of doorbell activation.

set OpsMode<Value>MotionAudio : A selection of the audio files stored in the directory which is defined in the attribute "AudioFileDir". This file will be converted and send to the DoorBird to be played in case of motion sensor triggering.

set OpsMode<Value>MotionRelay : A selection of the installed relays which shall be activated in case of motion sensor triggering.

set Receive_Audio <Path> : Receives an audio file and saves it. Requires a datapath to audio file to be saved. The user "fhem" needs to have write access to this directory.

set Restart : Sends the command to restart (reboot) the Doorbird unit

set Transmit_Audio <Path> : Converts a given audio file and transmits the stream to the DoorBird speaker. Requires a datapath to audio file to be converted and send. The user "fhem" needs to have write access to this directory.




Get

The get function is able to obtain the following information from the DoorBird unit:

get History_Request : Downloads the pictures of the last events of the doorbell and motion sensor. (Refer to attribute MaxHistory)

get Image_Request : Downloads the current Image of the camera of DoorBird unit.

get Video_Request <Value> : Downloads the current Video of the camera of DoorBird unit for the time in seconds given.

get Info_Request : Downloads the current internal setup such as relay configuration, firmware version etc. of the DoorBird unit. The obtained relay adresses will be used as options for the Open_Door command.




Attributes

The following user attributes can be used with the DoorBird module in addition to the global ones e.g. room.

disable : Stops the device from further reacting on UDP datagrams sent by the DoorBird unit. The default value is 0 = activated

KeepAliveTimeout : Timeout in seconds without still-alive UDP datagrams before state of device will be set to "disconnected". The default value is 30s

MaxHistory : Number of pictures to be downloaded from history for both - doorbell and motion sensor events. The default value is "50" which is the maximum possible.

PollingTimeout : Timeout in seconds before download requests are terminated in cause of no reaction by DoorBird unit. Might be required to be adjusted due to network speed. The default value is 10s.

UdpPort : Port number to be used to receice UDP datagrams. Ports are pre-defined by firmware. The default value is port 6524

SessionIdSec : Time in seconds for how long the session Id shall be valid, which is required for secure Video and Audio transmission. The DoorBird kills the session Id after 10min = 600s automatically. In case of use with CCTV recording units, this function must be disabled by setting to 0. The default value is 540s = 9min.

AudioFileDir : The relative (e.g. "audio") or absolute (e.g. "/mnt/NAS/audio") with or without trailing "/" directory path to which the audio files supposed to be stored. The default value is "" = disabled

AudioFileDirmaxSize : The maximum size of the AudioFileDir in Megabyte [MB]. If the maximum Size has been reached with audio files, the oldest files are deleted automatically The default value is 50 = 50MB

ImageFileDir : The relative (e.g. "images") or absolute (e.g. "/mnt/NAS/images") with or without trailing "/" directory path to which the image files supposed to be stored. The default value is "" = disabled

ImageFileDirmaxSize : The maximum size of the ImageFileDir in Megabyte [MB]. If the maximum Size has been reached with Image files, the oldest files are deleted automatically The default value is 50 = 50MB

VideoFileDir : The relative (e.g. "images") or absolute (e.g. "/mnt/NAS/images") with or without trailing "/" directory path to which the video files supposed to be stored. The default value is "" = disabled

VideoFileDirmaxSize : The maximum size of the VideoFileDir in Megabyte [MB]. If the maximum Size has been reached with Video files, the oldest files are deleted automatically The default value is 50 = 50MB

VideoFileFormat : The file format for the video file to be stored The default value is "mpeg"

VideoDurationDoorbell : Time in seconds for how long the video shall be recorded in case of an doorbbell event. The default value is 0 = disabled

VideoDurationMotion : Time in seconds for how long the video shall be recorded in case of an motion sensor event. The default value is 0 = disabled

EventReset : Time in seconds after wich the Readings for the Events Events (e.g. "doorbell_button", "motions sensor", "keypad") shal be reset to "idle". The default value is 5s

WaitForHistory : Time in seconds after wich the module shall wait for an history image triggered by an event is ready for download. Might be adjusted if fhem-Server and Doorbird unit have large differences in system time. The default value is 7s

OpsModeList : A space separated list of names for operational modes (e.g. "Normal Party Fire") on which the DoorBird reacts automatically on events. The default value is "" = disabled

HistoryFilePath : Creates relative datapaths to the last pictures, and videos in order to indicate them directly (e.g. fhem ftui widget "image") The default value is "0" = disabled

Dooya protocol

The Dooya protocol is used by a wide range of devices, which are either senders or receivers/actuators. The RECIVING and SENDING of Dooya commands is implemented in the SIGNALduino, so this module currently supports devices like blinds and shutters. The Dooya protocol is used from a lot of different shutter companies in Germanyr. Examples are Rohrmotor24 or Nobily.



  4: sduino/msg READ: MU;P0=4717;P1=-1577;P2=284;P3=-786;P4=649;P5=-423;D=01232345[......]445232;CP=2; 
  4: sduino: Fingerprint for MU Protocol id 16 -> Dooya shutter matches, trying to demodulate  
  4: sduino: decoded matched MU Protocol id 16 dmsg u16#370658E133 length 40  
  4: SIGNALduino_unknown Protocol: 16 
  4: SIGNALduino_unknown converted to bits: 0011011100000110010110001110000100110011  
  4: SIGNALduino_unknown / shutter Dooya 0011011100000110010110001110000100110011 received  
  4: 00110111000001100101100 1110 0001 0011 0011  
  4: SIGNALduino_unknown found shutter from Dooya. id=3606104, remotetype=14,  channel=1, direction=down, all_shutters=false  
  


a SIGNALduino device (must be defined first)



Define

define <name> Dooya <id>_<channel>

The id is a 28-digit binar code, that uniquely identifies a single remote control.
Pairing is done by setting the shutter in programming mode, either by disconnecting/reconnecting the power, and by pressing the program button on an already associated remote.
Once the shutter is in programming mode, send the "prog" command from within FHEM to complete the pairing. The shutter will peep shortly to indicate completion.
You are now able to control this blind from FHEM, the receiver thinks it is just another remote control or the real exist remote. For the shutter it´s the same.
• <id> is a 28 digit binar number that uniquely identifies FHEM as a new remote control.
  You can use a different one for each device definition, and group them using a structure. You can use the same ID for a couple of shutters and you can give every one an other channel. (0 to 15, 0 ist the MASTER and conrols all other channels.) If you set one of them, you need to pick the same address as an existing remote. You can create the Device with autocreate with a real remote or manuel without remote control.

Examples:
define Rollo_Master Dooya 0011011100000110010110001110_0
Rollo_Master channel 0 controls all shutters (channel 1 - 15) with the same ID, in this case Rollo_1 and Rollo_2

define Rollo_1 Dooya 0011011100000110010110001110_1
Rollo_1 channel 1
define Rollo_2 Dooya 0011011100000110010110101110_2
Rollo_2 channel 2


Set
set <name> <value> [<time>]

where value is one of:


    on
    off
    stop
    pos value (0..100) # see note
    prog  # Special, see note
    

Examples:
set rollo_1 on
set rollo_1 on,sleep 1,rollo_2 on,sleep 1,rollo_3 on
set rollo_1 off
set rollo_1 pos 50


Notes:
• prog is a special command used to pair the receiver to FHEM: Set the receiver in programming mode and send the "prog" command from FHEM to finish pairing.
  The shutter will peep shortly to indicate success.
• pos value
  The position is variying between 0 completely open and 100 for covering the full window. The position must be between 0 and 100 and the appropriate attributes drive-down-time-to-100, drive-down-time-to-close, drive-up-time-to-100 and drive-up-time-to-open must be set.
  
The position reading distinuishes between multiple cases
• Without timing values set only generic values are used for status and position:

  open, closed, moving

  are used
• With timing values set but drive-down-time-to-close equal to drive-down-time-to-100 and drive-up-time-to-100 equal 0 the device is considered to only vary between 0 and 100 (100 being completely closed)
• With full timing values set the device is considerd a window shutter (Rolladen) with a difference between covering the full window (position 100) and being completely closed (position 200)

Get
N/A

Attributes
• IODev
  Set the IO or physical device which should be used for sending signals for this "logical" device. It must be the SIGNALduino.
  Note: The IODev has to be set, otherwise no commands will be sent!
  


• channel
  Set the channel of the remote. You can use 0 (MASTER) to 15.
  Note: The MASTER conrols all remotes with the same ID!!!
  


• SignalRepeats
  Set the repeats for sending signal. You can use 5, 10, 15 and 20.


• additionalPosReading
  Position of the shutter will be stored in the reading pos as numeric value. Additionally this attribute might specify a name for an additional reading to be updated with the same value than the pos.


• eventMap
  Replace event names and set arguments. The value of this attribute consists of a list of space separated values, each value is a colon separated pair. The first part specifies the "old" value, the second the new/desired value. If the first character is slash(/) or comma(,) then split not by space but by this character, enabling to embed spaces. Examples:
  attr store eventMap on:open off:closed
attr store eventMap /on-for-timer 10:open/off:closed/
set store open


• do_not_notify


• dummy
  Set the device attribute dummy to define devices which should not output any radio signals. Associated notifys will be executed if the signal is received. Used e.g. to react to a code from a sender, but it will not emit radio signal if triggered in the web frontend.


• loglevel


• showtime


• ignore
  Ignore this device, e.g. if it belongs to your neighbour. The device won't trigger any FileLogs/notifys, issued commands will silently ignored (no RF signal will be sent out, just like for the dummy attribute). The device won't appear in the list command (only if it is explicitely asked for it), nor will it appear in commands which use some wildcard/attribute as name specifiers (see devspec). You still get them with the "ignored=1" special devspec.


• drive-down-time-to-100
  The time the blind needs to drive down from "open" (pos 0) to pos 100.
  In this position, the lower edge touches the window frame, but it is not completely shut.
  For a mid-size window this time is about 12 to 15 seconds.


• drive-down-time-to-close
  The time the blind needs to drive down from "open" (pos 0) to "close", the end position of the blind.
  This is about 3 to 5 seonds more than the "drive-down-time-to-100" value.


• drive-up-time-to-100
  The time the blind needs to drive up from "close" (endposition) to "pos 100".
  This usually takes about 3 to 5 seconds.


• drive-up-time-to-open
  The time the blind needs drive up from "close" (endposition) to "open" (upper endposition).
  This value is usually a bit higher than "drive-down-time-to-close", due to the blind's weight.



Generated events:
From a Dooya device you can receive one of the following events.
• on
• off
• stop
Which event is sent is device dependent and can sometimes be configured on the device.

EC3000

The Energy Count 3000 is a AC mains plug with integrated power meter functionality from CONRAD.

It can be integrated in to FHEM via a JeeLink as the IODevice.

Define
define <name> EC3000 <addr>

addr is a 4 digit hex number to identify the EC3000 device. Note: devices are autocreated on reception of the first message.


Set

Get

Readings
• consumption
• consumptionMax
• consumptionNow

Attributes
• offLevel
  a power level less or equal offLevel is considered to be off

ECMD

Any physical device with request/response-like communication capabilities over a serial line or TCP connection can be defined as ECMD device. A practical example of such a device is the AVR microcontroller board AVR-NET-IO from Pollin with ECMD-enabled Ethersex firmware. The original NetServer firmware from Pollin works as well. There is a plenitude of use cases.

A physical ECMD device can host any number of logical ECMD devices. Logical devices are defined as ECMDDevices in fhem. ADC 0 to 3 and I/O port 0 to 3 of the above mentioned board are examples of such logical devices. ADC 0 to 3 all belong to the same device class ADC (analog/digital converter). I/O port 0 to 3 belong to the device class I/O port. By means of extension boards you can make your physical device drive as many logical devices as you can imagine, e.g. IR receivers, LC displays, RF receivers/transmitters, 1-wire devices, etc.

Defining one fhem module for any device class would create an unmanageable number of modules. Thus, an abstraction layer is used. You create a device class on the fly and assign it to a logical ECMD device. The class definition names the parameters of the logical device, e.g. a placeholder for the number of the ADC or port, as well as the get and set capabilities. Worked examples are to be found in the documentation of the ECMDDevice device.

Note: this module requires the Device::SerialPort or Win32::SerialPort module if the module is connected via serial Port or USB.

Character coding

ECMD is suited to process any character including non-printable and control characters. User input for raw data, e.g. for setting attributes, and the display of raw data, e.g. in the log, is perl-encoded according to the following table (ooo stands for a three-digit octal number):


character	octal	code
Bell	007	\a
Backspace	008	\008
Escape	033	\e
Formfeed	014	\f
Newline	012	\n
Return	015	\r
Tab	011	\t
backslash	134	\134 or \\
any	ooo	\ooo


In user input, use \134 for backslash to avoid conflicts with the way FHEM handles continuation lines.

Define


define <name> ECMD telnet <IPAddress:Port>

or

define <name> ECMD serial <SerialDevice>[<@BaudRate>]

Defines a physical ECMD device. The keywords telnet or serial are fixed.

Examples:
define AVRNETIO ECMD telnet 192.168.0.91:2701
define AVRNETIO ECMD serial /dev/ttyS0
define AVRNETIO ECMD serial /dev/ttyUSB0@38400



Set


set <name> classdef <classname> <filename>

Creates a new device class <classname> for logical devices. The class definition is in the file <filename>. You must create the device class before you create a logical device that adheres to that definition.

Example:
set AVRNETIO classdef /etc/fhem/ADC.classdef


set <name> reopen

Closes and reopens the device. Could be handy if connection is lost and cannot be reestablished automatically.


Get


get <name> raw <command>

Sends the command <command> to the physical ECMD device <name> and reads the response. In the likely case that the command needs to be terminated by a newline character, you have to resort to a <perl special>.

Example:
get AVRNETIO raw { "ip\n" }



Attributes


• classdefs
  A colon-separated list of <classname>=<filename>. The list is automatically updated if a class definition is added. You can directly set the attribute. Example: attr myECMD classdefs ADC=/etc/fhem/ADC.classdef:GPIO=/etc/fhem/AllInOne.classdef
• split <separator>
  Some devices send several readings in one transmission. The split attribute defines the separator to split such transmissions into separate messages. The regular expression for matching a reading is then applied to each message in turn. After splitting, the separator is still part of the single messages. Separator can be a single- or multi-character string, e.g. \n or \r\n. Example: attr myECMD split \n splits foo 12\nbar off\n into foo 12\n and bar off\n.
• logTraffic <loglevel>
  Enables logging of sent and received datagrams with the given loglevel. Control characters in the logged datagrams are escaped, i.e. a double backslash is shown for a single backslash, \n is shown for a line feed character, etc.
• timeout <seconds>
  Time in seconds to wait for a response from the physical ECMD device before FHEM assumes that something has gone wrong. The default is 3 seconds if this attribute is not set.
• partial <seconds>
  Some physical ECMD devices split responses into several transmissions. If the partial attribute is set, this behavior is accounted for as follows: (a) If a response is expected for a get or set command, FHEM collects transmissions from the physical ECMD device until either the response matches the expected response (reading ... match ... in the class definition) or the time in seconds given with the partial attribute has expired. (b) If a spontaneous transmission does not match the regular expression for any reading, the transmission is recorded and prepended to the next transmission. If the line is quiet for longer than the time in seconds given with the partial attribute, the recorded transmission is discarded. Use regular expressions that produce exact matches of the complete response (after combining partials and splitting).
• requestSeparator <separator>
  A single command from FHEM to the device might need to be broken down into several requests. A command string is split at all occurrences of the request separator. The request separator itself is removed from the command string and thus is not part of the request. The default is to have no request separator. Use a request separator that does not occur in the actual request.
• responseSeparator <separator>
  In order to identify the single responses from the device for each part of the command broken down by request separators, a response separator can be appended to the response to each single request. The response separator is only appended to commands split by means of a request separator. The default is to have no response separator, i.e. responses are simply concatenated. Use a response separator that does not occur in the actual response.
• autoReopen <timeout>,<delay>
  If this attribute is set, the device is automatically reopened if no bytes were written for <timeout> seconds or more. After reopening FHEM waits <delay> seconds before writing to the device. Use the delay with care because it stalls FHEM completely.
• stop
  Disables read/write access to the device if set to 1. No data is written to the physical ECMD device. A read request always returns an undefined result. This attribute can be used to temporarily disable a device that is not available.
• verbose


Separators

When to use the split and partial attributes?

Set the partial attribute in combination with reading ... match ... in the class definition, if you receive datagrams with responses which are broken into several transmissions, like resp followed by onse\r\n.

Set the split attribute if you receive several responses in one transmission, like reply1\r\nreply2\r\n.

When to use the requestSeparator and responseSeparator attributes?

Set the requestSeparator attribute, if you want to send several requests in one command, with one transmission per request. The strings sent to the device for set and get commands as defined in the class definition are broken down into several request/response interactions with the physical device. The request separator is not sent to the physical device.

Set the responseSeparator attribute to separate the responses received for a command broken down into several requests by means of a request separator. This is useful for easier postprocessing.

Example: you want to send the requests request1 and request2 in one command. The physical device would respond with response1 and response2 respectively for each of the requests. You set the request separator to \000 and the response separator to \001 and you define the command as request1\000request2\000. The command is broken down into request1 and request2. request1 is sent to the physical device and response1 is received, followed by sending request2 and receiving response2. The final result is response1\001response2\001.

You can think of this feature as of a macro. Splitting and partial matching is still done per single request/response within the macro.

Datagram monitoring and matching

Data to and from the physical device is processed as is. In particular, if you need to send a line feed you have to explicitely send a \n control character. On the other hand, control characters like line feeds are not stripped from the data received. This needs to be considered when defining a class definition.

For debugging purposes, especially when designing a class definition, it is advisable to turn traffic logging on. Use attr myECMD logTraffic 3 to log all data to and from the physical device at level 3.

Datagrams and attribute values are logged with non-printable and control characters encoded as here followed by the octal representation in parantheses. Example: #!foo\r\n (\043\041\146\157\157\015\012).

Data received from the physical device is processed as it comes in chunks. If for some reason a datagram from the device is split in transit, pattern matching and processing will most likely fail. You can use the partial attribute to make FHEM collect and recombine the chunks.

Connection error handling

This modules handles unexpected disconnects of devices as follows (on Windows only for TCP connections):

Disconnects are detected if and only if data from the device in reply to data sent to the device cannot be received with at most two attempts. FHEM waits at most 3 seconds (or the time specified in the timeout attribute, see Attributes). After the first failed attempt, the connection to the device is closed and reopened again. The state of the device is failed. Then the data is sent again to the device. If still no reply is received, the state of the device is disconnected, otherwise opened. You will have to fix the problem and then use set myECMD reopen to reconnect to the device.

Please design your class definitions in such a way that the double sending of data does not bite you in any case.

Class definition

The class definition for a logical ECMD device class is contained in a text file. The text file is made up of single lines. Empty lines and text beginning with # (hash) are ignored. Therefore make sure not to use hashes in commands.
The following commands are recognized in the device class definition:



• params <parameter1> [<parameter2> [<parameter3> ... ]]
  
  Declares the names of the named parameters that must be present in the definition of the logical ECMD device.
  
  
• state <reading>
  
  Normally, the state reading is set to the latest command or reading name followed by the value, if any. This command sets the state reading to the value of the named reading if and only if the reading is updated.
  
  
• set <commandname> cmd { <perl special> }
get <commandname> cmd { <perl special> }
  
  Declares a new set or get command <commandname>. If the user invokes the set or get command <commandname>, the string that results from the execution of the <perl special> is sent to the physical device.

  A request separator (see Attributes) can be used to split the command into chunks. This is required for sending multiple Ethersex commands for one command in the class definition. The result string for the command is the concatenation of all responses received from the physical device, optionally with response separators (see Attributes) in between.
  
  

• set <commandname> expect "<regex>"
get <commandname> expect "<regex>"
  
  Declares what FHEM expects to receive after the execution of the get or set command <commandname>. <regex> is a Perl regular expression. The double quotes around the regular expression are mandatory and they are not part of the regular expression itself. <regex> must match the entire reply, as in m/^<regex>$/. Particularly, broken connections can only be detected if something is expected (see Connection error handling).
  
  
• set <commandname> postproc { <perl special> }
get <commandname> postproc { <perl special> }
  
  Declares a postprocessor for the command <commandname>. The data received from the physical device in reply to the get or set command <commandname> is processed by the Perl code <perl command>. The perl code operates on $_. Make sure to return the result in $_ as well. The result of the perl command is shown as the result of the get or set command.
  
  
• set <commandname> params <parameter1> [<parameter2> [<parameter3> ... ]]
get <commandname> params <parameter1> [<parameter2> [<parameter3> ... ]]
  
  Declares the names of the named parameters that must be present in the set or get command <commandname>. Be careful not to use a parameter name that is already used in the device definition (see params above).
  
  
• reading <reading> match "<regex>"
  
  Declares a new reading named <reading>. A spontaneous data transmission from the physical device that matches the Perl regular expression <regex> is evaluated to become the value of the named reading. All ECMDDevice devices belonging to the ECMD device with readings with matching regular expressions will receive an update of the said readings. <regex> must match the entire reply, as in m/^<regex>$/.
  
  
• reading <reading> postproc { <perl special> }
  
  Declares a postprocessor for the reading <reading>. The data received for the named reading is processed by the Perl code <perl command>. This works analogously to the postproc spec for set and get commands.
  
  
The perl specials in the definitions above can contain macros:


• The macro %NAME will expand to the device name.
• The macro %TYPE will expand to the device type.
• The macro %<parameter> will expand to the current value of the named parameter. This can be either a parameter from the device definition or a parameter from the set or get command.
• The macro substitution occurs before perl evaluates the expression. It is a plain text substitution. Be careful not to use parameters with overlapping names like %pin and %pin1.
• If in doubt what happens, run the commands with loglevel 5 and inspect the log file.


The rules outlined in the documentation of perl specials for the <perl command> in the postprocessor definitions apply. Note: Beware of undesired side effects from e.g. doubling of semicolons!

ECMDDevice

Define
define <name> ECMDDevice [<classname> [<parameter1> [<parameter2> [<parameter3> ... ]]]]

Defines a logical ECMD device. The number of given parameters must match those given in the class definition of the device class <classname>.

Normally, the logical ECMDDevice is attached to the latest previously defined physical ECMD device for I/O. Use the IODev attribute of the logical ECMDDevice to attach to any physical ECMD device, e.g. attr myRelais2 IODev myAVRNETIO. In such a case the correct reference to the class cannot be made at the time of definition of the device. Thus, you need to omit the <classname> and <parameter> references in the definition of the device and use the class attribute instead.

Examples:

define myADC ECMDDevice ADC
define myRelais1 ECMDDevice relais 8
define myRelais2 ECMDDevice
attr myRelais2 IODev myAVRNETIO
attr myRelais2 class relais 8


Set
set <name> <commandname> [<parameter1> [<parameter2> [<parameter3> ... ]]]

The number of given parameters must match those given for the set command <commandname> definition in the class definition.

If set <commandname> is invoked the perl special in curly brackets from the command definition is evaluated and the result is sent to the physical ECMD device.

Example:
set myRelais1 on
set myDisplay text This\x20text\x20has\x20blanks!



Get
get <name> <commandname> [<parameter1> [<parameter2> [<parameter3> ... ]]]

The number of given parameters must match those given for the get command <commandname> definition in the class definition.

If get <commandname> is invoked the perl special in curly brackets from the command definition is evaluated and the result is sent to the physical ECMD device. The response from the physical ECMD device is returned and the state of the logical ECMD device is updated accordingly.

Example:
get myADC value 3



Attributes
• class
  If you omit the <classname> and <parameter> references in the definition of the device, you have to add them separately as an attribute. Example: attr myRelais2 class relais 8.
• noState
  Changes of readings do not change the state reading if this attribute is set to a non-zero value. For example, this is desirable if you need to avoid the second event created by changing the state reading. Previously created state readings can be deleted by means of deletereading. The user can define the value shown in the state of the device by means of the stateFormat attribute.
• verbose
• eventMap
• IODev
• readingFnAttributes


Example 1


The following example shows how to access the ADC of the AVR-NET-IO board from Pollin with ECMD-enabled Ethersex firmware.

The class definition file /etc/fhem/ADC.classdef looks as follows:

get value cmd {"adc get %channel\n"}
get value params channel
get value expect "\d+\n"
get value postproc { s/^(\d+)\n$/$1/;; $_ }

In the fhem configuration file or on the fhem command line we do the following:

define AVRNETIO ECMD telnet 192.168.0.91:2701 # define the physical device
attr AVRNETIO classdefs ADC=/etc/fhem/ADC.classdef # define the device class ADC
define myADC ECDMDevice ADC # define the logical device myADC with device class ADC
get myADC value 1 # retrieve the value of analog/digital converter number 1

The get command is evaluated as follows: get value has one named parameter channel. In the example the literal 1 is given and thus %channel is replaced by 1 to yield "adc get 1\n" after macro substitution. Perl evaluates this to a literal string which is send as a plain ethersex command to the AVR-NET-IO. The board returns something like 024\n for the current value of analog/digital converter number 1. The postprocessor keeps only the digits.


Example 2


The following example shows how to switch a relais driven by pin 3 (bit mask 0x08) of I/O port 2 on for one second and then off again.

The class definition file /etc/fhem/relais.classdef looks as follows:

params pinmask
set on cmd {"io set ddr 2 ff\n\000ioset port 2 0%pinmask\n\000wait 1000\n\000io set port 2 00\n"}
set on expect ".*"
set on postproc {s/^OK\nOK\nOK\nOK\n$/success/; "$_" eq "success" ? "ok" : "error"; }

In the fhem configuration file or on the fhem command line we do the following:

define AVRNETIO ECMD telnet 192.168.0.91:2701 # define the physical device
attr AVRNETIO classdefs relais=/etc/fhem/relais.classdef # define the device class relais
attr AVRNETIO requestSeparator \000
define myRelais ECMDDevice 8 # define the logical device myRelais with pin mask 8
set myRelais on # execute the "on" command

The set command is evaluated as follows: %pinmask is replaced by 8 to yield "io set ddr 2 ff\n\000io set port 2 08\n\000wait 1000\n\000io set port 2 00\n\000" after macro substitution. Perl evaluates this to a literal string. This string is split into lines (with trailing newline characters)
• io set ddr 2 ff\n
• ioset port 2 08\n
• wait 1000\n
• io set port 2 00\n
These lines are sent as a plain ethersex commands to the AVR-NET-IO one by one. After each line the answer from the physical device is read back. They are concatenated and returned for further processing by the postproc command. For any of the four plain ethersex commands, the AVR-NET-IO returns the string OK\n. They are concatenated. The postprocessor takes the result from $_, substitutes it by the string success if it is OK\nOK\nOK\nOK\n, and then either returns the string ok or the string error. If the responseSeparator was set to \000, the result string would be OK\n\000OK\n\000OK\n\000OK\n\000 instead of OK\nOK\nOK\nOK\n.


Example 3


The following example shows how to implement a sandbox.

The class definition file /etc/fhem/DummyServer.classdef looks as follows:

reading foo match "\d+\n"
reading foo postproc { s/^(\d+).*$/$1/;; $_ }

In the fhem configuration file or on the fhem command line we do the following:

define myDummyServer ECMD telnet localhost:9999 # define the physical device
set myDummyServer classdef DummyServer /etc/fhem/DummyServer.classdef # define the device class DummyServer
define myDummyClient ECDMDevice DummyServer # define a logical device with device class DummyServer


On a Unix command line, run netcat -l 9999. This makes netcat listening on port 9999. Data received on that port are printed on stdout. Data input from stdin is sent to the other end of an incoming connection.

Start FHEM.

Then enter the number 4711 at the stdin of the running netcat server.

FHEM sees 4711\n coming in from the netcat dummy server. The incoming string matches the regular expression of the foo reading. The postprocessor is used to strip any trailing garbage from the digits. The result 4711 is used to update the foo reading.

EGPM Socket

Defines a Socket from EGPM2LAN Module. If the global Module AUTOCREATE is enabled, this device will be created automatically. For manual Setup, pls. see the description of EGPM2LAN.

Define
define <name> EGPM <device> <socket-nr>


Set
set <name> <[on|off|toggle]>
Switches the socket on or of.
set <name> <[on-for-timer|off-for-timer|on-till|off-till|blink|intervals]>
Switches the socket for a specified time+duration or n-times. For Details see set extensions

Example:
define lamp1 EGPM mainswitch 1
set lamp1 on


Get
N/A

Attributes
• readingFnAttributes

Generated events
• EGPM <name> <[on|off]>

EGPM2LAN

Define
define <name> EGPM2LAN <IP-Address>

Creates a Gembird ® Energenie EG-PM2-LAN device to switch up to 4 sockets over the network. If you have more than one device, it is helpful to connect and set names for your sockets over the web-interface first. The name settings will be adopted to FHEM and helps you to identify the sockets. Please make sure that you´re logged off from the Energenie web-interface otherwise you can´t control it with FHEM at the same time.
Create a EGPM-Module to control a single socket with additional features.
EG-PMS2-LAN with surge protector feature was not tested until now.

Set
set <name> password [<one-word>]
Encrypt and store device-password in FHEM. Leave empty to remove the password.
Before 04/2017, the password was stored in clear-text using the DEFINE-Command, but it should not be stored in the config-file.

set <name> <[on|off|toggle]> <socketnr.>
Switch the socket on or off.

set <name> <[on|off]> <all>
Switch all available sockets on or off.

set <name> <staterequest>
Update the device information and the state of all sockets.
If autocreate is enabled, an EGPM device will be created for each socket.

set <name> <clearreadings>
Removes all readings from the list to get rid of old socketnames.

Get
get <name> state
Returns a text like this: "1: off 2: on 3: off 4: off" or the last error-message if something went wrong.


Attributes
• stateDisplay
Default: socketNumer changes between socketNumer and socketName in front of the current state. Call set statusrequest to update all states.
• autocreate
Default: on EGPM-devices will be created automatically with a set-command. Change this attribute to value off to avoid that mechanism.
• loglevel
• readingFnAttributes



Example:
define mainswitch EGPM2LAN 10.192.192.20
set mainswitch password SecretGarden
set mainswitch on 1

EM

Define
define <name> EM <em1010pc-device>

Define a EM1010PC USB device. As the EM1010PC was not designed to be used with a PC attached to it all the time, it won't transmit received signals automatically, fhem has to poll it every 5 minutes.
Currently there is no way to read the internal log of the EM1010PC with fhem, use the program em1010.pl in the contrib directory for this purpose.

Examples:
define em EM /dev/elv_em1010pc


Set
set EM <value>

where value is either time or reset.
If time has arguments of the form YYYY-MM-DD HH:MM:SS, then the specified time will be set, else the time from the host.
Note: after reset you should set the time.

Get
get EM <value>

where value is either version or time.
Attributes
• model (em1010pc)
• dummy

EMEM

Define
define <name> EMEM <device-number>

Define up to 4 EM1000EM attached to the EM1010PC. The device number must be between 5 and 8. Defining an EMEM will schedule an internal task, which reads the status of the device every 5 minutes, and triggers notify/filelog commands.
Note: Currently this device does not support a "set" function.

Example:
define emem EMEM 5


Set
N/A

Get
get EMEM status

This is the same command which is scheduled every 5 minutes internally.

Attributes
• model (EM1000EM)
• dummy
• IODev

EMGZ

Define
define <name> EMGZ <device-number>

Define up to 4 EM1000GZ attached to the EM1010PC. The device number must be between 9 and 12. Defining an EMGZ will schedule an internal task, which reads the status of the device every 5 minutes, and triggers notify/filelog commands.

Example:
define emgz EMGZ 9

Set
set EMGZdevice <param> <value>

where param is:
• price
  The price of one KW in EURO (use e.g. 0.20 for 20 Cents). It is used only on the EM1010PC display, it is of no interest for FHEM.

Get
get EMGZ status

This is the same command which is scheduled every 5 minutes internally.

Attributes
• model (EM1000GZ)
• dummy
• IODev

EMT7110

The EMT7110 is a plug with integrated power meter functionality.
It can be integrated into FHEM via a JeeLink as the IODevice.

The EMT7110 sends with 9.579 kbit/s. Therefore it is necessary to set the JeeLink to a mode where it recieves this data rate.
This can be done using the initCommands attribute of the JeeLink.

If you have only 9.579 kbit/s sensors use this setting:
attr myJeeLink initCommands 1r v

If you have also 17.241 kbit/s sensors (like TX29...) use this setting:
attr myJeeLink initCommands 30t v
30t means that the JeeLink toggles the data rate every 30 Seconds.

Define define <name> EMT7110 <addr>
addr is a 4 digit hex number to identify the EMT7110 device.
To enable autocreate for a certain time you must set LaCrossePairForSec in the JeeLink IODevice device.

Set
• resetAccumulatedPower
  Sets the accumulatedPowerOffset attribute to the current value of accumulatedPowerMeasured. Don't forget to call save to write the new value to fhem.cfg

Get

Readings
• accumulatedPowerMeasured
  The accumulated power sent by the EMT7110. The EMT7110 accumulates the power even if it was removed and reconnected to the power outlet. The only way to reset it is to remove and reinsert the batteries in the EMT7110.


• accumulatedPower
  Is accumulatedPowerMeasured minus the value of the accumulatedPowerOffset attribute value This reading is used for the A: part of state


• costs
  Is accumulatedPower * pricePerKWH attribute value


• current
  The measured current in mA


• power
  The measured power in Watt


• voltage
  The measured voltage in Volt


Attributes
• accumulatedPowerOffset
  See accumulatedPower reading


• pricePerKWH
  See costs reading

EMWZ

Define
define <name> EMWZ <device-number>

Define up to 4 EM1000WZ attached to the EM1010PC. The device number must be between 1 and 4. Defining an EMWZ will schedule an internal task, which reads the status of the device every 5 minutes, and triggers notify/filelog commands.

Example:
define emwz EMWZ 1


Set
set EMWZdevice <param> <value>

where param is one of:
• rperkw
  Number of rotations for a KiloWatt of the EM1000WZ device (actually of the device where the EM1000WZ is attached to). Without setting this correctly, all other readings will be incorrect.
• alarm
  Alarm in WATT. if you forget to set it, the default value is rediculously low (random), and if a value above this threshold is received, the EM1010PC will start beeping once every minute. It can be very annoying.
• price
  The price of one KW in EURO (use e.g. 0.20 for 20 Cents). It is used only on the EM1010PC display, it is of no interest for FHEM.

Get
get EMWZ status

This is the same command which is scheduled every 5 minutes internally.

Attributes
• model (EM1000WZ)
• dummy
• IODev

ENECSYSGW

Module to access the ENECSYS gateway (http://www.ENECSYS.com/products/gateway/).

The actual micro-inverter devices are defined as ENECSYSINV devices.

All newly found inverter devices are autocreated and added to the room ENECSYSINV.

Define
define <name> ENECSYSGW [<host>] [<interval>]

Defines an ENECSYSGW device with address <host>.

The gateway will be polled every <interval> seconds. The default is 10 and minimum is 5.

Examples:
define gateway ENECSYSGW 10.0.1.1

ENECSYSINV

Define
define <name> ENECSYSINV <id> [<interval>]

Defines an micro-inverter device connected to an ENECSYSGW.

Examples:
define SolarPanel1 ENECSYSINV 100123456


Readings
• acfrequency
  the alternating current frequency reported from the device. Should be around 50 Hz in Europe.
• acpower
  the alternating current power
• acvolt
  the alternating current voltage
• dccurrent
  the direct current
• dcpower
  the direct current power
• dcvolt
  the direct current voltage
• efficiency
  the efficiency of the inverter
• lifetime
  the sum of collected energy of the inverter
• temperature
  the temperature of the inverter
• state
  the current state (equal to dcpower)

ENIGMA2

Define
define <name> ENIGMA2 <ip-address-or-hostname> [[[[<port>] [<poll-interval>]] [<http-user>]] [<http-password>]]

This module controls ENIGMA2 based devices like Dreambox or VUplus receiver via network connection.

Defining an ENIGMA2 device will schedule an internal task (interval can be set with optional parameter <poll-interval> in seconds, if not set, the value is 45 seconds), which periodically reads the status of the device and triggers notify/filelog commands.

Example:

define SATReceiver ENIGMA2 192.168.0.10

# With custom port
define SATReceiver ENIGMA2 192.168.0.10 8080

# With custom interval of 20 seconds
define SATReceiver ENIGMA2 192.168.0.10 80 20

# With HTTP user credentials
define SATReceiver ENIGMA2 192.168.0.10 80 20 root secret


Set
set <name> <command> [<parameter>]

Currently, the following commands are defined.

• on   -   powers on the device and send a WoL magic package if needed
• off   -   turns the device in standby mode
• toggle   -   switch between on and off
• shutdown   -   turns the device in deepstandby mode
• reboot   -  reboots the device
• restartGui   -  restarts the GUI / ENIGMA2 process
• channel channel,0...999,sRef   -   zap to specific channel or service reference
• channelUp   -   zap to next channel
• channelDown   -   zap to previous channel
• volume 0...100   -   set the volume level in percentage
• volumeUp   -   increases the volume level
• volumeDown   -   decreases the volume level
• mute on,off,toggle   -   controls volume mute
• play   -   starts/resumes playback
• pause   -   pauses current playback or enables timeshift
• stop   -   stops current playback
• record   -   starts recording of current channel
• input tv,radio   -   switches between tv and radio mode
• statusRequest   -   requests the current status of the device
• remoteControl UP,DOWN,...   -   sends remote control commands; see 'remoteControl ?' for full command list
  Note: You may add the word "long" after the command to simulate a long key press.
• showText text   -   sends info message to screen to be displayed for 8 seconds
• msg yesno,info...   -   allows more complex messages as showText, see commands as listed below
Note: If you would like to restrict access to admin set-commands (-> statusRequest, reboot, restartGui, shutdown) you may set your FHEMWEB instance's attribute allowedCommands like 'set,set-user'. The string 'set-user' will ensure only non-admin set-commands can be executed when accessing FHEM using this FHEMWEB instance.



Messaging


showText has predefined settings. If you would like to send more individual messages to your TV screen, the function msg can be used. For this application the following commands are available:

Type Selection:

msg yesno
msg info
msg message
msg attention



The following parameter are essentially needed after type specification:
msg <TYPE> <TIMEOUT> <YOUR MESSAGETEXT>



Get
get <name> <what>

Currently, the following commands are defined:


channel
currentMedia
currentTitle
mute
nextTitle
power
providername
servicevideosize
input
streamUrl
volume



Attributes

• bouquet-tv - service reference address where the favorite television bouquet can be found (initially set automatically during define)
• bouquet-radio - service reference address where the favorite radio bouquet can be found (initially set automatically during define)
• disable - Disable polling (true/false)
• http-method - HTTP access method to be used; e.g. a FritzBox might need to use POST instead of GET (GET/POST)
• http-noshutdown - Set FHEM-internal HttpUtils connection close behaviour (defaults=1)
• https - Access box via secure HTTP (true/false)
• ignoreState - Do not check for available device before sending commands to it (true/false)
• lightMode - reduces regular queries (resulting in less functionality), e.g. for low performance devices. (true/false)
• macaddr - manually set specific MAC address for device; overwrites value from reading "lanmac". (true/false)
• remotecontrol - Explicitly set specific remote control unit format. This will only be considered for set-command remoteControl as of now.
• remotecontrolChannel - Switch between remote control commands used for set-commands channelUp and channelDown.
• timeout - Set different polling timeout in seconds (default=6)
• wakeupCmd - Set a command to be executed when turning on an absent device. Can be an FHEM command or Perl command in {}. Available variables: ENIGMA2 device name -> $DEVICE, ENIGMA2 device MAC address -> $MACADDR (default=Wake-on-LAN)



Generated Readings/Events:

• acg - Shows Automatic Gain Control value in percent; reflects overall signal quality strength
• apid - Shows the audio process ID for current channel
• ber - Shows Bit Error Rate for current channel
• channel - Shows the service name of current channel or media file name; part of FHEM-4-AV-Devices compatibility
• currentMedia - The service reference ID of current channel; part of FHEM-4-AV-Devices compatibility
• currentTitle - Shows the title of the running event; part of FHEM-4-AV-Devices compatibility
• enigmaversion - Shows the installed version of ENIGMA2
• eventcurrenttime - Shows the current time of running event as UNIX timestamp
• eventcurrenttime_hr - Shows the current time of running event in human-readable format
• eventcurrenttime_next - Shows the current time of next event as UNIX timestamp
• eventcurrenttime_next_hr - Shows the current time of next event in human-readable format
• eventdescription - Shows the description of running event
• eventdescriptionextended - Shows the extended description of running event
• eventdescriptionextended_next - Shows the extended description of next event
• eventdescription_next - Shows the description of next event
• evenduration - Shows the total duration time of running event in seconds
• evenduration_hr - Shows the total duration time of running event in human-readable format
• evenduration_next - Shows the total duration time of next event in seconds
• evenduration_next_hr - Shows the total duration time of next event in human-readable format
• eventname - Shows the name of running event
• eventname_next - Shows the name of next event
• eventremaining - Shows the remaining duration time of running event in seconds
• eventremaining_hr - Shows the remaining duration time of running event in human-readable format
• eventremaining_next - Shows the remaining duration time of next event in seconds
• eventremaining_next_hr - Shows the remaining duration time of next event in human-readable format
• eventstart - Shows the starting time of running event as UNIX timestamp
• eventstart_hr - Shows the starting time of running event in human readable format
• eventstart_next - Shows the starting time of next event as UNIX timestamp
• eventstart_next_hr - Shows the starting time of next event in human readable format
• eventtitle - Shows the title of the running event
• eventtitle_next - Shows the title of the next event
• fpversion - Shows the firmware version for the front processor
• hddX_capacity - Shows the total capacity of the installed hard drive in GB
• hddX_free - Shows the free capacity of the installed hard drive in GB
• hddX_model - Shows hardware details for the installed hard drive
• imageversion - Shows the version for the installed software image
• input - Shows currently used input; part of FHEM-4-AV-Devices compatibility
• iswidescreen - Indicates widescreen format - 0=off 1=on
• lanmac - Shows the device MAC address
• model - Shows details about the device hardware
• mute - Reports the mute status of the device (can be "on" or "off")
• nextTitle - Shows the title of the next event; part of FHEM-4-AV-Devices compatibility
• onid - The ON ID
• pcrpid - The PCR process ID
• pmtpid - The PMT process ID
• power - Reports the power status of the device (can be "on" or "off")
• presence - Reports the presence status of the receiver (can be "absent" or "present"). In case of an absent device, control is basically limited to turn it on again. This will only work if the device supports Wake-On-LAN packages, otherwise command "on" will have no effect.
• providername - Service provider of current channel
• recordings - Number of active recordings
• recordingsX_name - name of active recording no. X
• recordingsX_servicename - servicename of active recording no. X
• recordings_next - Shows the time of next recording as UNIX timestamp
• recordings_next_hr - Shows the time of next recording as human-readable format
• recordings_next_counter - Shows the time until next recording starts in seconds
• recordings_next_counter_hr - Shows the time until next recording starts human-readable format
• recordings_next_name - name of next recording
• recordings_next_servicename - servicename of next recording
• recordings_error - counter for failed recordings in timerlist
• recordings_finished - counter for finished recordings in timerlist
• servicename - Name for current channel
• servicereference - The service reference ID of current channel
• servicevideosize - Video resolution for current channel
• sid - The S-ID
• snr - Shows Signal to Noise for current channel in percent
• snrdb - Shows Signal to Noise in dB
• state - Reports current power state and an absence of the device (can be "on", "off" or "absent")
• tsid - The TS ID
• tuner_X - Details about the used tuner hardware
• txtpid - The TXT process ID
• videoheight - Height of the video resolution for current channel
• videowidth - Width of the video resolution for current channel
• volume - Reports current volume level of the receiver in percentage values (between 0 and 100 %)
• vpid - The Video process ID
• webifversion - Type and version of the used web interface

EQ3BT

EQ3BT is used to control a EQ3 Bluetooth Smart Radiator Thermostat

Note: The bluez package is required to run this module. Please check if gatttool executable is available on your system.

Define
define <name> EQ3BT <mac address>

Example:
define livingroom.thermostat EQ3BT 00:33:44:33:22:11


Set
set <name> <command> [<parameter>]
The following commands are defined:


• desiredTemperature [4.5...29.5]   -   set the temperature
• boost on/off   -   activate boost command
• mode manual/automatic   -   set manual/automatic mode
• updateStatus   -   read current thermostat state and update readings
• eco   -   set eco temperature
• comfort   -   set comfort temperature


Get
n/a

attr
• sshHost - FQD-Name or IP of ssh remote system / you must configure your ssh system for certificate authentication. For better handling you can config ssh Client with .ssh/config file

ESA2000

The ESA2000 module interprets ESA1000 or ESA2000 type of messages received by the CUL.

Define
define <name> ESA2000 <code> [base1 base2]

<code> is the 4 digit HEX code identifying the devices.

base1/2 is added to the total kwh as a base (Hoch- und Niedertarifzählerstand).

Set
N/A

Get
N/A

Attributes
• ignore


• do_not_notify


• showtime


• model (esa2000-led, esa2000-wz, esa2000-s0, esa1000wz-ir, esa1000wz-s0, esa1000wz-led, esa1000gas)


• IODev


• readingFnAttributes

ESCVP21net

ESCVP21net implements Epson VP21 control via (W)LAN, uses VP.net.
Attention: To be able to switch the projector power on via (W)LAN, you have to enable wireless/LAN standby mode (or whatever it is called in your projector menu), so that the projector does NOT deactivate the (W)LAN in standby mode!

Define
define <name> ESCVP21net <IP_Address> [<port>] [<model>]

This module controls Epson Seiko Devices via TCP, using VP.net and ESC/VP21 commands.
For the time being, only Epson initilization is implemented (needs a special initialization string "ESC/VP.net").


• IP_Address - the IP Address of the projector
• port - ... guess? Yes, the port. If not given, Epson standard port 3629 is used.
• model - defines your type of projector. It is used for loading a suitable pre-defined command set.
  No parameter or default will provide you with a limit "set" (PWR, MUTE, LAMP, KEY, GetAll, GetStatus).
  You can try TW5650 to get a typical set of implemented commands. Providing the maintainer with a suitable set for your projector will extend the module's capabilities ;-)
  Individually supported by now: TW5650, EB2250U, TW6100, TW7400, TW9400, LS12000, HC2150
  "Hidden Feature:" Type Scotty will give you everything (as he does always ;) ). Not every command will work for you. You are the Captain, so decide wisely what to choose...
• Example: define EPSON ESCVP21net 10.10.0.1 3629 TW5650


The first Define (or defmod) will configure
• a standard icon (it will use "it_camera", since I am not really a good designer)
• webCmds for on, off, GetStatus, GetAll
• cmdIcons for the webCmds
• stateFormat as PWR

Set


Available set commands depend on your model, see above.
For the predefined commands, "nice" names will be shown in the readings, e.g. for PWR: Standby (Net on) instead of the boring PWR=04 (which is the device's answer if the projector is in Standby with LAN on).
Default set commands are


• GetAll
  This is a little bit special - it does not send just one command to the projector, but will select every command defined which has a get option, send it to the projector and update the corresponding reading. If a command gives no result or an error, this will be suppressed, the old value is silently kept.
  The status of GetAll is shown in the GetAll reading. It will either show the read commands, or inform if an error was received.


• GetStatus
  Also special - also does not send just one command to the projector, but will select every command you defined in attr "statusCheckCmd" which has a get option, send it to the projector and update the corresponding reading. If a command gives no result or an error, this will be suppressed, the old value is silently kept.
  The status of GetStatus is shown in the GetStatus reading. It will either show the read commands, or inform if an error was received.


• LAMP
  get to query lamp hours.


• MUTE
  on or off to mute video signal (i.e. blank screen), get to query current state.


• KEY
  sends the value you enter to the projector.
  E.g.KEY 03 or KEY 3C should open the OSD menu, KEY 05 or or KEY 3D should close it.
  Feel free to define your own KEY sets via the attribute "AdditionalSettings".


• PWR
  on or off to switch power, get to query current value.
  (due to projector timeout on PWR, status reading update after issuing on/off will be delayed by ca 12s)


• on
  Hm, what could that mean ... OK, shortcut to switch your projector on - give it a try!
  (due to projector timeout on PWR, status reading update will be delayed by ca 12s)


• off
  Wohoo ... want to switch it off again? Then use this command.
  (due to projector timeout on PWR, status reading update will be delayed by ca 12s)


• ASPECT
  set/get aspect ratio. Values depend on your model.


• AUTOHOME
  set/get auto display of home screen.


• AUTOKEYSTONE
  set/get auto keystone correction.


• BRIGHT
  get brightness value.


• BRIGHTset
  Set brightness value.


• BTAUDIO
  set/get bluetooth audio (on/off).


• CMODE
  set/get color mode.


• CONTRAST
  get contrast enhancement value.


• CONTRASTset
  set contrast enhancement value.


• DENSITY
  get density value.


• DENSITYset
  set density value.


• ERASEMEM
  Erase picture setting memory slot (1...10), related to PUSHMEM, POPMEM.


• GAMMA
  set/get gamma value (-2...2)


• HREVERSE
  set/get horizontal reverse setting.


• ILLUM
  set/get illumination setting of on-device control lights.


• IMGPROC
  undocumented setting for image processing (fine/fast). Might not be available on some devices.


• IRIS
  undocumented setting for iris setting. Might not be available on some devices.


• LIRIS
  undocumented setting for L-iris setting (whatever that means...). Might not be available on some devices.


• LUMINANCE
  set/get luminance setting (high/low).


• MCFI
  set/get frame interpolation setting.


• MSEL
  set/get background color for A/V mute screen.


• OVSCAN
  set/get overscan ratio.


• POPMEM
  restore image setting from memory slot (1...10), related to PUSHMEM, ERASEMEM.


• PUSHMEM
  save current image setting to memory slot (1...10), related to POPMEM, ERASEMEM.


• PWSTATUS
  undocumented. Gets pwer status (see PWR).


• SHARP
  get sharpness value.


• SHARPset
  set sharpness value.


• SIGNAL
  set/get signal state (e.g 2D/3D).


• SNO
  get serial number of device.


• SOURCE
  set/get current source of video input.


• TINT
  get tint value.


• TINTset
  set tint value.


• VOL
  get volume setting. Normally a multiple of 12 (whyever...).


• VOLset
  set volume. Range is 1...20, since epson wants a multiple of 12 to be set (whyever...).


• VREVERSE
  set/get vertical reverse setting.



The following commands are only available if debug is set to 1. They are not meant for normal operation.
Use at your own risk, might crash fhem if used in the "wrong" situation.
But stay calm - restart always helps (at least I hope so...)


• cleanup
  debug option. Deletes timers, closes connection, kills nonblocking function. Handle with care!


• closeDevice
  debug option. Closes connection to device.


• connect
  debug option. Closes active connection to device and forces reconnect.


• decode
  debug option. Decodes stored json values for set.


• deleteNextOpen
  debug option. Deletes timer for next device open command.


• encode
  debug option. Force new json encoding of set values.


• isOpen
  debug option. Query if connection to device is open and logs result in logfile (verbose 5 required).


• openDevice
  debug option. Force new connection to device. Handle with care.


• reRead
  debug option. Force update of set commands, useful if you changed e.g "AdditionalSettings".


• removeTimer
  debug option. Removes all timers for connection check.



Attributes

• AdditionalSettings
  cmd1:val_1,...,val_n cmd2:val_1,...,val_n
  You can specify own set commands here, they will be added to the set list.
  Multiple own sets can be specified, separated by a blank.
  command and values are separated by ":", values are separated by ",".
  Example: ASPECT:get,10,20,30 SN:noArg
  Each command with get will we queried when unsing set <name> GetAll
  Might need a restart to be recognized, or use "reRead" setting.


• Manufacturer
  Epson|default - is not used currently.


• PwrQueryDelay
  (value in seconds)
  After setting PWR on/off, the projector needs some timeout before an PWR status query ("PWR get") can be sent.
  value defines the intervall in seconds to wait.
  The perfect moment for a query depends (as many things in life do...), in this case on your projector.
  I strongly recommend to use a value greater than 10 seconds to avoid race conditions. Lower values might work ... might. Feel free to test, but don't blame the module if you experience nice crashes.
  Default value is 12 seconds.


• connectionCheck
  off|(value in seconds)
  value defines the intervall in seconds to perform an connection check. This is useful, since the standard connection handling of fhem (DevIo) will not detect an broken TCP connection, so the state disconnected will only trigger after TCP timeout (60-90 minutes). If you are ok with this, just set it to off.
  Default value is 60 seconds.


• cyclicConnect
  off|(value in seconds)
  value defines the intervall in seconds to perform an periodic reconnect. Each interval we try to re-open the TCP connectionto the projector. Implemented to work around DevIo not recognizing a server-side broken connection, which can lead to a unnecessary, however non-blocking, system load.
  Default value is 3600 seconds.


• debug
  You won't need it. But ok, if you insist...
  debug will reveal some more set commands, namely encode, decode, reread. They will store the currents sets and results in json format to hidden readings (encode) or restore them (decode). reread will just restore the available set commands for your projector type in case they got "lost". Don't use the other debug commands - unnless you know what you do...
  Default is 0, of course.


• statusCheckCmd
  (any command(s) you set)
  Defines the command(s) used by statusCheckInterval. Multiple commands can specified, e.g. PWR LAMP. Default: PWR to get power status. Please pay also attention to the helpful remarks at "statusCheckInterval".
  Wrong commands or commands without a get will be ignored.


• statusCheckInterval
  off|(value in seconds)
  value defines the intervall in seconds to perform an status check. Each interval the projector is queried with the command defined by statusCheckCmd (default: PWR to get power status).
  Attention: statusCheck is disabled - i.e. will NOT be done - when the projector is detected to be offline / unreachable. It does not make sense to poll an unreachable projector, doesn't it? If you want to query your projector regularly regardlessly, use the magic "cyclicConnect" attribute. Setting this will query the projector in the intervall you define, and update the settings "PWR" and "statusP" accordingly. This will e.g. help you to show "off" as status when the projector power was shut off outside fhem (who the hell wants to do that if you can do it infhem? Anyway...) instead of only standby (shutting power of, btw, is what I recommend, since it saves power, money and the environment)
  Default value is 60 seconds.


• statusOfflineMsg
  (any message text you set)
  Defines the message to set in the Reading related to statusCheckCmd when the device goes offline. Status of device will be checked after each statusCheckInterval (default: 60s), querying the statusCheckCmd command (default: PWR), and if STATE is disconnected the Reading of statusCheckCmd will be set to this message. Default: offline.


• statusPOfflineMsg
  (any message text you set)
  The "P" makes the difference here ... Defines the message to set in "statusP" when the device is offline or unreachable. Status of device will be checked after each statusCheckInterval (default: 60s), querying the statusCheckCmd command (default: PWR), and if STATE is disconnected the Reading "statusP" will be set to this message. Default: off.

ESPEInk

ESPEInk This module implements the possibility to send pictures generated in FHEM to an raw eInk paper connected to an ESP8266 or ESP32 eInk WLAN driver board from waveshare (see details about the board at Wiki ESP8266 Waveshare Driver Board and Wiki ESP32 Waveshare Driver Board).
The module consists of 2 parts. One is the preparation of the picture to be send to the board. Here a template picture can be defined and additional texts can be added. Furthermore it can be specified how the conversion should be done (e.g. if size of template picture should be automatically fit to eInk size, dithering, color mode or monochrome) The second part converts the picture to the right format and sends it to the board and thus changes the display on the eInk paper.

Prerequisites

This module requires an eInk paper raw module from Waveshare (exisiting in different sizes, number of colors and resolutions) and a WLAN driver board (Wiki Waveshare Driver Board). The driver board needs the installation of an adruino sketch as described in the Wiki (see link before). After this the module together with the eInk display only needs power supply. The data exchange between FHEM and the display is done via WLAN. The module further needs installation of the GD library for perl (see installation instructions at GD for Perl and at Image::LibRSVG for Perl).

Define
define <name> ESPEInk <picturefile> [url] [interval] [colormode] [convertmode]

Example: define myEInk ESPEInk /opt/fhem/www/images/test.png

The picturefile parameter must be path to a readable file in the filesystem of FHEM.
[url] is the url of the WLAN driver board (typically an IP address but could also be a Web-URL). This parameter is optional but needed as soon as you want to not only generate the picture but also upload it to the eInk display. For upload it is also necessary to specify the correct device type (default is 1.54inch_e-Paper_Module see also attribute devicetype, for a list of all available device types use get devices).
[interval] is a time interval for regular updates of the information to the eInk display. It automatically converts the inputs and uploads the result to the eInk display and defaults to 300 seconds.
[colormode] can be either color or monochrome and specifies if the inputs should be converted to a fitting color picture or if the conversion should be done in monochrome format.
[convertmode] can be either level or dithering. If level is specified, the conversion transforms the given colors to the ones to the closest color the display is capable of (depending on the display type this can be black, red or yellow). When dithering is specified, the conversion performs a Floyd Steinberg dithering to fit the input picture better to the capabilities of the eInk display.

Set

set <name> <option> <value>

Options:
• addtext
  This option allows to specify a text that should be added to the template picture at any position.
  The value must be given in the form: text#x#y#size#angle#color#font#linegap#blockwidth
  where:
  text is the text that should be added. This is the only mandatory part of the value.
  x is the x-position of the lower left corner of the text relative to the lower left corner of the display area
  y is the y-position of the lower left corner of the text relative to the lower left corner of the display area
  size is the size of the text in pixels. This parameter is only used if a TTF font type is specified (see below)
  angle is the rotation angle (counterclockwise) that should be used when drawing the text. In case of not using TTF fonts (see below), the resulting rotation can be only 0 or 90 degrees.
  color is an RGB hex string that specifies the RGB values of the color respectively (e.g. 00FF00 for green)
  font is either one of small medium large giant or a path to a valid TTF font file in the FHEM file system.
  linegap The distance between consecutive lines if blocksetting is used (see blockwidth below) positive values increase the distance negative values reduce the distance.
  blockwidth The width in pixels of the text block generated by the text string. If the string width on the display is higher than the given width in pixels, an automatic linebreak will be added.
  For each of the specified texts a list of readings and attributes is added to the device. The readings are holding the parameters finally taken for the generation of the output picture. The attributes allow an easy change of the readings (see details in the description below). Once at least one text is specified, the set option removeobject is added.
  
• addicon
  This option allows to specify an icon that should be added to the template picture at any position.
  The value must be given in the form: icon#x#y#size#angle#color
  where:
  icon is the name of the icon that should be added. This is the only mandatory part of the value. Icons can either be specified as fhem icon names (any installed fhem icons are supported), or as url links to web icons
  x is the x-position of the lower left corner of the icon relative to the lower left corner of the display area
  y is the y-position of the lower left corner of the icon relative to the lower left corner of the display area
  size is the size of the icon in pixels. This parameter is only used if a TTF font type is specified (see below)
  angle is the rotation angle (counterclockwise) that should be used when drawing the icon. In case of not using TTF fonts (see below), the resulting rotation can be only 0 or 90 degrees.
  color is an RGB hex string that specifies the RGB values of the color respectively (e.g. 00FF00 for green)
  For each of the specified icons a list of readings and attributes is added to the device. The readings are holding the parameters finally taken for the generation of the output picture. The attributes allow an easy change of the readings (see details in the description below). Once at least one icon is specified, the set option removeobject is added.
  
• addsymbol
  This option allows to specify an symbols (lines, ellipses, rectangles, arcs) that should be added to the template picture at any position.
  The value must be given in the form: symbol#x#y#thickness#angle#color#width#height#segment
  where:
  symbol is specifying which symbol should be drawn. Possible values are line or rectangle or ellipse or arc. If -filled is added, the symbol is filled, if -dotted or -dashed is added, the line is drawn dotted or dashed. For example a symbol value given as 'line-dotted' will draw a dotted line, 'rectangle-filled' will draw a filled rectangle.
  x is the x-position of the lower left corner of the symbol relative to the lower left corner of the display area
  y is the y-position of the lower left corner of the symbol relative to the lower left corner of the display area
  thickness is the thickness of lines or outlines of the symbols drawn.
  angle is the rotation angle (counterclockwise) that should be used when drawing the symbol.
  color is an RGB hex string that specifies the RGB values of the color respectively (e.g. 00FF00 for green)
  width is the width of the symbol (in case of lines, the line is drawn width pixels in x direction and height pixels in y direction).
  height is the width of the symbol (in case of lines, the line is drawn width pixels in x direction and height pixels in y direction).
  segment is only used for arc type symbols. In this case angle (see above) specifies the start of the arc and segment specifices the width of the arc.
  For each of the specified symbols a list of readings and attributes is added to the device. The readings are holding the parameters finally taken for the generation of the output picture. The attributes allow an easy change of the readings (see details in the description below). Once at least one symbol is specified, the set option removeobject is added.
  
• textreading
  This option allows to specify a device:reading as trigger for adding texts to the template picture at any position.
  The value must be given in the form: device:reading#x#y#size#angle#color#font#linegap#blockwidth
  where:
  device:reading specifies a device (and potentially a reading otherwise state will be taken as reading) that should contain the text. This is the only mandatory part of the value. When the internal parameter INTERVAL ist set to 0 (at definition time or through the attribute interval) the change of the reading will directly trigger an update of the result picture and an upload to the device.
  x is the x-position of the lower left corner of the text relative to the lower left corner of the display area
  y is the y-position of the lower left corner of the text relative to the lower left corner of the display area
  size is the size of the text in pixels. This parameter is only used if a TTF font type is specified (see below)
  angle is the rotation angle (counterclockwise) that should be used when drawing the text. In case of not using TTF fonts (see below), the resulting rotation can be only 0 or 90 degrees.
  color is an RGB hex string that specifies the RGB values of the color respectively (e.g. 00FF00 for green)
  font is either one of small medium large giant or a path to a valid TTF font file in the FHEM file system.
  linegap The distance between consecutive lines if blocksetting is used (see blockwidth below) positive values increase the distance negative values reduce the distance.
  blockwidth The width in pixels of the text block generated by the text string. If the string width on the display is higher than the given width in pixels, an automatic linebreak will be added.
  For each of the specified texts a list of readings and attributes is added to the device. The readings are holding the parameters finally taken for the generation of the output picture. The attributes allow an easy change of the readings (see details in the description below). Once at least one text is specified, the set option removeobject is added.
• iconreading
  This option allows to specify a device:reading as trigger for adding icons to the template picture at any position.
  The value must be given in the form: device:reading#x#y#size#angle#color
  where:
  device:reading specifies a device (and potentially a reading otherwise state will be taken as reading) that should contain the icons names (see possible icon names at "addicon" option). This is the only mandatory part of the value. When the internal parameter INTERVAL ist set to 0 (at definition time or through the attribute interval) the change of the reading will directly trigger an update of the result picture and an upload to the device.
  x is the x-position of the lower left corner of the icon relative to the lower left corner of the display area
  y is the y-position of the lower left corner of the icon relative to the lower left corner of the display area
  size is the size of the icon in pixels. This parameter is only used if a TTF font type is specified (see below)
  angle is the rotation angle (counterclockwise) that should be used when drawing the icon. In case of not using TTF fonts (see below), the resulting rotation can be only 0 or 90 degrees.
  color is an RGB hex string that specifies the RGB values of the color respectively (e.g. 00FF00 for green)
  font is either one of small medium large giant or a path to a valid TTF font file in the FHEM file system.
  For each of the specified icons a list of readings and attributes is added to the device. The readings are holding the parameters finally taken for the generation of the output picture. The attributes allow an easy change of the readings (see details in the description below). Once at least one icon is specified, the set option removeobject is added.
• convert
  With this option the conversion can be triggered. Whenever a conversion is triggered, the resulting picture is added as reading result_picture to the device (or an existing reading is changed). Conversion is done "non-blocking" in the backround so that FHEM remains accessible.
• removeobject
  With this option existing text definitions can be removed. The value for this option is a comma separated list of integer numbers refering to the index of the respective texts to be deleted. This option is only available if at least one text has been added to the device with set addtext or set addicon.
• opload
  Uploads the current version of the result picture (result from most recent conversion step) to the eInk display device for display.

Get

get <name> <option>

Currently the only supported get option is get devices. This will display a list of all available device types in a popup window. the get command.

Readings
The following readings are generated by the module:

Readings:
• source_picture
  Displays the given picture template specified at the definition of a device or given by attribute picturefile.
• result_picture
  Displays the result of the most recent conversion once set convert has been issued the first time.
• deftexts
  The number of text attributes defined to be added to the template picture when doing the conversion.
• [0-n]-text
  The text specified for a given text object. [0-n] is an integer number and refers to the index of the text.
• [0-n]-icon
  The icon specified for a given icon object. [0-n] is an integer number and refers to the index of the icon.
• [0-n]-x
  The x-position of the lower left corner of the text relative to the lower left corner of the display area.
• [0-n]-y
  The y-position of the lower left corner of the text relative to the lower left corner of the display area.
• [0-n]-size
  The size of the text in pixels. This parameter is only used if a TTF font type is specified (see below).
• [0-n]-angle
  The rotation angle (degrees counterclockwise) that will be used when drawing the text. In case of not using TTF fonts (see below), the resulting rotation can be only 0 or 90 degrees.
• [0-n]-color
  An RGB hex string that tells the respective RGB values of the color used for displaying the text (e.g. 00FF00 for green).
• [0-n]-font
  Either one of small medium large giant or a path to a valid TTF font file in the FHEM file system specifying the font to be used when displaying the text.
• [0-n]-linegap
  The distance between consecutive lines if blocksetting is used (see blockwidth below) positive values increase the distance negative values reduce the distance
• [0-n]-blockwidth
  The width in pixels of the text block generated by the text string. If the string width on the display is higher than the given width in pixels, an automatic linebreak will be added
• [0-n]-trigger
  The triggering condition of the object if the object is related to areading (see set textreading and set iconreading).
• [0-n]-def
  The initial definition of the object. This is used to reset to inital settings for color, font etc. when attributes are removed.
• [0-n]-isIcon
  Internal setting for marking entry as icon or text.

Attributes
attr <name> <attribute> <value>

See commandref#attr for more info about the attr command. In addition to the standard attributes the following device specific attributes are existing.

Attributes:
• picturefile
  Set the picture template. This parameter must be a path to a readable file in the filesystem of FHEM
• url
  The url of the WLAN driver board the eInk display is connected to (typically an IP address but could also be a Web-URL)
• definition
  This is an alternative to using the set addtext/addicon/addsymbol/textreadin/iconreading command. The attribute contains a list of defintions separated by newline. The syntax of the defintion is the same as in the reading [0-n]-def. It contains the command (addtext or addicon or addsymbol or textreading or iconreading) followed by '#' and then the same defintion values as statet in set (addtext ...) above. Lines starting with a # are ignored and treated as comment lines. Example: addtext#Hello#10#10#12#0#000000#giant
• definitionFile
  This is another alternative to using the set addtext/addicon/addsymbol/textreadin/iconreading command. The attribute holdes the name of a text file containing a list of defintions separated by newline. The syntax of the defintion is the same as in the reading [0-n]-def. It contains the command (addtext or addicon or addsymbol or textreading or iconreading) followed by '#' and then the same defintion values as statet in set (addtext ...) above. Lines starting with a # are ignored and treated as comment lines. Example: addtext#Hello#10#10#12#0#000000#giant
• interval
  The time interval for regular updates of the information to the eInk display. The device automatically converts the inputs and uploads the result to the eInk display in this interval. If this value is set to 0 there will be automatical updates in case a triggering device is specified (see set textreading). Otherwise 0 means no automatic updates.
• mininterval
  The time interval that shall at least be elapsed since the last upload. If the interval since last upload is smaller than this value, not uploads will be performed.
• boardtype
  The type of driver board to be used. Currently ESP8266 and ESP32 driver boards are supported.
• devicetype
  The device type to be used. Refer to get devices for a list of available devices.
• colomode
  Can be either color or monochrome and specifies if the inputs should be converted to a fitting color picture or if the conversion should be done in monochrome format.
• convertmode
  Can be either level or dithering. If level is specified, the conversion transforms the given colors to the ones to the closest color the display is capable of (depending on the display type this can be black, red or yellow). When dithering is specified, the conversion performs a Floyd Steinberg dithering to fit the input picture better to the capabilities of the eInk display.
• width
  The width of the result picture. Is normally taken from the devicetype default settings. Should be only used for non predefined devices.
• height
  The height of the result picture. Is normally taken from the devicetype default settings. Should be only used for non predefined devices.
• x0
  An x-offset for the placement of the source picture into the result picture during conversion. Reference is the lower left corner of the result.
• y0
  An y-offset for the placement of the source picture into the result picture during conversion. Reference is the lower left corner of the result.
• placement
  Tells the conversion algorithm where to place the source picture in the result picture if there are different widths and heights. Can be one of top-left top-right bottom-left bottom-right.
• scale2fit
  If set to 1 the source picture is scaled to fit into the result picture in x and y directions.
• coloroffset
  Provides a possibility for changing the mapping of source colors to result colors. Given in the form r;g;b.
• maxretries
  Set the maximum number of retries for sending data to the WLAN display driver of the eInk display. Whenever the sending of a certain data package is not successful, sending is repeated until succes or number of maxretries is reached. Default is 3.

The following attributes are only available for the defined text objects to be added to the result picture. There is one set of attributes for each defined texts starting with the respective text index before the -


• [0-n]-text
  The text specified for a given text object. [0-n] is an integer number and refers to the index of the text.
• [0-n]-icon
  The icon name or url specified for a given icon object. [0-n] is an integer number and refers to the index of the text.
• [0-n]-x
  The x-position of the lower left corner of the text relative to the lower left corner of the display area.
• [0-n]-y
  The y-position of the lower left corner of the text relative to the lower left corner of the display area.
• [0-n]-size
  The size of the text in pixels. This parameter is only used if a TTF font type is specified (see below).
• [0-n]-angle
  The rotation angle (degrees counterclockwise) that will be used when drawing the text. In case of not using TTF fonts (see below), the resulting rotation can be only 0 or 90 degrees.
• [0-n]-color
  An RGB hex string that tells the respective RGB values of the color used for displaying the text (e.g. 00FF00 for green).
• [0-n]-font
  Either one of small medium large giant or a path to a valid TTF font file in the FHEM file system specifying the font to be used when displaying the text.
• [0-n]-linegap
  The distance between consecutive lines if blocksetting is used (see blockwidth below) positive values increase the distance negative values reduce the distance
• [0-n]-blockwidth
  The width in pixels of the text block generated by the text string. If the string width on the display is higher than the given width in pixels, an automatic linebreak will be added

ESPEasy

Provides access and control to Espressif ESP8266/ESP32 WLAN-SoC w/ ESPEasy

Notes:
• You have to define a bridge device before any logical device can be (automatically) defined.
• You have to configure your ESP to use "FHEM HTTP" controller protocol. Furthermore ESP Easy controller IP must match FHEM's IP address. ESP controller port and the FHEM ESPEasy bridge port must be the same.
• Max. 2 ESPEasy bridges can be defined in the same FHEM instance: 1 for IPv4 and 1 for IPv6
• Further information about this module is available here: Forum #55728 or in this wiki article.
• For security reasons: if one or more of your ESPEasy device uses a public IP address then you have to enable this explicitly or the device(s) will be ignored/rejected:
• Enable all ESPEasy device IP addresses/subnets/regexs with the help of bridge attributes allowedIPs / deniedIPs.
• Enable authentication: see attribute authentication and bridge set user / pass commands.


Requirements:
• ESPEasy build >= R128 (self compiled) or an ESPEasy precompiled image >= R140_RC3
  
• ESPEasy Mega with option to set sleep awake time (Config -> Sleep Mode -> Sleep awake time) is required to control ESP Easy nodes in deep sleep. Receiving sensor values works with all other supported versions.
  
• Perl module JSON. Use "cpan install JSON" or operating system's package manager to install Perl JSON Modul. Depending on your os the required package is named: libjson-perl or perl-JSON.

ESPEasy Bridge

Define (bridge)


define <name> ESPEasy bridge <[IPV6:]port>


• <name>
  Specifies a device name of your choise.
  example: ESPBridge


• <port>
  Specifies TCP port for incoming ESPEasy http requests. This port must not be used by any other application or daemon on your system and must be in the range 1024..65535 unless you run your FHEM installation with root permissions (not recommanded).
  If you want to define an IPv4 and an IPv6 bridge on the same TCP port (recommanded) then it might be necessary on (some?) Linux distributions to activate IPV6_V6ONLY socket option. Use "echo 1>/proc/sys/net/ipv6/bindv6only" or systemctl for that purpose.
  eg. 8383
  eg. IPV6:8383
  Example:
  define ESPBridge ESPEasy bridge 8383



Get (bridge)


• <reading>
  returns the value of the specified reading


• queueSize
  returns number of entries for currently used queue.


• queueContent
  returns queues content.
  • arguments: IP address (can be a regex or omitted to display all queues)


• user
  returns username used by basic authentication for incoming requests.


• pass
  returns password used by basic authentication for incoming requests.



Set (bridge)


• active
  Activates the current device if it was set inactive before. Set active/inactive will be mostly used in scripts without the side effect that the 'red question mark' will be displayed in FHEMWEB that indicates unsaved configuration changes. If attribute disabled is enabled (set to '1') then this set command will be ignored.


• inactive
  Opposite of set command activate


• clearQueue
  Used to erase all command queues.
  required value: <none>
  eg. : set ESPBridge clearQueue


• help
  Shows set command usage
  required values: help|pass|user|clearQueue


• pass
  Specifies password used by basic authentication for incoming requests.
  Note that attribute authentication must be set to enable basic authentication, too.
  required value: <password>
  eg. : set ESPBridge pass secretpass


• reopen
  Reopen TCP/IP server port for incoming connections from ESPs.


• user
  Specifies username used by basic authentication for incoming requests.
  Note that attribute authentication must be set to enable basic authentication, too.
  required value: <username>
  eg. : set ESPBridge user itsme



Attributes (bridge)


• allowedIPs
  Used to limit IPs or IP ranges of ESPs which are allowed to commit data.
  Specify IP, IP/netmask, regexp or a comma separated list of these values. Netmask can be written as bitmask or dotted decimal. Domain names for dns lookups are not supported.
  Possible values: IPv64 address, IPv64/netmask, regexp
  Default: 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fe80::/10, fc00::/7, ::1
  
  Examles:
  

  10.68.30.147	=> IPv4 single address
  10.68.30.0/25	=> IPv4 CIDR network 192.168.30.0-127
  10.68.30.8/255.255.248.0	=> IPv4 CIDR network 192.168.30.8-15
  192.168.30.1([0-4][0-9]|50)	=> IPv4 range w/ regexp: 192.168.30.100-150
  2001:1a59:50a9::aaaa	=> IPv6 single address
  2001:1a59:50a9::/48	=> IPv6 network 2001:1a59:50a9::/48
  2001:1a59:50a9::01[0-4][0-9]	=> IPv6 range w/ regexp: 2001:1a59:50a9::0100-0149

  Note that short IPv6 notation (::) must be used in conjunction with regexps.


• authentication
  Used to enable basic authentication for incoming requests.
  Note that user, pass and authentication attribute must be set to activate basic authentication
  Possible values: 0,1
  Default: 0


• autocreate
  Used to overwrite global autocreate setting.
  Global autocreate setting will be detected by global attribut 'autoload_undefined_devices'
  Possible values: 0,1
  Default: 0 (disabled)


• autosave
  Used to overwrite global autosave setting.
  Global autosave setting will be detected by global attribut 'autosave'.
  Possible values: 0,1
  Default: 0 (disabled)


• combineDevices
  Used to gather all ESP devices of a single ESP into 1 FHEM device even if different ESP devices names are used.
  Possible values: 0, 1, IPv64 address, IPv64/netmask, ESPname or a comma separated list consisting of these values.
  Netmasks can be written as bitmask or dotted decimal. Domain names for dns lookups are not supported.
  Default: 0 (disabled for all ESPs)
  Eg. 1 (globally enabled)
  Eg. ESP01,ESP02
  Eg. 10.68.30.1,10.69.0.0/16,ESP01,2002:1a59:50a9::/48


• deniedIPs
  Used to define IPs or IP ranges of ESPs which are denied to commit data.
  Syntax see allowedIPs.
  This attribute will overwrite any IP or range defined by allowedIPs.
  Default: none (no IPs are denied)


• disable
  Used to disable device. inactive state will be overwritten.
  Possible values: 0,1
  Default: 0 (eanble)


• httpReqTimeout
  Specifies seconds to wait for a http answer from ESP8266 device.
  Possible values: 4..60
  Default: 10 seconds


• maxHttpSessions
  Limit maximal concurrent outgoing http sessions to a single ESP.
  Set to 0 to disable this feature. At the moment (ESPEasy R147) it seems to be possible to send 5 "concurrent" requests if nothing else keeps the esp working.
  Possible values: 0..9
  Default: 3


• maxQueueSize
  Limit maximal queue size (number of commands in queue) for outgoing http requests.
  If command queue size is reached (eg. ESP is offline) any further command will be ignored and discard.
  Possible values: >10
  Default: 250


• resendFailedCmd
  Used to define number of command resends to the ESP if there is an error in transmission on network layer (eg. unreachable wifi device).
  Possible values: a positive number
  Default: 0 (disabled: no resending of commands)


• uniqIDs
  This attribute has been removed.


• readingFnAttributes



ESPEasy Device

Define (logical device)


Note 1: Logical devices will be created automatically if any values are received by the bridge device and autocreate is not disabled. If you configured your ESP in a way that no data is send independently then you have to define logical devices. At least wifi rssi value could be defined to use autocreate and presence detection.

define <name> ESPEasy <ip|fqdn> <port> <IODev> <identifier>


• <name>
  Specifies a device name of your choise.
  example: ESPxx


• <ip|fqdn>
  Specifies ESP IP address or hostname.
  example: 172.16.4.100
  example: espxx.your.domain.net


• <port>
  Specifies http port to be used for outgoing request to your ESP. Should be 80
  example: 80


• <IODev>
  Specifies your ESP bridge device. See above.
  example: ESPBridge


• <identifier>
  Specifies an identifier that will bind your ESP to this device.
  This identifier must be specified in this form:
  <esp name>_<esp device name>.
  If bridge attribute combineDevices is used then <esp name> is used, only.
  ESP name and device name can be found here:
  <esp name>: => ESP GUI => Config => Main Settings => Name
  <esp device name>: => ESP GUI => Devices => Edit => Task Settings => Name
  example: ESPxx_DHT22
  example: ESPxx


• Example:
  define ESPxx ESPEasy 172.16.4.100 80 ESPBridge EspXX_SensorXX



Get (logical device)


• adminPassword
  returns the admin password. For details see set adminPassword


• pinMap
  returns possible alternative pin names that can be used in commands


• setCmds
  returns formatted table of registered ESP commands/mappings.



Set (logical device)


Notes:
- Commands are case insensitive.
- Users of Wemos D1 mini or NodeMCU can use Arduino pin names instead of GPIO numbers.
  D1 => GPIO5, D2 => GPIO4, ...,TX => GPIO1 (see: get pinMap)
- low/high state can be written as 0/1 or on/off

ESPEasy module internal commands:


• active
  Works in the same way as bridge set command active.


• inactive
  Works in the same way as bridge set command inactive.


• adminPassword
  The ESP Easy 'Admin Password" is used to protect some ESP Easy commands against unauthorized access. When this feature is enabled on your ESPs you should deposit this password. If an ESP Easy command will require this authorization the password will be sent to the ESP. Keep in mind that this feature works quite slow on your ESP Easy nodes.


• attrTemplate
  See global attrTemplate. Attribute useSetExtensions must be activated or the command is unavailable.


• clearReadings
  Delete all readings that are auto created by received sensor values since last FHEM restart.
  
  • arguments: none
  • example: set <esp> clearReadings


• help
  Shows set command usage.
  
  • arguments: <a valid set command>
  • example: set <esp> help gpio


• raw
  Can be used for own ESP plugins or new ESPEasy commands that are not considered by this module at the moment. Any argument will be sent directly to the ESP. Used URL is: "/control?cmd="
  • arguments: raw <cmd> [<arg1>] [<arg2>] [<...>]
  • example: set <esp> raw myCommand p1 p2 p3


• rawsystem
  The same as set command raw but this command uses the URL "/?cmd=" (command.ino) instead of "/control?cmd=" (ESPEasy plugins).


• statusRequest
  Trigger a statusRequest for configured GPIOs (see attribut pollGPIOs) and do a presence check
  
  • arguments: n/a
  • example: set <esp> statusRequest
  
  

Note: The following commands are built-in ESPEasy Software commands that are send directly to the ESP after passing a syntax check and more... A detailed description can be found here: ESPEasy Command Reference

ESP Easy generic I/O commands:


• GPIO
  Switch output pins to high/low
  
  • arguments: <pin> <0|1|off|on>
  • example: set <esp> gpio 14 on


• PWM
  Direct PWM control of output pins
  
  • arguments: <pin> <level>
  • example: set <esp> pwm 14 512


• PWMFADE
  Fade output pins to a pwm value
  
  • arguments: <pin> <target pwm> <duration 1-30s>
  • example: set <esp> pwmfade 14 1023 10


• Pulse
  Direct pulse control of output pins
  
  • arguments: <pin> <0|1|off|on> <duration>
  • example: set <esp> pulse 14 on 10


• LongPulse
  Direct pulse control of output pins (duration in s)
  
  • arguments: <pin> <0|1|off|on> <duration>
  • example: set <esp> longpulse 14 on 10


• LongPulse_ms
  Direct pulse control of output pins (duration in ms)
  
  • arguments: <pin> <0|1|off|on> <duration>
  • example: set <esp> longpulse_ms 14 on 10000


• PCFGpio
  Control PCF8574 (8-bit I/O expander for I2C-bus)
  
  • arguments: <port> <0|1|off|on>
  • example: set <esp> PCFGpio 128 on
  Port numbering see: ESPEasy Wiki PCF8574


• PCFPulse
  Control PCF8574 (8-bit I/O expander for I2C-bus)
  • arguments: <port> <0|1|off|on> <duration>
  • example: set <esp> PCFPulse 128 on 10
  Port numbering see: ESPEasy Wiki PCF8574


• PCFLongPulse
  Control on PCF8574 (8-bit I/O expander for I2C-bus)
  • arguments: <port> <0|1|off|on> <duration>
  • example: set <esp> PCFLongPulse 128 on 10
  Port numbering see: ESPEasy Wiki PCF8574


• MCPGPIO
  Control MCP23017 output pins (16-Bit I/O Expander with Serial Interface)
  
  • arguments: <port> <0|1|off|on>
  • example: set <esp> MCPGPIO 48 on
  Port numbering see: ESPEasy Wiki MCP23017


• MCPPulse
  Pulse control on MCP23017 output pins (duration in ms)
  
  • arguments: <port> <0|1|off|on> <duration>
  • example: set <esp> MCPPulse 48 on 100


• MCPLongPulse
  Longpulse control on MCP23017 output pins (duration in s)
  
  • arguments: <port> <0|1|off|on> <duration>
  • example: set <esp> MCPLongPulse 48 on 2


• pcapwm
  Control PCA9685 (16-channel / 12-bit PWM I2C-bus controller)
  
  • arguments: <pin 0-15> <level 0-4095>
  • example: set <esp> pcapwm 15 4095

ESP Easy motor control commands:


• Servo
  Direct control of servo motors
  
  • arguments: <servoNo> <pin> <position>
  • example: set <esp> servo 1 14 100


• MotorShieldCMD
  Control a DC motor or stepper
  
  • arguments: DCMotor <motornumber> <forward|backward|release> <speed>
    arguments: Stepper <motornumber> <forward|backward|release> <steps> <single|double|interleave|microstep>
  • example: set <esp> MotorShieldCMD DCMotor 1 forward 10
    example: set <esp> MotorShieldCMD Stepper 1 backward 25 single

ESP Easy display related commands:


• lcd
  Write text messages to LCD screen
  Pay attention to attributes displayTextEncode and displayTextWidth.
  
  • arguments: <row> <col> <text>
  • example: set <esp> lcd 1 1 Test a b c


• lcdcmd
  Control LCD screen
  
  • arguments: <on|off|clear>
  • example: set <esp> lcdcmd clear


• oled
  Write text messages to OLED screen
  Pay attention to attributes displayTextEncode and displayTextWidth.
  
  • arguments: <row> <col> <text>
  • example: set <esp> oled 1 1 Test a b c


• oledcmd
  Control OLED screen
  
  • arguments: <on|off|clear>
  • example: set <esp> oledcmd clear


• oledframedcmd
  Switch oledframed on/off
  
  • arguments: <on|off>
  • example: set <esp> oledframedcmd on

ESP Easy DMX related commands:


• dmx
  Send DMX commands to a device
  
  • arguments: <on|off|log|value|channel=value[,value][...]>
  • example: set <esp> dmx 1=255,2=127

ESP Easy LED/Lights related commands:


• Lights (plugin can be found here)
  Control a rgb or ct light
  
  • arguments: <rgb|ct|pct|on|off|toggle> [<hex-rgb|color-temp|pct-value>] [<fading time>]
  • examples:
    set <esp> lights rgb aa00aa
set <esp> lights rgb aa00aa 10
set <esp> lights ct 3200
set <esp> lights ct 3200 10
set <esp> lights pct 50
set <esp> lights on
set <esp> lights off
set <esp> lights toggle
    


• nfx (plugin can be found here)
  Control nfx plugin. Note: To use FHEMWEB's colorpicker and slider widgets you have to set Attribut mapLightCmds to nfx.
  • arguments:

    all	<rrggbb> [fadetime] [delay +/-ms]
    bgcolor	<rrggbb>
    ct	<ct> [fadetime] [pct bri]
    colorfade	<rrggbb_start> <rrggbb_end> [startpixel] [endpixel]
    comet	<rrggbb> [speed +/- 0-50]
    count	<value>
    dim	<value 0-255>
    dualscan	<rrggbb> [rrggbb background] [speed 0-50]
    dualwipe	<rrggbb> [rrggbb dot] [speed +/- 0-50]
    fade	<rrggbb> [fadetime ms] [delay +/-ms]
    fadedelay	<value in +/-ms>
    fadetime	<value in ms>
    faketv	[startpixel] [endpixel]
    fire	[fps] [brightness 0-255] [cooling 20-100] [sparking 50-200]
    fireflicker	[intensity 0-255] [speed 0-50]
    kitt	<rrggbb> [speed 0-50]
    line	<startpixel> <endpixel> <rrggbb>
    off	[fadetime] [delay +/-ms]
    on	[fadetime] [delay +/-ms]
    one	<pixel> <rrggbb>
    pct	<pct> [fadetime]
    rainbow	[speed +/- 0-50]
    rgb	<rrggbb> [fadetime] [delay +/-ms]
    scan	<rrggbb> [rrggbb background] [speed 0-50]
    simpleclock	[bigtickcolor] [smalltickcolor] [hourcolor] [minutecolor] [secondcolor] [backgroundcolor]
    sparkle	<rrggbb> [rrggbb background] [speed 0-50]
    speed	<value 0-50>
    stop
    theatre	<rrggbb> [rrggbb background] [speed +/- 0-50]
    toggle	[fadetime]
    twinkle	<rrggbb> [rrggbb background] [speed 0-50]
    twinklefade	<rrggbb> [number of pixels] [speed 0-50]
    wipe	<rrggbb> [rrggbb dot] [speed +/- 0-50]

  • examples:
    set <esp> nfx all 00ff00 100
set <esp> nfx rgb aa00ff 1000 10
set <esp> nfx line 0 100 f0f0f0c

  • examples with attribut mapLightCmds set to nfx:
    set <esp> all 00ff00 100
set <esp> rgb aa00ff 1000 10
set <esp> line 0 100 f0f0f0c



• candle
  Control candle rgb plugin
  
  • arguments: CANDLE:<FlameType>:<Color>:<Brightness>
  • example: set <esp> CANDLE:4:FF0000:200


• neopixel
  Control neopixel plugin (single LED)
  
  • arguments: <led nr> <red 0-255> <green 0-255> <blue 0-255>
  • example: set <esp> neopixel 1 255 255 255


• neopixelall
  Control neopixel plugin (all together)
  
  • arguments: <red 0-255> <green 0-255> <blue 0-255>
  • example: set <esp> neopixelall 255 255 255


• neopixelline
  Control neopixel plugin (line)
  
  • arguments: <start led no> <stop led no> <red 0-255> <green 0-255> <blue 0-255>
  • example: set <esp> neopixelline 1 5 0 127 255

ESP Easy sound related commands:


• tone
  Play a tone on a pin via a speaker or piezo element (ESPEasy >= 2.0.0-dev6)
  
  • arguments: <pin> <freq Hz> <duration s>
  • example: set <esp> tone 14 4000 1


• rtttl
  Play melodies via RTTTL (ESPEasy >= 2.0.0-dev6)
  
  • arguments: <rtttl> <pin>:<rtttl codes>
  • example: set <esp> rtttl 14:d=10,o=6,b=180,c,e,g


• buzzer
  Beep a short time
  
  • arguments: none
  • example: set <esp> buzzer

ESP Easy miscellaneous commands:


• irsend
  Send ir codes via "Infrared Transmit" Plugin
  Supported protocols are: NEC, JVC, RC5, RC6, SAMSUNG, SONY, PANASONIC at the moment. As long as official documentation is missing you can find some details here: IR Transmitter thread #1 and IR Transmitter thread #61.
  
  • arguments: <NEC|JVC|RC5|RC6|SAMSUNG|SONY|PANASONIC> <hex code> <bit length>
    arguments: <RAW> <B32 raw> <frequenz> <pulse length> <blank length>
  • example: set <esp> irsend NEC 7E81542B 32
    example: set <esp> irsend RAW 3U0GGL8AGGK588A22K58ALALALAGL1A22LAK45ALALALALALALALALAL1AK5 38 512 256


• reboot
  Used to reboot your ESP
  
  • arguments: none
  • example: set <esp> reboot


• serialsend
  Used for ser2net plugin
  
  • arguments: <string>
  • example: set <esp> serialsend test

ESP Easy administrative commands (be careful !!!):


• erase
  Wipe out ESP flash memory
  
  • arguments: none
  • example: set <esp> erase


• reset
  Do a factory reset on the ESP
  
  • arguments: none
  • example: set <esp> reset


• resetflashwritecounter
  Used to reset flash write counter
  
  • arguments: none
  • example: set <esp> resetflashwritecounter

ESP Easy rules related commands (Note: These commands may be protected with the ESP Easy 'Admin Passsword'. See set adminpassword for details.)


• deepsleep
  Ask ESP to go into deepsleep mode.
  
  • arguments: <duration in is>


• event
  Trigger an ESP event. Such events can be used in ESP Easy rules.
  
  • arguments: <string>
  • example: set <esp> event testevent


• notify
  Send a notify message
  
  • arguments: <notify nr> <message>


• publish
  Publish a value via MQTT
  
  • arguments: <topic> <value>


• rules
  Enable/disable rule processing
  
  • arguments: <0|1|off|on>


• sendto
  Send a command to another ESP
  
  • arguments: <unit nr> <command>


• sendtohttp
  Used to tigger a HTTP URL call
  
  • arguments: none


• sendtoudp
  Used to tigger a UDP call
  
  • arguments: <ip> <port> <url>


• taskrun
  Used trigger a taskrun command
  
  • arguments: <task/device nr>


• taskvalueset
  Used to set taskvalueset
  
  • arguments: <task/device nr> <value nr> <value/formula>


• taskvaluesetandrun
  Used to set taskvaluesetandrun
  
  • arguments: <task/device nr> <value nr> <value/formula>


• timerset
  Set an ESP Easy timer
  
  • arguments: <timer nr> <duration in s>

ESP Easy experimental commands: (The following commands can be changed or removed at any time)


• rgb
  Used to control a rgb light wo/ an ESPEasy plugin.
  You have to set attribute rgbGPIOs to enable this feature. Default colorpicker mode is HSVp but can be adjusted with help of attribute colorpicker to HSV or RGB. Set attribute webCmd to rgb to display a colorpicker in FHEMWEB room view and on detail page.
  
  • arguments: <rrggbb>|on|off|toggle
  • examples:
    set <esp> rgb 00FF00
set <esp> rgb on
set <esp> rgb off
set <esp> rgb toggle
    
  • Full featured example:
    attr <ESP> colorpicker HSVp
    attr <ESP> devStateIcon { ESPEasy_devStateIcon($name) }
    attr <ESP> Interval 30
    attr <ESP> parseCmdResponse status,pwm
    attr <ESP> pollGPIOs D6,D7,D8
    attr <ESP> rgbGPIOs D6,D7,D8
    attr <ESP> webCmd rgb:rgb ff0000:rgb 00ff00:rgb 0000ff:toggle:on:off

ESP Easy deprecated commands: (will be removed in a later version)


• status
  Request esp device status (eg. gpio)
  See attributes: parseCmdResponse, readingPrefixGPIO, readingSuffixGPIOState
  • arguments: <pin>
  • example: set <esp> status 14



Attributes (logical device)


• adjustValue
  Used to adjust sensor values
  Must be a space separated list of <reading>:<formula>. Reading can be a regexp. Formula can be an arithmetic expression like 'round(($VALUE-32)*5/9,2)'. If $VALUE is omitted in formula then it will be added to the beginning of the formula. So you can simple write 'temp:+20' or '.*:*4'
  Modified or ignored values are marked in the system log (verbose 4). Use verbose 5 logging to see more details.
  If the used sub function returns 'undef' then the value will be ignored.
  The following variables can be used if necessary:
  • $VALUE contains the original value
  • $READING contains the reading name
  • $NAME contains the device name
  Default: none
  Eg. attr ESPxx adjustValue humidity:+0.1 temperature*:($VALUE-32)*5/9
  Eg. attr ESPxx adjustValue .*:my_OwnFunction($NAME,$READING,$VALUE)
  
  Sample function to ignore negative values:
  sub my_OwnFunction($$$) {
  my ($name,$reading,$value) = @_;
  return ($value < 0) ? undef : $value;
}



• colorpicker
  Used to select colorpicker mode
  Possible values: RGB,HSV,HSVp
  Default: HSVp


• colorpickerCTcw
  Used to select ct colorpicker's cold white color temperature in Kelvin
  Possible values: > colorpickerCTww
  Default: 6000


• colorpickerCTww
  Used to select ct colorpicker's warm white color temperature in Kelvin
  Possible values: < colorpickerCTcw
  Default: 2000


• disable
  Used to disable device
  Possible values: 0,1
  Default: 0


• deepsleep
  This attribut defines the default deep sleep state that is assumed if the ESP has not sent its status to FHEM. Eg. directly after a FHEM restart. If the ESP has sent its status, this value is ignored. Useful if you want to be sure that a set command would be queued and sent when the ESP awakes after a restart/rereadcfg of FHEM.
  Furthermore events for reading sleepState are generated if enabled. ESPEasy Mega with option to set sleep awake time (Config -> Sleep Mode -> Sleep awake time) is required to use this feature.
  Possible values: 0,1
  Default: 0


• disableRiskyCmds
  Used to disable supposed dangerous set cmds: erase, reset, resetflashwritecounter
  Possible values: 0,1
  Default: 0


• displayTextEncode
  Used to disable url encoding for text that is send to oled/lcd displays. Useful if you want to encode the text by yourself.
  Possible values: 0,1
  Default: 1 (enabled)


• displayTextWidth
  Used to specify number of characters per display line.
  If set then all characters before and after the text on the same line will be overwritten with spaces. Attribute displayTextEncode must not be disabled to use this feature. A 128x64px display has 16 characters per line if you are using a 8px font.
  Possible values: integer
  Default: 0 (disabled)


• Interval
  Used to set polling interval for presence check and GPIOs polling in seconds. 0 will disable this feature.
  Possible values: secs > 10.
  Default: 300


• IODev
  Used to select I/O device (ESPEasy Bridge).


• mapLightCmds
  Enable the following commands and map them to the specified ESPEasy command: rgb, ct, pct, on, off, toggle, dim, line, one, all, fade, colorfade, rainbow, kitt, comet, theatre, scan, dualscan, twinkle, twinklefade, sparkle, wipe, fire, stop, fadetime, fadedelay, count, speed, bgcolor. Ask the ESPEasy maintainer to add more if required.
  Needed to use FHEM's colorpicker or slider widgets to control a rgb/ct/effect/... plugin.
  required values: a valid set command
  eg. attr <esp> mapLightCmds Lights


• maxCmdDuration
  Only used if an ESP Easy node works in deep sleep mode. This attribut defines the amount of seconds your ESP node needs to work off a single command. In other words: This value defines how much awake time must be left to send a command to your ESP node before it goes into deep sleep mode. Commands that are not send will be queued und worked off when the node awakes again.
  ESPEasy Mega with option to set sleep awake time (Config -> Sleep Mode -> Sleep awake time) is required to use this feature.
  Possible values: secs >= 0, but < awake time
  Default: 1


• presenceCheck
  Used to enable/disable presence check for ESPs
  Presence check determines the presence of a device by readings age. If any reading of a device is newer than interval seconds then it is marked as being present. This kind of check works for ESP devices in deep sleep too but require at least 1 reading that is updated regularly. Therefore the ESP must send the corresponding data regularly (ESP device option "delay").
  Possible values: 0,1
  Default: 1 (enabled)


• readingFnAttributes


• readingSwitchText
  Map values for readings to on/off instead 0/1 if ESP device is a switch.
  Possible values:
  0: disable mapping.
  1: enable mapping 0->off / 1->on
  2: enable inverse mapping 0->on / 1->off
  Default: 1


• rgbGPIOs
  Use to define GPIOs your lamp is conneted to. Must be set to be able to use rgb set command.
  Possible values: Comma separated tripple of ESP pin numbers or arduino pin names
  Eg: 12,13,15
  Eg: D6,D7,D8
  Default: none


• setState
  Summarize received values in state reading.
  A positive number determines the number of characters used for abbreviated reading names. Only readings with an age less than interval will be considered. If your are not satisfied with format or behavior of setState then disable this attribute (set to 0) and use global attributes userReadings and/or stateFormat to get what you want.
  Possible values: integer >=0
  Default: 3 (enabled with 3 characters abbreviation)


• userSetCmds
  Can be used to:
  • Define new, own or unconsidered ESP Easy commands. Note: alternatively the set commands raw or rawsystem can also be used to it.
    
  • Mapping of secondary commands as primary ones to be able to use FHEM widgets or FHEM's set extentions.
  • Redefine built-in commands.
  
  Argument must be a perl hash. The following hash keys can be used. An omitted key will be replaced with the appropriate default value.
  
  • args: minimum number of required arguments for set cmd. Default: 0, no additional arguments required.
    [Special case: if set to -1 then <FHEM cmd> will not be added to <ESP Easy cmd>. Useful if <FHEM cmd> differs from <ESP Easy cmd>. <ESP Easy cmd> must then be part of url hash key. See Forum or example myCmd4 below.]
  • url: ESPEasy URL to be called. Default: "/control?cmd="
  • widget: FHEM widget to be used for this set command. Default: none
  • cmds: Sub command(s) of specified plugin that will be mapped as regular command(s). Must also be a perl hash. Default: none
  • usage: Possible command line arguments. Used in help command and syntax check. Required arguments should be enclosed in curly brackets, optional arguments in square brackets. Both should be separated by spaces. Default: none
  The following usage strings have a special meaning and effect:
  • <0|1|off|on>: "on" or "off" will be replaced with "0" or "1" in commands send to the ESPEasy device. See attribute readingSwitchText for details.
  • <pin>: GPIO pin numbers can also be written as Arduino/NodeMCU pin names. See get pinMap command.
  • <text>: Text will be encoded for use with oled/lcd commands to be able to use special characters.
  
  Define new commands:
  
  • ( myCmd1 => {} )
  • ( myCmd1 => {}, myCmd2 => {} )
  • ( myCmd3 => {args => 2, url => "/?cmd=", widget=> "", usage => "<param1> <param2>"} )
  • ( myCmd4 => {url =>"/control?cmd=event,myevent", args => -1} )
  
  Define new commands with mapped sub commands:
  This example registers the new commands plugin_a and plugin_b. Both commands can be used like any other ESP Easy command (eg. set dev plugin_b on). Sub commands rgb, ct, on, off and bri can also be used as regular commands. The advantage is that FHEM's widgets and/or set extentions can be used for these sub commands right now.

  • (
    plugin_a => {
        args  => 2,
        url   => "/control?cmd=",
        usage => "<rgb|ct> ",
        cmds  => {
           rgb => { args => 1, usage => "<rrggbb>", widget => "colorpicker,HSV" },
           ct  => { args => 1, usage => "<colortemp>", widget => "colorpicker,CT,2000,10,4000" }
        }
      },
    plugin_b => {
        args  => 1,
        url   => "/foo?bar",
        usage => "<on|off|bri> [bri_value]",
        cmds  => {
           on  => { widget => "noArg" },
           off => { widget => "noArg" },
           bri => { widget => "knob,min:1,max:100,step:1,linecap:round", usage => "<0..255>", args => 1 }
        }
      }
    )

• useSetExtensions
  If set to 1 and on/off commands are available (use userSetCmds or eventMap if not) then the set extensions are supported.
  Default: 0 (disabled)
  Eg. attr ESPxx useSetExtensions 1

Deprecated attributes:


• parseCmdResponse (deprecated, may be removed in later versions)
  Used to parse response of commands like GPIO, PWM, STATUS, ...
  Specify a module command or comma separated list of commands as argument. Commands are case insensitive.
  Only necessary if ESPEasy software plugins do not send their data independently. Useful for commands like STATUS, PWM, ...
  Possible values: <set cmd>[,<set cmd>][,...]
  Default: status
  Eg. attr ESPxx parseCmdResponse status,pwm


• pollGPIOs (deprecated, may be removed in later versions)
  Used to enable polling for GPIOs status. This polling will do same as command 'set ESPxx status <device> <pin>'
  Possible values: GPIO number or comma separated GPIO number list
  Default: none
  Eg. attr ESPxx pollGPIOs 13,D7,D2

The following two attributes control naming of readings that are generated by help of parseCmdResponse and pollGPIOs (see above)


• readingPrefixGPIO (deprecated, may be removed in later versions)
  Specifies a prefix for readings based on GPIO numbers. For example: "set ESPxx pwm 13 512" will switch GPIO13 into pwm mode and set pwm to 512. If attribute readingPrefixGPIO is set to PIN and attribut parseCmdResponse contains pwm command then the reading name will be PIN13.
  Possible Values: string
  Default: GPIO


• readingSuffixGPIOState (deprecated, may be removed in later versions)
  Specifies a suffix for the state-reading of GPIOs (see Attribute pollGPIOs)
  Possible Values: string
  Default: no suffix
  Eg. attr ESPxx readingSuffixGPIOState _state

ElectricityCalculator

The ElectricityCalculator Module calculates the electrical energy consumption and costs of one ore more electricity meters. It is not a counter module itself but it requires a regular expression (regex or regexp) in order to know where to retrieve the continously increasing counter value of one or more mechanical or electronic electricity meter. As soon the module has been defined within the fhem.cfg, the module reacts on every event of the specified counter like myOWDEVICE:counter.* etc. The ElectricityCalculator module provides several current, historical, statistical values around with respect to one or more electricity meter and creates respective readings. To avoid waiting for max. 12 months to have realistic values, the readings <DestinationDevice>_<SourceCounterReading>_CounterDay1st, <DestinationDevice>_<SourceCounterReading>_CounterMonth1st, <DestinationDevice>_<SourceCounterReading>_CounterYear1st and <DestinationDevice>_<SourceCounterReading>_CounterMeter1st must be corrected with real values by using the setreading - command. These real values may be found on the last electricity bill. Otherwise it will take 24h for the daily, 30days for the monthly and up to 12 month for the yearly values to become realistic. Intervalls smaller than 10s will be discarded to avoid peaks due to fhem blockages (e.g. DbLog - reducelog).




Define
define <name> ElectricityCalculator <regex>
<name> :	The name of the calculation device. (E.g.: "myElectricityCalculator")
<regex> :	A valid regular expression (also known as regex or regexp) of the event where the counter can be found
Example: define myElectricityCalculator ElectricityCalculator myElectricityCounter:countersA.*




Set

The set - function sets individual values for example to correct values after power loss etc. The set - function works for readings which have been stored in the CalculatorDevice and to update the Offset. The Readings being stored in the Counter - Device need to be changed individially with the set - command. The command "SyncCounter" will calculate and update the Offset. Just enter the value of your mechanical Reader.




Get

The get - function just returns the individual value of the reading. The get - function works only for readings which have been stored in the CalculatorDevice. The Readings being stored in the Counter - Device need to be read individially with get - command.




Attributes

If the below mentioned attributes have not been pre-defined completly beforehand, the program will create the ElectricityCalculator specific attributes with default values. In addition the global attributes e.g. room can be used.

BasicPricePerAnnum : A valid float number for basic annual fee in the chosen currency for the electricity supply to the home. The value is provided by your local electricity supplier and is shown on your electricity bill. For UK and US users it may known under "standing charge". Please make sure it is based on one year! The default value is 0.00

Currency : One of the pre-defined list of currency symbols [€,£,$]. The default value is €

disable : Disables the current module. The module will not react on any events described in the regular expression. The default value is 0 = enabled.

ElectricityCounterOffset : A valid float number of the electric Energy difference = offset (not the difference of the counter ticks!) between the value shown on the mechanic meter for the electric energy and the calculated electric energy of the counting device. The value for this offset will be calculated as follows WOffset = WMechanical - WModule The default value is 0.00

ElectricityKwhPerCounts : A valid float number of electric energy in kWh per counting ticks. The value is given by the mechanical trigger of the mechanical electricity meter. E.g. ElectricityKwhPerCounts = 0.001 means each count is a thousandth of one kWh (=Wh). Some electronic counter (E.g. HomeMatic HM-ES-TX-WM) providing the counted electric energy as Wh. Therfore this attribute must be 0.001 in order to transform it correctly to kWh. The default value is 1 (= the counter is already providing kWh)

ElectricityPricePerKWh : A valid float number for electric energy price in the chosen currency per kWh. The value is provided by your local electricity supplier and is shown on your electricity bill. The default value is 0.2567

MonthlyPayment : A valid float number for monthly advance payments in the chosen currency towards the electricity supplier. The default value is 0.00

MonthOfAnnualReading : A valid integer number for the month when the mechanical electricity meter reading is performed every year. The default value is 5 (May)

ReadingDestination : One of the pre-defined list for the destination of the calculated readings: [CalculatorDevice,CounterDevice]. The CalculatorDevice is the device which has been created with this module. The CounterDevice is the Device which is reading the mechanical Electricity-meter. The default value is CalculatorDevice - Therefore the readings will be written into this device.

SiPrefixPower : One value of the pre-defined list: W (Watt), kW (Kilowatt), MW (Megawatt) or GW (Gigawatt). It defines which SI-prefix for the power value shall be used. The power value will be divided accordingly by multiples of 1000. The default value is W (Watt).

DecimalPlace : One value of the pre-defined list 3 to 7. It defines to which accuracy in decimal places all results shall be calculated. The default value is 3 = 0.001.




Readings

As soon the device has been able to read at least 2 times the counter, it automatically will create a set of readings: The placeholder <DestinationDevice> is the device which has been chosen in the attribute ReadingDestination above. This will not appear if CalculatorDevice has been chosen. The placeholder <SourceCounterReading> is the reading based on the defined regular expression where the counting ticks are coming from.

<DestinationDevice>_<SourceCounterReading>_CounterCurrent	: Current indicated total electric energy consumption as shown on mechanical electricity meter. Correct Offset-attribute if not identical.
<DestinationDevice>_<SourceCounterReading>_CounterDay1st	: The first meter reading after midnight.
<DestinationDevice>_<SourceCounterReading>_CounterDayLast	: The last meter reading of the previous day.
<DestinationDevice>_<SourceCounterReading>_CounterMonth1st	: The first meter reading after midnight of the first day of the month.
<DestinationDevice>_<SourceCounterReading>_CounterMonthLast	: The last meter reading of the previous month.
<DestinationDevice>_<SourceCounterReading>_CounterMeter1st	: The first meter reading after midnight of the first day of the month where the mechanical meter is read by the electricity supplier.
<DestinationDevice>_<SourceCounterReading>_CounterMeterLast	: The last meter reading of the previous meter reading year.
<DestinationDevice>_<SourceCounterReading>_CounterYear1st	: The first meter reading after midnight of the first day of the year.
<DestinationDevice>_<SourceCounterReading>_CounterYearLast	: The last meter reading of the previous year.
<DestinationDevice>_<SourceCounterReading>_EnergyCostDayLast	: Energy costs of the last day.
<DestinationDevice>_<SourceCounterReading>_EnergyCostMeterLast	: Energy costs in the chosen currency of the last electricity meter period.
<DestinationDevice>_<SourceCounterReading>_EnergyCostMonthLast	: Energy costs in the chosen currency of the last month.
<DestinationDevice>_<SourceCounterReading>_EnergyCostYearLast	: Energy costs of the last calendar year.
<DestinationDevice>_<SourceCounterReading>_EnergyCostDay	: Energy consumption in kWh since the beginning of the current day (midnight).
<DestinationDevice>_<SourceCounterReading>_EnergyCostMeter	: Energy costs in the chosen currency since the beginning of the month of where the last electricity meter reading has been performed by the electricity supplier.
<DestinationDevice>_<SourceCounterReading>_EnergyCostMonth	: Energy costs in the chosen currency since the beginning of the current month.
<DestinationDevice>_<SourceCounterReading>_EnergyCostYear	: Energy costs in the chosen currency since the beginning of the current year.
<DestinationDevice>_<SourceCounterReading>_EnergyDay	: Energy consumption in kWh since the beginning of the current day (midnight).
<DestinationDevice>_<SourceCounterReading>_EnergyDayLast	: Total Energy consumption in kWh of the last day.
<DestinationDevice>_<SourceCounterReading>_EnergyMeter	: Energy consumption in kWh since the beginning of the month of where the last electricity-meter reading has been performed by the Electricity supplier.
<DestinationDevice>_<SourceCounterReading>_EnergyMeterLast	: Total Energy consumption in kWh of the last electricity-meter reading period.
<DestinationDevice>_<SourceCounterReading>_EnergyMonth	: Energy consumption in kWh since the beginning of the current month (midnight of the first).
<DestinationDevice>_<SourceCounterReading>_EnergyMonthLast	: Total Energy consumption in kWh of the last month.
<DestinationDevice>_<SourceCounterReading>_EnergyYear	: Energy consumption in kWh since the beginning of the current year (midnight of the first).
<DestinationDevice>_<SourceCounterReading>_EnergyYearLast	: Total Energy consumption in kWh of the last calendar year.
<DestinationDevice>_<SourceCounterReading>_FinanceReserve	: Financial Reserve based on the advanced payments done on the first of every month towards the Electricity supplier. With negative values, an additional payment is to be expected.
<DestinationDevice>_<SourceCounterReading>_MonthMeterReading	: Number of month since last meter reading. The month when the reading occured is the first month = 1.
<DestinationDevice>_<SourceCounterReading>_PowerCurrent	: Current electric Power. (Average Power between current and previous measurement.)
<DestinationDevice>_<SourceCounterReading>_PowerDayAver	: Average electric Power since midnight.
<DestinationDevice>_<SourceCounterReading>_PowerDayMax	: Maximum Power peak since midnight.
<DestinationDevice>_<SourceCounterReading>_PowerDayMin	: Minimum Power peak since midnight.

EleroDrive

This mudule implements an Elero drive. It uses EleroStick as IO-Device.

Define
define <name> EleroDrive <channel>
<channel> specifies the channel of the transmitter stick that shall be used.


Set
• moveDown
  
• moveUp
  
• stop
  
• moveIntermediate
  
• moveTilt
  
• refresh
  

Get
• no gets
  


Attributes
• IODev
  The name of the IO-Device, normally the name of the EleroStick definition
• TopToBottomTime
  The time in seconds this drive needs for a complete run from the top to the bottom or vice versa
• IntermediatePercent
  Percent open when in intermediate position
• TiltPercent
  Percent open when in tilt position

Readings
• position
  Current position of the drive (top_position, bottom_position, ...)
• percentClosed
  0 ... 100
  100 is completely closed, 0 is completely open

EleroStick

This module provides the IODevice for EleroDrive and other future modules that implement Elero components
It handles the communication with an "Elero Transmitter Stick"

Define
• define <name> EleroStick <port>
  <port> specifies the serial port where the transmitter stick is attached.
  The name of the serial-device depends on your OS. Example: /dev/ttyUSB1@38400
  The baud rate must be 38400 baud.
  
  
Set
• no sets
  


Get
• no gets
  


Attributes
• Clients
  The received data gets distributed to a client (e.g. EleroDrive, ...) that handles the data. This attribute tells, which are the clients, that handle the data. If you add a new module to FHEM, that shall handle data distributed by the EleroStick module, you must add it to the Clients attribute.


• MatchList
  The MatchList defines, which data shall be distributed to which device.
  It can be set to a perl expression that returns a hash that is used as the MatchList
  Example: attr myElero MatchList {'1:EleroDrive' => '.*'}


• ChannelTimeout
  The delay, how long the modul waits for an answer after sending a command to a drive.
  Default is 5 seconds.


• Delay
  If something like structure send commands very fast, Delay (seconds) throttles the transmission down that the Elero-system gets time to handle each command.


• DisableTimer
  Disables the periodically request of the status. Should normally not be set to 1.


• SwitchChannels
  Comma separated list of channels that are a switch device.


• Interval
  When all channels are checkt, this number of seconds will be waited, until the channels will be checked again.
  Default is 60 seconds.


Readings
• state
  disconnected or opened if a transmitter stick is connected
• SendType
  Type of the last command sent to the stick
• SendMsg
  Last command sent to the stick
• AnswerType
  Type of the last Answer received from the stick
• AnswerMsg
  Last Answer received from the stick

EleroSwitch

This mudule implements an Elero switch. It uses EleroStick as IO-Device.

Define
define <name> EleroSwitch <channel>
<channel> specifies the channel of the transmitter stick that shall be used.


Set
• on
  
• off
  
• dim1
  
• dim2
  
• refresh
  

Get
• no gets
  


Attributes
• IODev
  The name of the IO-Device, normally the name of the EleroStick definition

Readings
• state
  Current state of the switch (on, off, dim1, dim2)

ElsnerWS

The ElsnerWS weather evaluation modul serves as a connecting link between the Elsner P03/3-RS485 Weather Stations or Elsner P04/3-RS485 Weather Stations or and blind actuators. ElsnerWS use a RS485 connection to communicate with the Elsner P0x/3-RS485 Weather Stations. It received the raw weather data periodically once a second, which manufacturer-specific coded via an RS485 bus serially are sent. It evaluates the received weather data and based on adjustable thresholds and delay times it generates up/down signals for blinds according to wind, rain and sun. This way blinds can be pilot-controlled and protected against thunderstorms. The GPS function of the sensor provides the current values of the date, time, weekday, sun azimuth, sun elevation, longitude and latitude.
As an alternative to the module for the Elsner RS485 sensors, sensors with Modbus RS485 protocol can also be used. The ModbusElsnerWS module is available for this purpose. EnOcean profiles "Environmental Applications" with the EEP A5-13-01 ... EEP A5-13-06 are also available for these weather stations, but they also require weather evaluation units from Eltako or AWAG, for example. The functional scope of the modules is widely similar.

Functions
• Evaluation modul for the weather sensors P03/3-RS485 or P04/3-RS485 (Basic|CET|GPS)
• Processing weather raw data and creates graphic representation
• For wind observations, average speeds, gusts and peak values are calculated.
• Alarm signal in case of failure of the weather sensor
• Up/down readings for blinds according to wind, rain and sun
• Adjustable switching thresholds and delay times
• Day/night signal
• Display of date, time, sun azimuth, sun elevation, longitude and latitude
• Execution of custom alarm commands, see customCmdAlarmOff and customCmdAlarmOn.
• Execution of custom up and down commands that can be triggered by the readings dayNight, isRaining, isStormy, isSunny, isSunnyEast, isSunnySouth, isSunnyWest and isWindy, see customCmdDown and customCmdUp.

Prerequisites
This module requires the basic Device::SerialPort or Win32::SerialPort module.

Hardware Connection
The weather sensors P03/3-RS485 or P04/3-RS485 are connected via a shielded cable 2x2x0.5 mm2 to a RS485 transceiver. The sensor is connected via the pins A to the RS485 B(+)-Port, B to RS485 A(-)-Port, 1 to + 24 V, 2 to GND and Shield. Please note that the RS485 connection names are reversed. Only the usual pins for serial Modbus communication A, B and Ground are needed. Multiple Fhem devices can be connected to the sensor via the RS485 bus at the same time.
The serial bus should be terminated at its most remote ends with 120 Ohm resistors. If several RS485 transceiver are connected to the serial bus, only the termination resistor in the devices furthest ends must be switched on.
More information about the sensors, see for example P03/3-RS485-GPS User Guide.
The USB adapters Digitus DA-70157, In-Circuit USB-RS485-Bridge and DSD TECH SH-U10 USB to RS485 converter are successfully tested at a Raspberry PI in conjunction with the weather sensor.

Define
define <name> ElsnerWS comtype=<comtype> devicename=<devicename>

The module connects to the Elsner Weather Station via serial bus <rs485> through the device <device>.
The following parameters apply to an RS485 transceiver to USB.

Example:
define WS ElsnerWS comtype=rs485 devicename=/dev/ttyUSB1@19200
define WS ElsnerWS comtype=rs485 devicename=COM1@19200 (Windows)

Alternatively, the device can also be created automatically by autocreate. Once the weather station is connected to Fhem via the RS485 USB transceiver, Fhem is to be restarted. The active but not yet configured USB ports are searched for a ready-to-operate weather station during the Fhem boot.

Attributes
• brightnessDayNight E_min/lx:E_max/lx, [brightnessDayNight] = 0...99000:0...99000, 10:20 is default.
  Set switching thresholds for reading dayNight based on the reading brightness.
• brightnessDayNightCtrl custom|sensor, [brightnessDayNightCtrl] = custom|sensor, sensor is default.
  Control the dayNight reading through the device-specific or custom threshold and delay.
• brightnessDayNightDelay t_reset/s:t_set/s, [brightnessDayNightDelay] = 0...3600:0...3600, 600:600 is default.
  Set switching delay for reading dayNight based on the reading brightness. The reading dayNight is reset or set if the thresholds are permanently undershot or exceed during the delay time.
• brightnessSunny E_min/lx:E_max/lx, [brightnessSunny] = 0...99000:0...99000, 20000:40000 is default.
  Set switching thresholds for reading isSunny based on the reading brightness.
• brightnessSunnyDelay t_reset/s:t_set/s, [brightnessSunnyDelay] = 0...3600:0...3600, 120:30 is default.
  Set switching delay for reading isSunny based on the reading brightness. The reading isSunny is reset or set if the thresholds are permanently undershot or exceed during the delay time.
• brightnessSunnyEast E_min/lx:E_max/lx, [brightnessSunnyEast] = 0...99000:0...99000, 20000:40000 is default.
  Set switching thresholds for reading isSunnyEast based on the reading sunEast.
• brightnessSunnyEastDelay t_reset/s:t_set/s, [brightnessSunnyEastDelay] = 0...3600:0...3600, 120:30 is default.
  Set switching delay for reading isSunnyEast based on the reading sunEast. The reading isSunnyEast is reset or set if the thresholds are permanently undershot or exceed during the delay time.
• brightnessSunnySouth E_min/lx:E_max/lx, [brightnessSunnySouth] = 0...99000:0...99000, 20000:40000 is default.
  Set switching thresholds for reading isSunnySouth based on the reading sunSouth.
• brightnessSunnySouthDelay t_reset/s:t_set/s, [brightnessSunnySouthDelay] = 0...3600:0...3600, 120:30 is default.
  Set switching delay for reading isSunnySouth based on the reading sunSouth. The reading isSunnySouth is reset or set if the thresholds are permanently undershot or exceed during the delay time.
• brightnessSunnyWest E_min/lx:E_max/lx, [brightnessSunnyWest] = 0...99000:0...99000, 20000:40000 is default.
  Set switching thresholds for reading isSunnyWest based on the reading sunWest.
• brightnessSunnyWestDelay t_reset/s:t_set/s, [brightnessSunnyWestDelay] = 0...3600:0...3600, 120:30 is default.
  Set switching delay for reading isSunnyWest based on the reading sunWest. The reading isSunnyWest is reset or set if the thresholds are permanently undershot or exceed during the delay time.
• customCmdAlarmOff <command>
  customCmdAlarmOn <command>
  Command being executed if an alarm is set (on) or deleted (off). If <command> is enclosed in {}, then it is a perl expression, if it is enclosed in "", then it is a shell command, else it is a "plain" fhem.pl command (chain). In the <command> you can access the name of the device by using $NAME, $TYPE and the current readings
  $BRIGHTNESS, $DATE, $DAYNIGHT, $HEMISPHERE, $ISRAINING, $ISSTORMY, $ISSUNNY, $ISSUNNYEAST, $ISSUNNYSOUTH", $ISSUNNYWEST, $ISWINDY, $LATITUDE, $LONGITUDE, $NAME, $SUNAZIMUTH, $SUNEAST, $SUNELAVATION, $SUNSOUTH, $SUNWEST, $TEMPERATURE, $TIME, $TIMEZONE, $TWILIGHT, $TYPE, $WEEKDAY, $WINDAVG2MIN, $WINDGUST10MIN, $WINDGUSTCURRNT, $WINDPEAK10MIN, $WINDSPEED, $WINDSTENGTH.
  The eventMap replacements are taken into account. This data is available as a local variable in perl, as environment variable for shell scripts, and will be textually replaced for Fhem commands.
  The alarm commands have a higher priority than the up and down commands.
• customCmdDown <command>
  customCmdUp <command>
  The command is executed if the Up or Down command is triggered, see customCmdDownTrigger or customCmdUpTrigger. If <command> is enclosed in {}, then it is a perl expression, if it is enclosed in "", then it is a shell command, else it is a "plain" fhem.pl command (chain). In the <command> you can access the name of the device by using $NAME, $TYPE and the current readings
  $BRIGHTNESS, $DATE, $DAYNIGHT, $HEMISPHERE, $ISRAINING, $ISSTORMY, $ISSUNNY, $ISSUNNYEAST, $ISSUNNYSOUTH", $ISSUNNYWEST, $ISWINDY, $LATITUDE, $LONGITUDE, $NAME, $SUNAZIMUTH, $SUNEAST, $SUNELAVATION, $SUNSOUTH, $SUNWEST, $TEMPERATURE, $TIME, $TIMEZONE, $TWILIGHT, $TYPE, $WEEKDAY, $WINDAVG2MIN, $WINDGUST10MIN, $WINDGUSTCURRNT, $WINDPEAK10MIN, $WINDSPEED, $WINDSTENGTH.
  The eventMap replacements are taken into account. This data is available as a local variable in perl, as environment variable for shell scripts, and will be textually replaced for Fhem commands.
  The alarm commands have a higher priority than the up and down commands.
• customCmdDownPeriod once|threeTimes|3|10|180|600
  customCmdUpPeriod once|threeTimes|3|10|180|600
  [customCmdDownPeriod] = once|threeTimes|3|10|180|600, once is default.
  Number or period of custom command to be executed.
• customCmdDownTrigger dayNight|isRaining|isStormy|isSunny|isSunnyEast|isSunnySouth|isSunnyWest|isWindy
  The commands in the attribute customCmdDown are executed if one of the selected readings is triggered as follows:
  • [dayNight] = night
  • [isRaining] = no
  • [isStormy] = no
  • [isSunny] = yes
  • [isSunnyEast] = yes
  • [isSunnySouth] = yes
  • [isSunnyWest] = yes
  • [isWindy] = no
  The commands in the attribute customCmdDown are executed periodically every second if the attribute is not set.
• customCmdUpTrigger dayNight|isRaining|isStormy|isSunny|isSunnyEast|isSunnySouth|isSunnyWest|isWindy
  The commands in the attribute customCmdUp are executed if one of the selected readings is triggered as follows:
  • [dayNight] = day
  • [isRaining] = yes
  • [isStormy] = yes
  • [isSunny] = no
  • [isSunnyEast] = no
  • [isSunnySouth] = no
  • [isSunnyWest] = no
  • [isWindy] = yes
  The commands in the attribute customCmdUp are executed periodically every second if the attribute is not set.
• customCmdPriority down|up, [customCmdPriority] = down|up, up is default.
  Priority of custom commands. If both the up and down command are triggered, only the prioritized command is executed.
• readingFnAttributes
• signOfLife off|on, [signOfLife] = off|on, on is default.
  Monitoring of the periodic telegrams from sensor.
• signOfLifeInterval t/s, [signOfLifeInterval] = 1 ... 15, 3 is default.
  Monitoring period in seconds of the periodic telegrams from sensor.
• timeEvent no|yes, [timeEvent] = no|yes, no is default.
  Update the reading time periodically.
• updateGlobalAttr no|yes, [updateGlobalAttr] = no|yes, no is default.
  Update the global attributes latitude and longitude with the received GPS coordinates.
• windSpeedStormy v_min/m/s:v_max/m/s, [windSpeedStormy] = 0...35:0...35, 13.9:17.2 (windStrength = 7 B - 8 B) is default.
  Set switching thresholds for reading isStormy based on the reading windSpeed.
• windSpeedStormyDelay t_reset/s:t_set/s, [windSpeedStormyDelay] = 0...3600:0...3600, 60:3 is default.
  Set switching delay for reading isStormy based on the reading windSpeed. The reading isStormy is reset or set if the thresholds are permanently undershot or exceed during the delay time.
• windSpeedWindy v_min/m/s:v_max/m/s, [windSpeedWindy] = 0...35:0...35, 1.6:3.4 (windStrength = 2 B - 3 B) is default.
  Set switching thresholds for reading isWindy based on the reading windSpeed.
• windSpeedWindyDelay t_reset/s:t_set/s, [windSpeedWindyDelay] = 0...3600:0...3600, 60:3 is default.
  Set switching delay for reading isWindy based on the reading windSpeed. The reading isWindy is reset or set if the thresholds are permanently undershot or exceed during the delay time.

Generated events
• T: t/°C B: E/lx W: v/m/s IR: no|yes
• alarm: dead_sensor
• brightness: E/lx (Sensor Range: E = 0 lx ... 99000 lx)
• date: JJJJ-MM-TT
• dayNight: day|night
• hemisphere: north|south
• isRaining: no|yes
• isStormy: no|yes
• isSunny: no|yes
• isSunnyEast: no|yes
• isSunnySouth: no|yes
• isSunnyWest: no|yes
• isWindy: no|yes
• latitude: φ/° (Sensor Range: φ = -90 ° ... 90 °)
• longitude: λ/° (Sensor Range: λ = -180 ° ... 180 °)
• sunAzimuth: α/° (Sensor Range: α = 0 ° ... 359 °)
• sunEast: E/lx (Sensor Range: E = 0 lx ... 99000 lx)
• sunElevation: β/° (Sensor Range: β = -90 ° ... 90 °)
• sunSouth: E/lx (Sensor Range: E = 0 lx ... 99000 lx)
• sunWest: E/lx (Sensor Range: E = 0 lx ... 99000 lx)
• temperature: t/°C (Sensor Range: t = -40 °C ... 70 °C)
• time: hh:mm:ss
• timeZone: CET|CEST|UTC
• weekday: Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday
• twilight: T/% (Sensor Range: T = 0 % ... 100 %)
• windAvg2min: v/m/s (Sensor Range: v = 0 m/s ... 70 m/s)
• windGust10min: v/m/s (Sensor Range: v = 0 m/s ... 70 m/s)
• windGustCurrent: v/m/s (Sensor Range: v = 0 m/s ... 70 m/s)
• windPeak10min: v/m/s (Sensor Range: v = 0 m/s ... 70 m/s)
• windSpeed: v/m/s (Sensor Range: v = 0 m/s ... 70 m/s)
• windStrength: B (Sensor Range: B = 0 Beaufort ... 12 Beaufort)
• state: T: t/°C B: E/lx W: v/m/s IR: no|yes

EnOcean

Quick Links
• Define
• Internals
• Get Commands
• Set Commands
• Attributes
• Generated Events


EnOcean devices are sold by numerous hardware vendors (e.g. Eltako, Peha, etc), using the RF Protocol provided by the EnOcean Alliance.

Depending on the function of the device an specific device profile is used, called EnOcean Equipment Profile (EEP). The specific definition of a device is referenced by the EEP (RORG-FUNC-TYPE). Basically four groups (RORG) will be differed, e. g. RPS (switches), 1BS (contacts), 4BS, VLD (sensors and controller). Some manufacturers use additional proprietary extensions. RORG MSC is not supported except for few exceptions. Further technical information can be found at the EnOcean Alliance, see in particular the EnOcean Equipment Profiles (EEP)

The supplementary Generic Profiles approach instead defines a language to communicate the transmitted data types and ranges. The devices becomes self describing on their data structures in communication. The Generic Profiles include a language definition with a parameter selection that covers every possible measured value to be transmitted. Therefore, the approach does not only define parameters for the value recalculation algorithm but also includes specific signal definition. (e.g. physical units). Further technical information can be found at the Generic Profiles 1.0 Abstract

Smart Acknowledge (Smart Ack) enables a special bidirectional communication. The communication is managed by a Controller that responds to the devices telegrams with acknowledges. Smart Ack is a bidirectional communication protocol between two actors. At least one actor must be an energy autarkic Sensor, and at least one must be a line powered Controller (Fhem). A sensor sends its data and expects the answer telegram in a predefined very short time slot. In this time Sensors receiver is active. For this purpose we declare a Post Master with Mail Boxes. A Mail Box is like a letter box for a Sensor and it specific to a single sender. Telegrams from Fhem are collected into the Mail Box. A Sensor can reclaim telegrams that are in his Mail Box.

Fhem recognizes a number of devices automatically. In order to teach-in, for some devices the sending of confirmation telegrams has to be turned on. Some equipment types and/or device models must be manually specified. Do so using the attributes subType and model, see chapter Set and Generated events. With the help of additional attributes, the behavior of the devices can be changed separately.

Fhem and the EnOcean devices must be trained with each other. To this, Fhem must be in the learning mode, see Teach-In / Teach-Out, Smart Ack Learning and learningMode. The teach-in procedure depends on the type of the devices.

Switches (EEP RPS) and contacts (EEP 1BS) are recognized when receiving the first message. Contacts can also send a teach-in telegram. Fhem not need this telegram. Sensors (EEP 4BS) has to send a teach-in telegram. The profile-less 4BS teach-in procedure transfers no EEP profile identifier and no manufacturer ID. In this case Fhem does not recognize the device automatically. The proper device type must be set manually, use the attributes subType, manufID and/or model. If the EEP profile identifier and the manufacturer ID are sent the device is clearly identifiable. Fhem automatically assigns these devices to the correct profile.

4BS devices can also be taught in special cases by using of confirmation telegrams. This method is used for the EnOcean Tipp-Funk devices. The function is activated via the attribute [teachMethod] = confirm. Some Eltako devices are fully preconfigured via Inofficial EEP for this procedure.
For example the remote device Eltako TF100D can be learned as follows

define <name> EnOcean H5-38-08
set TF100D in learning mode
set <name> teach

Some 4BS, VLD or MSC devices must be paired bidirectional, see Teach-In / Teach-Out.

For some devices, Eltako uses a company-specific MSC teach-in process. These devices send special MSC telegrams when switched on or the device is set to LRN. With bidirectional actuators, the MSC telegrams are only sent as long as they are still in the delivery state or the teach-in process is activated manually. See Inofficial EEP for the supported devices. To teach-in the devices in Fhem,

set <IODev> teach <t/s>

must be activated.

Devices that communicate encrypted, has to taught-in through specific procedures.

Smart Ack Learning is a futher process where devices exchange information about each other in order to create the logical links in the EnOcean network and a Post Master Mail Box. It can result in Learn In or Learn Out, see Smart Ack Learning.

Fhem supports many of most common EnOcean profiles and manufacturer-specific devices. Additional profiles and devices can be added if required.

In order to enable communication with EnOcean remote stations a TCM module is necessary.

Please note that EnOcean repeaters also send Fhem data telegrams again. Use the TCM attr <name> blockSenderID own to block receiving telegrams with a TCM SenderIDs.

Observing Functions

Interference or overloading of the radio transmission can prevent the reception of Fhem commands at the receiver. With the help of the observing function Fhem checks the reception of the acknowledgment telegrams of the actuator. If within one second no acknowledgment telegram is received, the last set command is sent again. The set command is repeated a maximum of 5 times. The maximum number can be specified in the attribute observeCmdRepetition.
The function can only be used if the actuator immediately after the reception of the set command sends an acknowledgment message.
The observing function is turned on by the Attribute observe. In addition, further devices can be monitored. The names of this devices can be entered in the observeRefDev attribute. If additional device are specified, the monitoring is stopped as soon as the first acknowledgment telegram of one of the devices was received (OR logic). If the observeLogic attribute is set to "and", the monitoring is stopped when a telegram was received by all devices (AND logic). Please note that the name of the own device has also to be entered in the observeRefDev if required.
If the maximum number of retries is reached and still no all acknowledgment telegrams has been received, the reading "observeFailedDev" shows the faulty devices and the command can be executed, that is stored in the observeErrorAction attribute.


Energy Management

• Demand Response (EEP A5-37-01)
Demand Response (DR) is a standard to allow utility companies to send requests for reduction in power consumption during peak usage times. It is also used as a means to allow users to reduce overall power comsumption as energy prices increase. The EEP was designed with a very flexible setting for the level (0...15) as well as a default level whereby the transmitter can specify a specific level for all controllers to use (0...100 % of either maximum or current power output, depending on the load type). The profile also includes a timeout setting to indicate how long the DR event should last if the DR transmitting device does not send heartbeats or subsequent new DR levels.
The DR actor controls the target actuators such as switches, dimmers etc. The DR actor is linked to the FHEM target actors via the attribute demandRespRefDev.

• Standard actions are available for the following profiles:
• switch (setting the switching command for min, max by the attribute demandRespMin, demandRespMax)
• gateway/switching (on, off)
• gateway/dimming (dim 0...100, relative to the max or current set value)
• lightCtrl.01 (dim 0...255)
• actuator.01 (dim 0...100)
• roomSensorControl.01 (setpoint 0...255)
• roomSensorControl.05 (setpoint 0...255 or nightReduction 0...5 for Eltako devices)
• roomCtrlPanel.00 (roomCtrlMode comfort|economy)
• On the target actuator can be specified alternatively a freely definable command. The command sequence is stored in the attribute demandRespAction. The command sequence can be designed similar to "notify". For the command sequence predefined variables can be used, eg. $LEVEL. This actions can be executed very flexible depending on the given energy reduction levels.
• Alternatively or additionally, a custom command sequence in the DR profile itself can be stored.
The profile has a master and slave mode.
• In slave mode, demand response data telegrams received eg a control unit of the power utility, evaluated and the corresponding commands triggered on the linked target actuators. The behavior in slave mode can be changed by multiple attributes.
• In master mode, the demand response level is set by set commands and thus sends a corresponding data telegram and the associated target actuators are controlled. The demand response control value are specified by "level", "power", "setpoint" "max" or "min". Each other settings are calculated proportionally. In normal operation, ie without power reduction, the control value (level) is 15. Through the optional parameters "powerUsageScale", "randomStart", "randomEnd" and "timeout" the control behavior can be customized. The threshold at which the reading "powerUsageLevel" between "min" and "max" switch is specified with the attribute demandRespThreshold.
Additional information about the profile itself can be found in the EnOcean EEP documentation.


Constant Light Controller

The constant light controller dims lamps depending on the ambient brightness. Two types of constant light controller are used.

For the closed loop control, the ambient brightness in the room itself is measured. This value is entered as an actual value in the control. The sensor must measure the brightness, for example, on the table top of the desk. For a stable control, changes in the brightness value by the outside light and the lamps must be detected immediately and at short intervals. Currently, the function of the closed loop control is not yet available in the EnOcean module.

In the case of open loop control, the lamps are dimmed linearly depending on the outside light. The brightness sensor must detect the outside brightness and must not be affected by the luminous flux of the lamps itself. The open loop control is switched on by

set <device> openLoopCtrl



The automatic control can be turned off by any other command. If the dimmaktor reports its stats, the control is also deactivated any manual input, for example on a wall switch.
The straight-line characteristic is determined via the attribute openLoopCtrlScale. Below and above the characteristic thresholds, the dimming values remain constant at the value of dimHigh or dimLow. The name of the brightness sensor must be specified in the brightnessRefDev attribute.
Currently, the constant light control is available for the gateway/dimming profile. More profiles will follow.


Remote Management

Remote Management allows EnOcean devices to be configured and maintained over the air. Thanks to Remote Management, sensors or switches IDs, for instance, can be stored or deleted from already installed actuators or gateways which are hard to access. Remote Management also allows querying debug information from the Remote Device and calling some manufacturer implemented functions.
Remote Management is performed by the Remote Manager, operated by the actor, on the managed Remote Device (Sensor, Gateway). The management is done through a series of commands and responding answers. Actor sends the commands to the Remote Device. Remote Device sends answers to the actor. The commands indicate the Remote Device what to do. Remote Device answers if requested by the command. The commands belong to one of the main use case categories, which are:
• Security
• Locate / indentify remote device
• Get status
• Extended function
The management is often done with a group of Remote Devices. Commands are sent as addressed unicast telegrams, usually. In special cases broadcast transmission is also available. To avoid telegram collisions the Remote Devices respond to broadcast commands with a random delay.
The Security, Locate, and Get Status options provide to the actor basic operability of Remote management. Their purpose is to ensure the proper work of Remote Management when operating with several Remote Devices. These functions behave in the same way on every Remote Device. Every product that supports Remote Management provides these options.
Extended functions provide the real benefit of Remote Management. They vary from Remote Device to Remote Device. They depend on how and where the Remote Device is used. Therefore, not every Remote Device provides every extended function. It depends on the programmer / customer what extended functions he wants to add. There is a list of specified commands, but the manufacturer can also add manufacturer specific extended functions. These functions are identified by the manufacturer ID.
More information can be found on the EnOcean websites.
Fhem operates primarily as a remote manager. For tests but also a client device can be created.

The remote manager function must be activated for the desired device by

attr <remote device name> remoteManagement manager



The remote client device must be defined as follows


define <client name> EnOcean C5-00-00


and has to by unlocked for t seconds

set <client name> unlock <t/s>


Only one remote management client device should be defined.

For security reasons the remote management commands can only be accessed in the unlock period. The period can be entered in two cases:
• Within 30min after device power-up if no CODE is set
• Within 30min after an unlock command with a correct 32bit security code is received
The unlock/lock period can be accessed only with the security code. The security code can be set whenever the Remote Device accepts remote management commands.
When the Remote Device is locked it does not respond to any command, but unlock and ping. When a wrong security code is received the Remote Device does not process unlock commands for a security period of 30 seconds.
Security code=0x000000 is the default value and has to be interpreted as: no CODE has been set. The actor can also set the security code to 0x000000 from a previously set value. If no security code is set, unlock after the unlock period is not processed. Only ping will be processed. Remote Management is not available until next power up. 0xFFFFFFFF is reserved and can not be used as security code.

To administrate a remote device whose Remote ID must be known. The Remote ID can be determined as follows:

attr <name> remoteManagement manager
power-up the remote device
get <name> remoteID


All commands are described in the remote management chapters of the set- and get-commands.

The Remote Management Function is configured using the following attributes:

• remoteCode
• remoteEEP
• remoteID
• remoteManagement
• remoteManufID

The content of events is described in the chapter Remote Management Events

. The following extended functions are supported:
• 210:remoteLinkTableInfo
• 211:remoteLinkTable
• 212:remoteLinkTable
• 213:remoteLinkTableGP
• 214:remoteLinkTableGP
• 220:remoteLearnMode
• 221:remoteTeach
• 224:remoteReset
• 225:remoteRLT
• 226:remoteApplyChanges
• 227:remoteProductID
• 230:remoteDevCfg
• 231:remoteDevCfg
• 232:remoteLinkCfg
• 233:remoteLinkCfg
• 240:remoteAck
• 250:remoteRepeater
• 251:remoteRepeater
• 252:remoteRepeaterFilter



Signal Telegram

Signal Telegram as a feature is dedicated to signalize special events with optional data, trigger actions or request responses. It extends the functionality of the device independently of used EEPs or other communication profiles.
Target key functional fields are:
• Communication flow control
• Energy harvesting and reporting
• Failure & issues reporting
• Radio link quality reporting
• Learn Mode Status
The Signal Telegram function commands are activated by the attribute signal. All commands are described in the signal telegram chapter of the get-commands. The content of events is described in the chapter Signal Telegram Events.


Radio Link Test

Units supporting the Radio Link Test (RLT) shall offer a functionality that allows for radio link testing between them (Position A to Position B, point-to-point only). Fhem support at least 1BS and 4BS test messages. When two units perform radio link testing one unit needs to act in a mode called RLT Master and the other unit needs to act in a mode called RLT Slave. Fhem acts as RLT Master (subType radioLinkTest).
The Radio Link Test device must be defined as follows


define <name> EnOcean A5-3F-00


and has to by activated

set <name> standby


Alternatively, the device can also be created automatically by autocreate. Only one RLT device may be defined in FHEM.
After activation the RLT Master listens for RLT Query messages. On reception of at least one RLT Query messsage the RLT Master responds and starts transmission of RLT MasterTest messages. After that the RLT Master awaits the response from the RLT Slave.
A radio link test communication consits of a minimum of 16 and a maximum of 256 RLT MasterTest messages. When the radio link test communication is completed the RLT Master gets deactivated automatically. The test results can be found in the log file.


Security features

The receiving and sending of encrypted messages is supported. This module currently allows the secure operating mode of a variety of sensors, PTM 210 / PTM 215 based switches and profiles gateway/switching and gateway/dimming.

To receive secured telegrams, you first have to start the teach in mode via

set <IODev> teach <t/s>

Since the beginning of 2021, the PTM 210 / PTM 215 modules offer a normal mode and two secure modes
• Implicit RLC (legacy, not recommended)
• Explicit RLC (recommended)


In the case of the Implicit RLC doing the following:

• Remove the switch cover of the module
• Press both nipples of one rocker side (A0 & AI or B0 & BI)
• While keeping the nipples pressed actuate the energy bow twice.


This generates two teach-in telegrams which create a Fhem device with the subType "switch.00" and synchronize the Fhem with the PTM 210 / PTM 215. Both the Fhem and the PTM210 / PTM 215 now maintain a counter which is used to generate a rolling code encryption scheme. Also during teach-in, a private key is transmitted to the Fhem. The counter value is allowed to desynchronize for a maximum of 128 counts, to allow compensating for missed telegrams, if this value is crossed you need to teach-in the PTM 215 again. Also if your Fhem installation gets erased including the state information, you need to teach in the PTM 210 / PTM 215 modules again (which you would need to do anyway).

In the case of the Explicit RLC doing the following:

• Remove the switch cover of the module
• Press any 3 nipples
• While keeping the nipples pressed actuate the energy bow twice.


In this mode, the PTM module sends the RLC value as part of every data telegram. With transmission of the RLC in every data telegram a desynchronization of the RLC counters between receivers and transmitter like described above cannot happen.

To send secured telegrams, you first have send a secure teach-in to the remode device


set <name> teachInSec


With the set <name> teachInSec command, all security and device parameters are transferred for the switch.00 profile.
For the gateway/switching and gateway/dimming profiles, the device profile must be taught in the second step using the set <name> teach command.

Please note that this encryption is unidirectional. The receipt telegrams of the actuators are not encrypted.

As for the security of this solution, if someone manages to capture the teach-in telegrams, he can extract the private key, so the added security isn't perfect but relies on the fact, that none listens to you setting up your installation.

The cryptographic functions need the additional Perl modules Crypt/Rijndael and Crypt/Random. The module must be installed manually. With the help of CPAN at the operating system level, for example,


/usr/bin/perl -MCPAN -e 'install Crypt::Rijndael'
/usr/bin/perl -MCPAN -e 'install Crypt::Random'



Define
define <name> EnOcean <DEF> [<EEP>]|getNextID|<EEP>

Define an EnOcean device, connected via a TCM modul. The <DEF> is the SenderID/DestinationID of the device (8 digit hex number), for example

define switch1 EnOcean FFC54500


In order to control devices, you cannot reuse the SenderIDs/ DestinationID of other devices (like remotes), instead you have to create your own, which must be in the allowed SenderID range of the underlying Fhem IO device, see TCM BaseID, LastID. For this first query the TCM with the get <tcm> baseID command for the BaseID. You can use up to 128 IDs starting with the BaseID shown there. If you are using an Fhem SenderID outside of the allowed range, you will see an ERR_ID_RANGE message in the Fhem log.
FHEM can assign a free SenderID alternatively, for example

define switch1 EnOcean getNextID


If the EEP is known, the appropriate device can be created with the basic parameters, for example

define sensor1 EnOcean FFC54500 A5-02-05


or

define sensor1 EnOcean A5-02-05


Inofficial EEP for special devices
• G5-07-01 PioTek-Tracker
  
• H5-07-01 Presence Sensor (Master)
  
• G5-10-12 Room Sensor and Control Unit [Eltako FUTH65D]
  
• G5-38-08 Gateway, Dimming [Eltako FSG, FUD]
  
• H5-38-08 Gateway, Dimming [Eltako TF61D, TF100D]
  
• I5-38-08 Gateway, Dimming [Eltako FUD14] secure and confirm teach-in supported
  
• J5-38-08 Gateway, Dimming [Eltako FUD61] secure, confirm and MSC teach-in supported
  
• M5-38-08 Gateway, Switching [Eltako FSR14] old version
  
• N5-38-08 Gateway, Switching [Eltako TF61L, TF61R, TF100A, TF100L]
  
• O5-38-08 Gateway, Switching [Eltako FSR14] secure and confirm teach-in supported
  
• P5-38-08 Gateway, Switching [Eltako FSR14M] secure and confirm teach-in supported
  In the second step, the automated meter reading electricity function must be taught in via Teach-In / Teach-Out.
  
• K5-38-08 Gateway, Switching [Eltako FSR61] secure and confirm teach-in supported
  
• G5-3F-7F Shutter [Eltako FSB]
  
• H5-3F-7F Shutter [Eltako TF61J]
  
• I5-3F-7F Shutter [Eltako FRM60] - MSC teach-in supported
  
• J5-3F-7F Wireless Analog Input Module [Thermokon SR65 3AI]
  
• G6-02-01 Pushbutton with controllable LEDs [Eltako F4CT55] - MSC teach-in supported
  
• L6-02-01 Smoke Detector [Eltako FRW]
  
• G5-ZZ-ZZ Light and Presence Sensor [Omnio Ratio eagle-PM101]
  
• ZZ-13-03 Environmental Applications, Data Exchange (EEP A5-13-03)
  
• ZZ-13-04 Environmental Applications, Time and Day Exchange (EEP A5-13-04)
  
• ZZ-ZZ-ZZ EnOcean RAW profile
  



The autocreate module may help you if the actor or sensor send acknowledge messages or teach-in telegrams. In order to control this devices e. g. switches with additional SenderIDs you can use the attributes subDef, subDef0 and subDefI.
Fhem communicates unicast, if bidirectional 4BS or UTE teach-in is used, see Bidirectional Teach-In / Teach-Out. In this case Fhem send unicast telegrams with its SenderID and the DestinationID of the device.


Internals
• DEF: 0000000 ... FFFFFFFF|<EEP>
  EnOcean DestinationID or SenderID
  If the attributes subDef* are set, this values are used as EnOcean SenderID.
  For an existing device, the device can be re-parameterized by entering the EEP.
  
• Dev_EURID: 0000000 ... FFFFFFFF
  EnOcean ChipID of the device
  
• Dev_RepeatingCounter: 0...2
  Number of forwardings by repeaters received by the device
  
• Dev_RSSImax: LP/dBm
  Largest field strength received by the device
  
• Dev_RSSImin: LP/dBm
  Smallest field strength received by the device
  
• Dev_SubTelNum: 1...15
  Number of sub telegrams received by the device
  
• <IODev>_DestinationID: 0000000 ... FFFFFFFF
  Received destination address, Broadcast radio: FFFFFFFF
  
• <IODev>_PacketType: 1 ... 255
  Number of the packet type of last data telegram received
  
• <IODev>_ReceivingQuality: excellent|good|bad
  excellent: RSSI >= -76 dBm (internal standard antenna sufficiently)
  good: RSSI < -76 dBm and RSSI >= -87 dBm (good antenna necessary)
  bad: RSSI < -87 dBm (repeater required)
  
• <IODev>_RepeatingCounter: 0...2
  Number of forwardings by repeaters
  
• <IODev>_RSSI: LP/dBm
  Received signal strength indication (best value of all received subtelegrams)
  
• <IODev>_SubTelNum: 1...15
  Number of sub telegrams received
  



Set
• Teach-In / Teach-Out
  • Teach-in remote devices
  
  set <IODev> teach <t/s>
  
  Set Fhem in the learning mode.
  A device, which is then also put in this state is to paired with Fhem. Bidirectional Teach-In / Teach-Out is used for some 4BS, VLD and MSC devices, e. g. EEP 4BS, RORG A5-20-01 (Battery Powered Actuator).
  Bidirectional Teach-In for 4BS, UTE and Generic Profiles are supported.
  IODev is the name of the TCM Module.
  t/s is the time for the learning period.
  
  Types of learning modes see learningMode
  
  Example:
  set TCM_0 teach 600
  
  
  • RPS profiles Teach-In (switches)
  
  set <name> A0|AI|B0|BI|C0|CI|D0|DI
  
  Send teach-in telegram to remote device.
  
  
  • 1BS profiles Teach-In (contact)
  
  set <name> teach
  
  Send teach-in telegram to remote device.
  
  
  • 4BS profiles Teach-In (sensors, dimmer, room controller etc.)
  
  set <name> teach
  
  Send teach-in telegram to remote device.
  If no SenderID (attr subDef) was assigned before a learning telegram is sent for the first time, a free SenderID is assigned automatically.
  
  
  • UTE - Universal Uni- and Bidirectional Teach-In
  
  set <name> teachIn|teachOut
  
  Send teach-in telegram to remote device.
  If no SenderID (attr subDef) was assigned before a learning telegram is sent for the first time, a free SenderID is assigned automatically.
  
  
  • Generic Profiles Teach-In
  
  set <name> teachIn|teachOut
  
  Send teach-in telegram to remote device.
  If no SenderID (attr subDef) was assigned before a learning telegram is sent for the first time, a free SenderID is assigned automatically.
  
  
  • Secure Devices Teach-In
  
  set <name> teachInSec
  
  Secure teach-in to the remode device.
  If no SenderID (attr subDef) was assigned before a learning telegram is sent for the first time, a free SenderID is assigned automatically.
  
  
• Smart Ack Learning
  • Teach-in remote Smart Ack devices
  
  set <IODev> smartAckLearn <t/s>
  
  Set Fhem in the Smart Ack learning mode.
  The post master fuctionality must be activated using the command smartAckMailboxMax in advance.
  The simple learnmode is supported, see smartAckLearnMode
  A device, which is then also put in this state is to paired with Fhem. Bidirectional learn in for 4BS, UTE and Generic Profiles are supported.
  IODev is the name of the TCM Module.
  t/s is the time for the learning period.
  
  Example:
  set TCM_0 smartAckLearn 600
  
  
• Remote Management
  set <name> <value>
  
  where value is
  • remoteAction
    sent action command to perfoms an action, depending on the functionality of the device
  • remoteApplyChanges devCfg|linkTable|no_change
    apply changes
  • remoteDevCfg <index> <value>
    set configuration
  • remoteLinkTable in|out <index> <ID> <EEP> <channel>
    set link table content
  • remoteLinkCfg in|out <index> <data index> <value>
    set link based configuration
  • remoteLinkTableGP in|out <index> <GP channel description>
    set link table content
  • remoteLock
    locks the remote device or local client
  • remoteLearnMode in|out|off <index>
    initiate remote learn-in or learn-out of inbound index
  • remoteReset devCfg|linkTableIn|linkTableOut|no_change
    reset to defaults
  • remoteRLT on|off <number of RLT slaves>
    reset to defaults
  • remoteRepeater on|off|filter <level> <filter structure>
    set repeater functions
  • remoteRepeaterFilter apply|block|delete|deleteAll destinationID|sourceID|rorg|rssi <filter value>
    set repeater functions
  • remoteSetCode
    set the remote security code
  • remoteTeach <channel>
    request teach-in telegram from channel 00..FF
  • remoteUnlock [1...1800]
    unlocks the remote device or local client
    The unlock period can be set in the client mode between 1s and 1800 s.
  
  [<channel>] = 00...FF
  [<EEP>] = <RORG>-<function>-<type>
  [<filter structure>] = AND|OR
  [<filter value>] = <destinationID>|<sourceID>|<RORG>|<LP/dBm>
  [<GP channel description>] = <name of channel 00>:<O|I>:<channel type>:<signal type>:<value type>[:<resolution>[:<engineering min>:<scaling min>:<engineering max>:<scaling max>]]
  [<ID>] = 00000001...FFFFFFFE
  [<index>] = 00...FF
  [<number of RLT slaves>] = 01..7F
  [<level>] = 1|2
  [<data index>] = 0000...FFFF
  [<value>] = n x 00...FF
  
  
  


• Switch, Pushbutton Switch (EEP F6-02-01 ... F6-03-02)
  RORG RPS [default subType]
  set <name> <value>
  
  where value is one of A0, AI, B0, BI, C0, CI, D0, DI, combinations of these and released. First and second action can be sent simultaneously. Separate first and second action with a comma.
  In fact we are trying to emulate a PT200 type remote.
  If you define an eventMap attribute with on/off, then you will be able to easily set the device from the WEB frontend.
  set extensions are supported, if the corresponding eventMap specifies the on and off mappings, for example attr eventMap on-till:on-till AI:on A0:off.
  With the help of additional attributes, the behavior of the devices can be adapt.
  The attr subType must be switch. This is done if the device was created by autocreate.
  
  Example:
  set switch1 BI
set switch1 B0,CI
attr eventMap BI:on B0:off
set switch1 on

  
  
• Staircase off-delay timer (EEP F6-02-01 ... F6-02-02)
  RORG RPS [Eltako FTN14, tested with Eltako FTN14 only]
  
  set <name> <value>
  
  where value is
  • on
    issue switch on command
  • released
    start timer
  
  Set attr eventMap to B0:on BI:off, attr subType to switch, attr webCmd to on:released and if needed attr switchMode to pushbutton manually.
  The attr subType must be switch. This is done if the device was created by autocreate.
  Use the sensor type "Schalter" for Eltako devices. The Staircase off-delay timer is switched on when pressing "on" and the time will be started when pressing "released". "released" immediately after "on" is sent if the attr switchMode is set to "pushbutton".



• Wireless 4-way colour pushbuttons display (EEP F6-02-01)
  [Eltako F4CT55]
  
  set <name> <value>
  
  where value is
  • colourAll <RRGGBB>
    set all colour displays to RGB value
  • colourA0 <RRGGBB>
    set colour display A0 to RGB value
  • colourAI <RRGGBB>
    set colour display AI to RGB value
  • colourB0 <RRGGBB>
    set colour display B0 to RGB value
  • colourBI <RRGGBB>
    set colour display BI to RGB value
  
  [RR] = 00 ... FF red color intensity in HEX notation
  [GG] = 00 ... FF green color intensity in HEX notation
  [BB] = 00 ... FF blue color intensity in HEX notation
  The attr subType must be set to switch, manufID to 00D and attr model to Eltako_F4CT55. This is done if the device was created by the Eltako MSC autocreate. However, the device can also be created with the help of the Inofficial EEP G6-02-01. If the released state is to be displayed after the end of a keystroke, set attr sensorMode to pushbutton manually.



• Pushbutton Switch (EEP D2-03-00)
  RORG VLD [EnOcean PTM 215 Modul]
  set <name> <value>
  
  where value is
  • teachIn
    initiate UTE teach-in
  • teachInSec
    initiate secure teach-in
  • teachOut
    initiate UTE teach-out
  • A0|AI|B0|BI
    issue switch command
  • A0,B0|A0,AI|AI,B0|AI,BI
    issue switch command
  • pressed
    energy bow pressed
  • pressed34
    3 or 4 buttons and energy bow pressed
  • released
    energy bow released
  
  
  First and second action can be sent simultaneously. Separate first and second action with a comma.
  If you define an eventMap attribute with on/off, then you will be able to easily set the device from the WEB frontend.
  set extensions are supported, if the corresponding eventMap specifies the on and off mappings, for example attr eventMap on-till:on-till AI:on A0:off.
  If comMode is set to biDir the device can be controlled bidirectionally.
  With the help of additional attributes, the behavior of the devices can be adapt.
  The attr subType must be switch.00. This is done if the device was created by autocreate.
  
  
  Example:
  set switch1 BI
set switch1 B0,CI
attr eventMap BI:on B0:off
set switch1 on

  
  
• Single Input Contact, Door/Window Contact (EEP D5-00-01)
  RORG 1BS [tested with Eltako FSR14]
  set <name> <value>
  
  where value is
  • closed
    issue closed command
  • open
    issue open command
  • teach
    initiate teach-in
  
  The attr subType must be contact. The attribute must be set manually. A monitoring period can be set for signOfLife telegrams of the sensor, see signOfLife and signOfLifeInterval. Default is "off" and an interval of 1980 sec.
  Set the manufID to 00D for Eltako devices that send a periodic voltage telegram. (For example TF-FKB)



• Occupancy Sensor (EEP A5-07-01)
  [Eltako FBH55SB]
  
  set <name> <value>
  
  where value is
  • teach
    initiate teach-in
  • on
    Motion detection is sent. With the attribute motionMode you can choose between the fully automatic and semi-automatic mode. Fully automatic is default. Semi-automatic motion detection is available in TF mode on the Eltako actuator.
  • fullyOn
    Fully automatic motion detection is sent.
  • semiOn
    Semi-automatic motion detection is sent. Switch-on takes place by the light sensor.
  • off
    No motion is sent.
  
  The current motion status can be set manually or will be taken from the motion reported by a motion reference device motionRefDev.
  If the attribute devUpdate is set to "auto", data telegrams with the current motion status are sent periodically.
  The profile behaves like a master or slave, see devMode.
  The attr subType must be occupSensor.01. The attribute must be set manually. The device can be fully defined via the Inofficial EEP H5-07-01.
  Set the attribute manufID to 00D for Eltako device function fullyOn and semiOn.



• Room Sensor and Control Unit (EEP A5-10-02)
  [Thermokon SR04 PTS]
  
  set <name> <value>
  
  where value is
  • teach
    initiate teach-in
  • setpoint [0 ... 255]
    Set the actuator to the specifed setpoint.
  • setpointScaled [<floating-point number>]
    Set the actuator to the scaled setpoint.
  • fanStage [auto|0|1|2|3]
    Set fan stage
  • switch [on|off]
    Set switch
  
  The actual temperature will be taken from the temperature reported by a temperature reference device temperatureRefDev primarily or from the attribute actualTemp if it is set.
  If the attribute setCmdTrigger is set to "refDev", a setpoint command is sent when the reference device is updated.
  The scaling of the setpoint adjustment is device- and vendor-specific. Set the attributes scaleMax, scaleMin and scaleDecimals for the additional scaled setting setpointScaled.
  The profile behaves like a master or slave, see devMode.
  The attr subType must be roomSensorControl.05. The attribute must be set manually.



• Room Sensor and Control Unit (EEP A5-10-03)
  [used for IntesisBox PA-AC-ENO-1i]
  
  set <name> <value>
  
  where value is
  • teach
    initiate teach-in
  • setpoint [0 ... 255]
    Set the actuator to the specifed setpoint.
  • setpointScaled [<floating-point number>]
    Set the actuator to the scaled setpoint.
  • fanStage [auto|0|1|2|3]
    Set fan stage
  • switch [on|off]
    Set switch
  
  The actual temperature will be taken from the temperature reported by a temperature reference device temperatureRefDev primarily or from the attribute actualTemp if it is set.
  If the attribute setCmdTrigger is set to "refDev", a setpoint command is sent when the reference device is updated.
  The scaling of the setpoint adjustment is device- and vendor-specific. Set the attributes scaleMax, scaleMin and scaleDecimals for the additional scaled setting setpointScaled.
  The profile behaves like a master or slave, see devMode.
  The attr subType must be roomSensorControl.05 and attr manufID must be 019. The attribute must be set manually.



• Room Sensor and Control Unit (A5-10-06 plus night reduction)
  [Eltako FTR65DS, FTR65HS]
  
  set <name> <value>
  
  where value is
  • teach
    initiate teach-in
  • desired-temp [t/°C [lock|unlock]]
    Set the desired temperature.
  • nightReduction [t/K [lock|unlock]]
    Set night reduction
  • setpointTemp [t/°C [lock|unlock]]
    Set the desired temperature
  
  The actual temperature will be taken from the temperature reported by a temperature reference device temperatureRefDev primarily or from the attribute actualTemp if it is set.
  If the attribute setCmdTrigger is set to "refDev", a setpointTemp command is sent when the reference device is updated.
  This profil can be used with a further Room Sensor and Control Unit Eltako FTR55* to control a heating/cooling relay FHK12, FHK14 or FHK61. If Fhem and FTR55* is teached in, the temperature control of the FTR55* can be either blocked or to a setpoint deviation of +/- 3 K be limited. For this use the optional parameter [block] = lock|unlock, unlock is default.
  The profile behaves like a master or slave, see devMode.
  A monitoring period can be set for signOfLife telegrams of the sensor, see signOfLife and signOfLifeInterval. Default is "off" and an interval of 1320 sec.
  The attr subType must be roomSensorControl.05 and attr manufID must be 00D. The attributes must be set manually.



• Room Sensor and Control Unit (EEP A5-10-10)
  [Thermokon SR04 * rH, Thanos SR *]
  
  set <name> <value>
  
  where value is
  • teach
    initiate teach-in
  • setpoint [0 ... 255]
    Set the actuator to the specifed setpoint.
  • setpointScaled [<floating-point number>]
    Set the actuator to the scaled setpoint.
  • switch [on|off]
    Set switch
  
  The actual temperature will be taken from the temperature reported by a temperature reference device temperatureRefDev primarily or from the attribute actualTemp if it is set.
  The actual humidity will be taken from the humidity reported by a humidity reference device humidityRefDev primarily or from the attribute humidity if it is set.
  If the attribute setCmdTrigger is set to "refDev", a setpoint command is sent when the reference device is updated.
  The scaling of the setpoint adjustment is device- and vendor-specific. Set the attributes scaleMax, scaleMin and scaleDecimals for the additional scaled setting setpointScaled.
  The profile behaves like a master or slave, see devMode.
  The attr subType must be roomSensorControl.01. The attribute must be set manually.



• Room Sensor and Control Unit (EEP A5-10-12)
  [Eltako FUTH65D]
  
  set <name> <value>
  
  where value is
  • teach
    initiate teach-in
  • setpoint [0 ... 255]
    Set the actuator to the specifed setpoint.
  • setpointScaled [<floating-point number>]
    Set the actuator to the scaled setpoint.
  • switch [on|off]
    Set switch
  
  The actual temperature will be taken from the temperature reported by a temperature reference device temperatureRefDev primarily or from the attribute actualTemp if it is set.
  If the attribute setCmdTrigger is set to "refDev", a setpoint command is sent when the reference device is updated.
  The profile behaves like a master or slave, see devMode.
  The attr subType must be roomSensorControl.01 and attr manufID must be 00D. The attribute must be set manually.



• Environmental Applications
  Data Exchange (EEP A5-13-03)
  Time and Day Exchange (EEP A5-13-04)
  
  set <name> <value>
  
  where value is
  • sendDate
    send a date telegram
  • sendTime
    send a time telegram
  • start
    start the periodic sending of the time
  • stop
    stop the periodic sending of the time
  • teachDate
    send the teach in telegram for date exchange
  • teachTime
    send the teach in telegram for time exchange
  
  The periodic interval is configured using the attribute:
  
  • sendTimePeriodic
  The attr subType must be environmentApp and devMode is set to master. This is done with the help of the inofficial EEPs ZZ-13-03 or ZZ-13-04. Type define EnOcean ZZ-13-04 getNextID manually.



• Battery Powered Actuator (EEP A5-20-01)
  [Kieback&Peter MD15-FTL-xx]
  
  set <name> <value>
  
  where value is
  • setpoint setpoint/%
    Set the actuator to the specifed setpoint (0...100). The setpoint can also be set by the setpointRefDev device if it is set.
  • setpointTemp t/°C
    Set the actuator to the specifed temperature setpoint. The temperature setpoint can also be set by the setpointTempRefDev device if it is set.
    The FHEM PID controller calculates the actuator setpoint based on the temperature setpoint. The controller's operation can be set via the PID parameters pidFactor_P, pidFactor_I and pidFactor_D.
    If the attribute pidCtrl is set to off, the PI controller of the actuator is used (selfCtrl mode). Please read the instruction manual of the device, whether the device has an internal PI controller.
    
  • runInit
    Maintenance Mode: Run init sequence
  • valveOpens
    Maintenance Mode: Valve opens
    After the valveOpens command, the valve remains open permanently and can no longer be controlled by Fhem. By pressing the button on the device itself, the actuator is returned to its normal operating state.
  • valveCloses
    Maintenance Mode: Valve closes
  
  The Heating Radiator Actuating Drive is configured using the following attributes:
  
  • pidActorCallBeforeSetting
  • pidActorErrorAction
  • pidActorErrorPos
  • pidActorLimitLower
  • pidActorTreshold
  • pidCtrl
  • pidDeltaTreshold
  • pidFactor_P
  • pidFactor_I
  • pidFactor_D
  • pidIPortionCallBeforeSetting
  • pidSensorTimeout
  • rcvRespAction
  • setpointRefDev
  • setpointSummerMode
  • setpointTempRefDev
  • summerMode
  • temperatureRefDev
  The actual temperature will be reported by the Heating Radiator Actuating Drive or by the temperatureRefDev if it is set. The internal temperature sensor of the Micropelt iTRV MVA-002 is not suitable as an actual temperature value for the PID controller. An external room thermostat is required.
  The attr event-on-change-reading .* shut not by set. The PID controller expects periodic events. If these are missing, a communication alarm is signaled.
  The attr subType must be hvac.01. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Teach-In / Teach-Out.
  The command is not sent until the device wakes up and sends a message, usually every 10 minutes.



• Heating Radiator Actuating Drive (EEP A5-20-04)
  [Holter SmartDrive MX]
  
  set <name> <value>
  
  where value is
  • setpoint setpoint/%
    Set the actuator to the specifed setpoint (0...100). The setpoint can also be set by the setpointRefDev device if it is set.
  • setpointTemp t/°C
    Set the actuator to the specifed temperature setpoint. The temperature setpoint can also be set by the setpointTempRefDev device if it is set.
    The FHEM PID controller calculates the actuator setpoint based on the temperature setpoint. The controller's operation can be set via the PID parameters pidFactor_P, pidFactor_I and pidFactor_D.
  • runInit
    Maintenance Mode: Run init sequence
  • valveOpens
    Maintenance Mode: Valve opens
    After the valveOpens command, the valve remains open permanently and can no longer be controlled by Fhem. By pressing the button on the device itself, the actuator is returned to its normal operating state.
  • valveCloses
    Maintenance Mode: Valve closes
  
  The Heating Radiator Actuating Drive is configured using the following attributes:
  
  • blockKey
  • displayOrientation
  • measurementCtrl
  • model
  • pidActorCallBeforeSetting
  • pidActorErrorAction
  • pidActorErrorPos
  • pidActorLimitLower
  • pidActorLimitUpper
  • pidActorTreshold
  • pidCtrl
  • pidDeltaTreshold
  • pidFactor_P
  • pidFactor_I
  • pidFactor_D
  • pidIPortionCallBeforeSetting
  • pidSensorTimeout
  • rcvRespAction
  • setpointRefDev
  • setpointSummerMode
  • setpointTempRefDev
  • summerMode
  • temperatureRefDev
  • wakeUpCycle
  The actual temperature will be reported by the Heating Radiator Actuating Drive or by the temperatureRefDev if it is set.
  The attr event-on-change-reading .* shut not by set. The PID controller expects periodic events. If these are missing, a communication alarm is signaled.
  The attr subType must be hvac.04. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Teach-In / Teach-Out.
  The OEM version of the Holter SmartDrive MX has an internal PID controller. This function is activated by attr model Holter_OEM and attr pidCtrl off.
  The command is not sent until the device wakes up and sends a message, usually every 5 minutes.



• Heating Radiator Actuating Drive (EEP A5-20-06)
  [Micropelt iTRV MVA-005, OPUS Micropelt HOME]
  
  set <name> <value>
  
  where value is
  • runInit
    Maintenance Mode: Run init sequence
  • setpoint setpoint/%
    Set the actuator to the specifed setpoint (0...100). The setpoint can also be set by the setpointRefDev device if it is set.
  • setpointTemp t/°C
    Set the actuator to the specifed temperature setpoint. The temperature setpoint can also be set by the setpointTempRefDev device if it is set.
    The FHEM PID controller calculates the actuator setpoint based on the temperature setpoint. The controller's operation can be set via the PID parameters pidFactor_P, pidFactor_I and pidFactor_D.
  • standby
    enter standby mode
    After the standby command, the valve remains closed permanently and can no longer be controlled by Fhem. By pressing the button on the device itself, the actuator is returned to its normal operating state.
  
  The Heating Radiator Actuating Drive is configured using the following attributes:
  
  • blockKey
  • measurementTypeSelect
  • model
  • pidActorCallBeforeSetting
  • pidActorErrorAction
  • pidActorErrorPos
  • pidActorLimitLower
  • pidActorTreshold
  • pidCtrl
  • pidDeltaTreshold
  • pidFactor_P
  • pidFactor_I
  • pidFactor_D
  • pidIPortionCallBeforeSetting
  • pidSensorTimeout
  • rcvRespAction
  • setpointRefDev
  • setpointSummerMode
  • setpointTempRefDev
  • temperatureRefDev
  • summerMode
  • wakeUpCycle
  • windowOpenCtrl
  The actual temperature will be reported by the Heating Radiator Actuating Drive or by the temperatureRefDev if it is set.
  The attr event-on-change-reading .* shut not by set. The PID controller expects periodic events. If these are missing, a communication alarm is signaled.
  The attr subType must be hvac.06. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Teach-In / Teach-Out.
  The actuator has an internal PID controller. This function is activated by attr pidCtrl off.
  The command is not sent until the device wakes up and sends a message, usually every 2 to 10 minutes.



• Generic HVAC Interface (EEP A5-20-10)
  [IntesisBox PA-AC-ENO-1i]
  
  set <name> <value>
  
  where value is
  • ctrl auto|0...100
    Set control variable
  • fanSpeed auto|1...14
    Set fan speed
  • occupancy occupied|off|standby|unoccupied
    Set room occupancy
  • on
    Set on
  • off
    Set off
  • mode auto|heat|morning_warmup|cool|night_purge|precool|off|test|emergency_heat|fan_only|free_cool|ice|max_heat|eco|dehumidification|calibration|emergency_cool|emergency_stream|max_cool|hvc_load|no_load|auto_heat|auto_cool
    Set mode
  • teach
    Teach-in
  • vanePosition auto|horizontal|position_2|position_3|position_4|vertical|swing|vertical_swing|horizontal_swing|hor_vert_swing|stop_swing
    Set vane position
  
  The attr subType must be hvac.10. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Teach-In / Teach-Out.



• Generic HVAC Interface - Error Control (EEP A5-20-11)
  [IntesisBox PA-AC-ENO-1i]
  
  set <name> <value>
  
  where value is
  • externalDisable disable|enable
    Set external disablement
  • remoteCtrl disable|enable
    Dieable/enable remote controller
  • teach
    Teach-in
  • window closed|opened
    Set window state
  
  The attr subType must be hvac.11. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Teach-In / Teach-Out.



• Energy management, demand response (EEP A5-37-01)
  demand response master commands
  
  set <name> <value>
  
  where value is
  • level 0...15 [<powerUsageScale> [<randomStart> [<randomEnd> [timeout]]]]
    set demand response level
  • max [<powerUsageScale> [<randomStart> [<randomEnd> [timeout]]]]
    set power usage level to max
  • min [<powerUsageScale> [<randomStart> [<randomEnd> [timeout]]]]
    set power usage level to min
  • power power/% [<powerUsageScale> [<randomStart> [<randomEnd> [timeout]]]]
    set power
  • setpoint 0...255 [<powerUsageScale> [<randomStart> [<randomEnd> [timeout]]]]
    set setpoint
  • teach
    initiate teach-in
  
  [<powerUsageScale>] = max|rel, [<powerUsageScale>] = max is default
  [<randomStart>] = yes|no, [<randomStart>] = no is default
  [<randomEnd>] = yes|no, [<randomEnd>] = no is default
  [timeout] = 0/min | 15/min ... 3825/min, [timeout] = 0 is default
  The attr subType must be energyManagement.01.
  This is done if the device was created by autocreate.
  



• Gateway (EEP A5-38-08)
  The Gateway profile include 7 different commands (Switching, Dimming, Setpoint Shift, Basic Setpoint, Control variable, Fan stage, Blind Central Command). The commands can be selected by the attribute gwCmd or command line. The attribute entry has priority.
  
  set <name> <value>
  
  where value is
  • <gwCmd> <cmd> [subCmd]
    initiate Gateway commands by command line
  • <cmd> [subCmd]
    initiate Gateway commands if attribute gwCmd is set.
  
  The attr subType must be gateway. Attribute gwCmd can also be set to switching|dimming|setpointShift|setpointBasic|controlVar|fanStage|blindCmd.
  This is done if the device was created by autocreate.
  For Eltako devices attributes must be set manually.



• Gateway (EEP A5-38-08)
  Switching
  [Eltako FLC61, FSA12, FSR14]
  
  set <name> <value>
  
  where value is
  • teach
    initiate teach-in mode
  • teachInSec
    initiate secure teach-in
  • on [lock|unlock]
    issue switch on command
  • off [lock|unlock]
    issue switch off command
  • set extensions are supported.
  
  The attr subType must be gateway and gwCmd must be switching. This is done if the device was created by autocreate.
  For Eltako devices attributes must be set manually. For Eltako FSA12 attribute model must be set to Eltako_FSA12.



• Gateway (EEP A5-38-08)
  Dimming
  [Eltako FUD12, FUD14, FUD61, FUD70, FSG14, ...]
  
  set <name> <value>
  
  where value is
  • dim/% [rampTime/s [lock|unlock]]
    issue dim command
  • teach
    initiate teach-in mode
  • teachInSec
    initiate secure teach-in
  • on [lock|unlock]
    issue switch on command
  • off [lock|unlock]
    issue switch off command
  • dim dim/% [rampTime/s [lock|unlock]]
    issue dim command
  • dimup dim/% [rampTime/s [lock|unlock]]
    issue dim command
  • dimdown dim/% [rampTime/s [lock|unlock]]
    issue dim command
  • set extensions are supported.
  
  rampTime Range: t = 1 s ... 255 s or 0 if no time specified, for Eltako: t = 1 = fast dimming ... 255 = slow dimming or 0 = dimming speed on the dimmer used
  The attr subType must be gateway and gwCmd must be dimming. This is done if the device was created by autocreate.
  For Eltako devices this attributes must be set manually. In addition, the attribute manufID must be set with 00D. Alternatively, the Eltako device can be fully defined using the inofficial EEPs G5-38-08, H5-38-08, I5-38-08 or J5-38-08. Use the sensor type "PC/FVS" for Eltako devices.



• Gateway (EEP A5-38-08)
  Dimming of fluorescent lamps
  [Eltako FSG70, tested with Eltako FSG70 only]
  
  set <name> <value>
  
  where value is
  • on
    issue switch on command
  • off
    issue switch off command
  • set extensions are supported.
  
  The attr subType must be gateway and gwCmd must be dimming. Set attr eventMap to B0:on BI:off, attr subTypeSet to switch and attr switchMode to pushbutton manually.
  Use the sensor type "Richtungstaster" for Eltako devices.



• Gateway (EEP A5-38-08)
  Setpoint shift
  [untested]
  
  set <name> <value>
  
  where value is
  • teach
    initiate teach-in mode
  • shift 1/K
    issue Setpoint shift
  
  Shift Range: T = -12.7 K ... 12.8 K
  The attr subType must be gateway and gwCmd must be setpointShift. This is done if the device was created by autocreate.
  



• Gateway (EEP A5-38-08)
  Basic Setpoint
  [untested]
  
  set <name> <value>
  
  where value is
  • teach
    initiate teach-in mode
  • basic t/°C
    issue Basic Setpoint
  
  Setpoint Range: t = 0 °C ... 51.2 °C
  The attr subType must be gateway and gwCmd must be setpointBasic. This is done if the device was created by autocreate.
  



• Gateway (EEP A5-38-08)
  Control variable
  [untested]
  
  set <name> <value>
  
  where value is
  • teach
    initiate teach-in mode
  • presence present|absent|standby
    issue Room occupancy
  • energyHoldOff normal|holdoff
    issue Energy hold off
  • controllerMode auto|heating|cooling|off
    issue Controller mode
  • controllerState auto|override <0 ... 100>
    issue Control variable override
  
  Override Range: cvov = 0 % ... 100 %
  The attr subType must be gateway and gwCmd must be controlVar. This is done if the device was created by autocreate.
  



• Gateway (EEP A5-38-08)
  Fan stage
  [untested]
  
  set <name> <value>
  
  where value is
  • teach
    initiate teach-in mode
  • stage 0 ... 3|auto
    issue Fan Stage override
  
  The attr subType must be gateway and gwCmd must be fanStage. This is done if the device was created by autocreate.
  



• Gateway (EEP A5-38-08)
  Blind Command Central
  [not fully tested]
  
  set <name> <value>
  
  where value is
  • position/% [α/°]
    drive blinds to position with angle value
  • teach
    initiate teach-in mode
  • status
    Status request
  • opens
    issue blinds opens command
  • up tu/s ta/s
    issue roll up command
  • closes
    issue blinds closes command
  • down td/s ta/s
    issue roll down command
  • position position/% [α/°]
    drive blinds to position with angle value
  • stop
    issue blinds stops command
  • runtimeSet tu/s td/s
    set runtime parameter
  • angleSet ta/s
    set angle configuration
  • positionMinMax positionMin/% positionMax/%
    set min, max values for position
  • angleMinMax αo/° αs/°
    set slat angle for open and shut position
  • positionLogic normal|inverse
    set position logic
  
  Runtime Range: tu|td = 0 s ... 255 s
  Select a runtime up and a runtime down that is at least as long as the shading element or roller shutter needs to move from its end position to the other position.
  Position Range: position = 0 % ... 100 %
  Angle Time Range: ta = 0 s ... 25.5 s
  Runtime value for the sunblind reversion time. Select the time to revolve the sunblind from one slat angle end position to the other end position.
  Slat Angle: α|αo|αs = -180 ° ... 180 °
  Position Logic, normal: Blinds fully opens corresponds to Position = 0 %
  Position Logic, inverse: Blinds fully opens corresponds to Position = 100 %
  The attr subType must be gateway and gwCmd must be blindCmd.
  See also attributes sendDevStatus and serviceOn
  The profile is linked with controller profile, see Blind Status.
  



• Extended Lighting Control (EEP A5-38-09)
  [untested]
  
  set <name> <value>
  
  where value is
  • teach
    initiate remote teach-in
  • on
    issue switch on command
  • off
    issue switch off command
  • dim dim [rampTime/s]
    issue dim command
  • dimup rampTime/s
    issue dim command
  • dimdown rampTime/s
    issue dim command
  • stop
    stop dimming
  • rgb <red color value><green color value><blue color value>
    issue color value command
  • scene drive|store 0..15
    store actual value in the scene or drive to scene value
  • dimMinMax <min value> <max value>
    set minimal and maximal dimmer value
  • lampOpHours 0..65535
    set the operation hours of the lamp
  • block unlock|on|off|local
    locking local operations
  • meteringValues 0..65535 mW|W|kW|MW|Wh|kWh|MWh|GWh|mA|mV
    set a new value for the energy metering (overwrite the actual value with the selected unit)
  • meteringValues 0..6553.5 A|V
    set a new value for the energy metering (overwrite the actual value with the selected unit)
  • set extensions are supported.
  
  color values: 00 ... FF hexadecimal
  rampTime Range: t = 1 s ... 65535 s or 1 if no time specified, ramping time can be set by attribute rampTime
  The attr subType or subTypSet must be lightCtrl.01. This is done if the device was created by autocreate.
  The subType is associated with the subtype lightCtrlState.02.



• Manufacturer Specific Applications (EEP A5-3F-7F)
  Shutter
  [Eltako FSB12, FSB14, FSB61, FSB70]
  
  set <name> <value>
  
  where value is
  • position/% [α/°]
    drive blinds to position with angle value
  • anglePos α/°
    drive blinds to angle value
  • closes
    issue blinds closes command
  • down td/s
    issue roll down command
  • opens
    issue blinds opens command
  • position position/% [α/°]
    drive blinds to position with angle value
  • stop
    issue stop command
  • teach
    initiate teach-in mode
  • up tu/s
    issue roll up command
  
  Run-time Range: tu|td = 1 s ... 255 s
  Position Range: position = 0 % ... 100 %
  Slat Angle Range: α = -180 ° ... 180 °
  Angle Time Range: ta = 0 s ... 6 s
  The devive can only fully controlled if the attributes angleMax, angleMin, angleTime, shutTime and shutTimeCloses, are set correctly. If settingAccuracy is set to high, the run-time is sent in 1/10 increments.
  Set attr subType to manufProfile, manufID to 00D and attr model to Eltako_FSB14|FSB61|FSB70|FSB_ACK manually. If the attribute model is set to Eltako_FSB_ACK, with the status "open_ack" the readings position and anglePos are also updated.
  If the attribute calAtEndpoints is to yes, the roller blind positions are calibrated when the endpoints are driven.
  Use the sensor type "Szenentaster/PC" for Eltako devices.



• Manufacturer Specific Applications (EEP A5-3F-7F)
  Shutter
  [Eltako FRM60]
  
  set <name> <value>
  
  where value is
  • position/%
    drive blinds to position
  • closes
    issue blinds closes command
  • opens
    issue blinds opens command
  • position position/% [high|low [lock|unlock]]
    drive blinds to position with rotation speed and lock key option
  • stop
    issue stop command
  • teach
    initiate teach-in
  
  [position] = 0 % ... 100 %
  The parameters rotation speed can be set permanently with the help of the attribute rotationSpeed
  . The attr subType must be set to manufProfile, manufID to 00D and attr model to Eltako_FRM60. This is done if the device was created by the Eltako MSC autocreate. However, the device can also be created with the help of the Inofficial EEP I5-3F-7F and then taught in the actuator. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out.
  



• Manufacturer Specific Applications (EEP A5-3F-7F)
  
  Wireless Analog Input Module
  [Thermokon SR65 3AI, untested]
  
  set <name> <value>
  
  where value is
  • input1 U/V
    set input1 (Range: U = 0 V ... 10 V)
  • input1Scaled [<floating-point number>]
    set input1Scaled
  • input2 U/V
    set input2 (Range: U = 0 V ... 10 V)
  • input2Scaled [<floating-point number>]
    set input2Scaled
  • input3 U/V
    set input3 (Range: U = 0 V ... 10 V)
  • input3Scaled [<floating-point number>]
    set input3Scaled
  • teach
    initiate teach-in
  
  The input value can be scaled device-specifically. Set the attributes scaleMax, scaleMin and scaleDecimals for the additional scaled setting input<channel>Scaled.
  The attr subType must be manufProfile and attr manufID must be 002 for Thermokon Devices. This is done manually via the Inofficial EEP J5-3F-7F.



• Electronic switches and dimmers with Energy Measurement and Local Control (D2-01-00 - D2-01-14)
  [Telefunken Funktionsstecker, PEHA Easyclick, AWAG Elektrotechnik AG Omnio UPS 230/xx,UPD 230/xx, REGS12/08M, NodOn in-wall module, smart plug]
  
  set <name> <value>
  
  where value is
  • autoOffTime t/s [<channel>]
    set auto Off timer
  • delayOffTime t/s [<channel>]
    set delay Off timer
  • dim/% [<channel> [<rampTime>]]
    issue dimming command
  • extSwitchMode unavailable|switch|pushbutton|auto [<channel>]
    set external interface mode
  • extSwitchType toggle|direction [<channel>]
    set external interface type
  • on [<channel>]
    issue switch on command
  • off [<channel>]
    issue switch off command
  • dim dim/% [<channel> [<rampTime>]]
    issue dimming command
  • local dayNight day|night, day is default
    set the user interface indication
  • local defaultState on|off|last, off is default
    set the default setting of the output channels when switch on
  • local localControl enabled|disabled, enabled is default
    enable the local control of the device
  • local overCurrentShutdown off|restart, off is default
    set the behavior after a shutdown due to an overcurrent
  • local overCurrentShutdownReset not_active|trigger, not_active is default
    trigger a reset after an overcurrent
  • local powerFailure enabled|disabled, disabled is default
    enable the power failure detection
  • local rampTime<1...3> 0/s, 0.5/s ... 7/s, 7.5/s, 0 is default
    set the dimming time of timer 1 ... 3
  • local teachInDev enabled|disabled, disabled is default
    enable the taught-in devices with different EEP
  • measurement delta 0/s ... 4095/s, 0 is default
    define the difference between two displayed measurements
  • measurement mode energy|power, energy is default
    define the measurand
  • measurement report query|auto, query is default
    specify the measurement method
  • measurement reset not_active|trigger, not_active is default
    resetting the measured values
  • measurement responseTimeMax 10/s ... 2550/s, 10 is default
    set the maximum time between two outputs of measured values
  • measurement responseTimeMin 1/s ... 255/s, 1 is default
    set the minimum time between two outputs of measured values
  • measurement unit Ws|Wh|KWh|W|KW, Ws is default
    specify the measurement unit
  • roomCtrlMode off|comfort|comfort-1|comfort-2|economy|buildingProtection
    set pilot wire mode
  • special repeater off|1|2
    set repeater level of device (additional NodOn command)
  
  [autoOffTime] = 0 s ... 0.1 s ... 6553.4 s
  [delayOffTime] = 0 s ... 0.1 s ... 6553.4 s
  [channel] = 0...29|all|input, all is default
  The default channel can be specified with the attr defaultChannel.
  [rampTime] = 1..3|switch|stop, switch is default
  The attr subType must be actuator.01. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out.



• Blind Control for Position and Angle (D2-05-00, D2-05-01, D2-05-02, D2-05-04, D2-05-05)
  [AWAG Elektrotechnik AG OMNIO UPJ 230/12, REGJ12/04M, miniJ01]
  
  set <name> <value>
  
  where value is
  • opens [<channel>]
    issue blinds opens command
  • closes [<channel>]
    issue blinds closes command
  • position position/% [[α/%] [[<channel>] [directly|opens|closes]]]
    drive blinds to position with angle value
  • anglePos α/% [<channel>]
    drive blinds to angle value
  • stop [<channel>]
    issue stop command
  • alarm [<channel>]
    set actuator to the "alarm" mode. When the actuator ist set to the "alarm" mode neither local nor central positioning and configuration commands will be executed. Before entering the "alarm" mode, the actuator will execute the "alarm action" as configured by the attribute alarmAction
  • lock [<channel>]
    set actuator to the "blockade" mode. When the actuator ist set to the "blockade" mode neither local nor central positioning and configuration commands will be executed.
  • unlock [<channel>]
    issue unlock command
  
  Channel Range: 1 ... 4|all, default is all
  Position Range: position = 0 % ... 100 %
  Slat Angle Range: α = 0 % ... 100 %
  The devive can only fully controlled if the attributes alarmAction, angleTime, reposition and shutTime are set correctly.
  With the attribute defaultChannel the default channel can be specified.
  The attr subType must be blindsCtrl.00 or blindsCtrl.01. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out.



• Multisensor Windows Handle (D2-06-01)
  [Soda GmbH]
  
  set <name> <value>
  
  where value is
  • presence absent|present
    set vacation mode
  • handleClosedClick disable|enable
    set handle closed click feature
  • batteryLowClick disable|enable
    set battery low click feature
  • teachSlave contact|windowHandleClosed|windowHandleOpen|windowHandleTilted
    sent teach-in to the slave devices (contact: EEP: D5-00-01, windowHandle: EEP F6-10-00)
    The events window or handle will get forwarded once a slave-device contact or windowHandle is taught in.
  • updateInterval t/s
    set sensor update interval
  • blinkInterval t/s
    set vacation blink interval
  
  sensor update interval Range: updateInterval = 5 ... 65535
  vacation blick interval Range: blinkInterval = 3 ... 255
  The multisensor window handle is configured using the following attributes:
  
  • subDefH
  • subDefW
  The attr subType must be multisensor.01. This is done if the device was created by autocreate.



• Room Control Panels (D2-10-00 - D2-10-02)
  [Kieback & Peter RBW322-FTL]
  
  set <name> <value>
  
  where value is
  • buildingProtectionTemp t/°C
    set building protection temperature
  • clearCmds [<channel>]
    clear waiting commands
  • comfortTemp t/°C
    set comfort temperature
  • config
    Setting the configuration of the room controller, the configuration parameters are set using attributes.
  • cooling auto|off|on|no_change
    switch cooling
  • deleteTimeProgram
    delete time programs of the room controller
  • desired-temp t/°C
    set setpoint temperature
  • economyTemp t/°C
    set economy temperature
  • fanSpeed fanspeed/%
    set fan speed
  • fanSpeedMode central|local
    set fan speed mode
  • heating auto|off|on|no_change
    switch heating
  • preComfortTemp t/°C
    set pre comfort temperature
  • roomCtrlMode buildingProtectionTemp|comfortTemp|economyTemp|preComfortTemp
    select setpoint temperature
  • setpointTemp t/°C
    set current setpoint temperature
  • time
    set time and date of the room controller
  • timeProgram
    set time programms of the room contoller
  • window closed|open
    put the window state
  
  Setpoint Range: t = 0 °C ... 40 °C
  The room controller is configured using the following attributes:
  
  • blockDateTime
  • blockDisplay
  • blockFanSpeed
  • blockMotion
  • blockProgram
  • blockOccupancy
  • blockTemp
  • blockTimeProgram
  • blockSetpointTemp
  • daylightSavingTime
  • displayContent
  • pollInterval
  • temperatureScale
  • timeNotation
  • timeProgram[1-4]
  The attr subType must be roomCtrlPanel.00. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out.



• Room Control Panels (D2-11-01 - D2-11-08)
  [Thermokon EasySens SR06 LCD-2T/-2T rh -4T/-4T rh]
  
  set <name> <value>
  
  where value is
  • cooling on|off, default [colling] = off
    set cooling symbol at the display
  • desired-temp t/°C
    set setpoint temperature
  • fanSpeed auto|off|1|2|3
    set fan speed
  • heating on|off, default [heating] = off
    set heating symbol at the display
  • occupancy occupied|unoccupied
    set occupancy state
  • setpointTemp t/°C
    set current setpoint temperature
  • setpointShiftMax t/K
    set setpoint shift max
  • setpointType setpointTemp|setpointShift
    set setpoint type
  • window closed|open, default [window] = closed
    set window open symbol at the display
  
  Setpoint Range: t = 5 °C ... 40 °C
  Setpoint Shift Max Range: t = 0 K ... 10 K
  The attr subType must be roomCtrlPanel.01. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired by Smart Ack, see SmartAck Learning.



• Fan Control (D2-20-00 - D2-20-02)
  [Maico ECA x RC/RCH, ER 100 RC, untested]
  
  set <name> <value>
  
  where value is
  • on
    fan on
  • off
    fan off
  • desired-temp [t/°C]
    set setpoint temperature
  • fanSpeed fanspeed/%|auto|default
    set fan speed
  • humidityThreshold rH/%
    set humidity threshold
  • roomSize 0...350/m²|default|not_used
    set room size
  • setpointTemp [t/°C]
    set current setpoint temperature
  
  Setpoint Range: t = 0 °C ... 40 °C
  The fan controller is configured using the following attributes:
  
  • setCmdTrigger
  • switchHysteresis
  • temperatureRefDev
  The attr subType must be fanCtrl.00. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out. The profile behaves like a master. Only one fan can be taught as a slave.



• Heating Actuator (D2-34-00 - D2-34-02)
  [AWAG UPS230/10, UPS230/12, REGH12/08M]
  
  set <name> <value>
  
  where value is
  • setpointTemp t/°C [<channel> [<overrideTime/h>]]
    set the temperatur setpoint
  • setpointTempRefDev [<channel>]
    enable the temperature setpoint via room control unit
  • setpointTempShift t/K [<channel> [<overrideTime/h>]]
    set the temperatur setpoint shift
  
  [setpointTemp] t = 0 °C ... 40 °C
  [setpointTempShift] t = Range: t = -10 K ... 10 K
  [channel] = 0...29|all, all is default
  The default channel can be specified with the attr defaultChannel.
  [overrideTime] = 0 h ... 63 h, 0 is default (endless)
  Duration of the override until fallback to the room control panel setpointTemp value. The attr subType must be heatingActuator.00. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out.



• Heat Recovery Ventilation (D2-50-00 - D2-50-11)
  [untested]
  
  set <name> <value>
  
  where value is
  • ventilation off|1...4|auto|demand|supplyAir|exhaustAir
    select ventilation mode/level
  • heatExchangerBypass opens|closes
    override of automatic heat exchanger bypass control
  • startTimerMode
    enable timer operation mode
  • CO2Threshold default|1/%
    override CO2 threshold for CO2 control in automatic mode
  • humidityThreshold default|rH/%
    override humidity threshold for humidity control in automatic mode
  • airQuatityThreshold default|1/%
    override air qualidity threshold for air qualidity control in automatic mode
  • roomTemp default|t/°C
    override room temperature threshold for room temperature control mode
  
  roomTemp Range: t = -63 °C ... 63 °C
  xThreshold Range: 0 % ... 100 %
  The attr subType must be heatRecovery.00. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out.



• Valve Control (EEP D2-A0-01)
  
  set <name> <value>
  
  where value is
  • closes
    issue closes command (master)
  • opens
    issue opens command (master)
  • closed
    issue closed command (slave)
  • open
    issue open command (slave)
  • teachIn
    initiate UTE teach-in (slave)
  • teachOut
    initiate UTE teach-out (slave)
  
  The valve controller is configured using the following attributes:
  
  • devMode
  The attr subType must be valveCtrl.00. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out. The profile behaves like a master or slave, see devMode.



• Generic Profiles
  
  set <name> <value>
  
  where value is
  • <00 ... 64>-<channel name> <value>
    set channel value
  • channelName <channel number>-<channel name>
    rename channel
  • teachIn
    sent teach-in telegram
  • teachOut
    sent teach-out telegram
  
  The generic profile device is configured using the following attributes:
  
  • comMode
  • devMode
  • gpDef
  • manufID
  The attr subType must be genericProfile. This is done if the device was created by autocreate. If the profile in slave mode is operated, especially the channel definition in the gpDef attributes must be entered manually.



• RAW Command
  
  set <name> <value>
  
  where value is
  • 1BS|4BS|GPCD|GPSD|GPTI|GPTR|MSC|RPS|UTE|VLD data [status]
    sent data telegram
  
  [data] = <1-byte hex ... 512-byte hex>
  [status] = 0x00 ... 0xFF
  With the help of this command data messages in hexadecimal format can be sent. Telegram types (RORG) 1BS, 4BS, RPS, MSC, UTE, VLD, GPCD, GPSD, GPTI and GPTR are supported. For further information, see EnOcean Equipment Profiles (EEP) and Generic Profiles.



• Radio Link Test
  
  set <name> <value>
  
  where value is
  • standby|stop
    set RLT Master state
  
  The Radio Link Test device is configured using the following attributes:
  
  • rltRepeat
  • rltType
  The attr subType must be readioLinkTest. This is done if the device was created by autocreate or manually by define <name> EnOcean A5-3F-00
  .

Get

• Remote Management
  get <name> <value>
  
  where value is
  • remoteDevCfg <start data index> <end data index>
    get device configuration between start index and end index
  • remoteFunctions
    get a list of the supported extended functions
  • remoteID
    get the remote device ID
  • remoteLinkTableInfo
    query supported link table info
  • remoteLinkCfg in|out <index> <start data index> <end data index> <length>
    get link table between start index and end index
  • remoteLinkTable in|out <start index> <end index>
    get link table between start index and end index
  • remoteLinkTableGP in|out <index>
    get link table GP entry with index
  • remotePing
    get a ping response from the remote device
  • remoteProductID
    query product ID
  • remoteRepeater
    asks for the repeater status of the remote device
  • remoteStatus
    asks for the status info of the remote device
  
  [<data index>] = 0000...FFFF
  [<index>] = 00...FF
  [<length>] = n x 00...FF
  



• Signal Telegram
  get <name> <value>
  
  where value is
  • signal energy
    get the energy status
  • signal revision
    get the revision of the device
  • signal RXlevel
    get the RX level of receiced request
  • signal harvester
    get the energy current harvested reporting
  
  Trigger status messages of the device.



• Dual Channel Switch Actuator (EEP A5-11-05)
  [untested]
  
  get <name> <value>
  
  where value is
  • status
    status request
  
  The attr subType or subTypSet must be switch.05. This is done if the device was created by autocreate.



• Extended Lighting Control (EEP A5-38-09)
  [untested]
  
  get <name> <value>
  
  where value is
  • status
    status request
  
  The attr subType or subTypSet must be lightCtrl.01. This is done if the device was created by autocreate.
  The subType is associated with the subtype lightCtrlState.02.



• Electronic switches and dimmers with Energy Measurement and Local Control (D2-01-00 - D2-01-12)
  [Telefunken Funktionsstecker, PEHA Easyclick, AWAG Elektrotechnik AG Omnio UPS 230/xx,UPD 230/xx, NodOn in-wall module, smart plug]
  
  get <name> <value>
  
  where value is
  • roomCtrlMode
    get pilot wire mode
  • settings [<channel>]
    get external interface settings
  • status [<channel>]
    
  • measurement <channel> energy|power
    
  • special <channel> health|load|voltage|serialNumber
    additional Permondo SmartPlug PSC234 commands
  • special <channel> firmwareVersion|reset|taughtInDevID|taughtInDevNum
    additional NodOn commands
  
  The default channel can be specified with the attr defaultChannel.
  The attr subType must be actuator.01. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out.



• Blind Control for Position and Angle (D2-05-00, D2-05-01, D2-05-02, D2-05-04, D2-05-05)
  [AWAG Elektrotechnik AG OMNIO UPJ 230/12, REGJ12/04M, miniJ01]
  
  get <name> <value>
  
  where value is
  • position [<channel>]
    query position and angle value
  
  Channel Range: 1 ... 4|all, default is all
  The devive can only fully controlled if the attributes alarmAction, angleTime, reposition and shutTime are set correctly.
  With the attribute defaultChannel the default channel can be specified.
  The attr subType must be blindsCtrl.00 or blindsCrtl.01. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out.



• Multisensor Windows Handle (D2-06-01)
  [Soda GmbH]
  
  get <name> <value>
  
  where value is
  • config
    get configuration settings
  • log
    get log data
  
  The multisensor window handle is configured using the following attributes:
  
  • subDefH
  • subDefW
  The attr subType must be multisensor.01. This is done if the device was created by autocreate.



• Room Control Panels (D2-10-00 - D2-10-02)
  [Kieback & Peter RBW322-FTL]
  
  get <name> <value>
  
  where value is
  • config
    get the configuration of the room controler
  • data
    get data
  • roomCtrl
    get the parameter of the room controler
  • timeProgram
    get the time program
  
  The attr subType must be roomCtrlPanel.00. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out.



• Fan Control (D2-20-00 - D2-20-02)
  [Maico ECA x RC/RCH, ER 100 RC, untested]
  
  get <name> <value>
  
  where value is
  • status
    get the state of the room controler
  
  The attr subType must be fanCtrl.00. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out.



• Heating Actuator (D2-34-00 - D2-34-02)
  [AWAG UPS230/10, UPS230/12, REGH122/08M]
  
  get <name> <value>
  
  where value is
  • setpoint [<channel>]
    get the setpoint infos of the heating actuator
  • status [<channel>]
    get the state of the heating actuator
  
  The attr subType must be heatingActuator.00. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out.



• Heat Recovery Ventilation (D2-50-00 - D2-50-11)
  [untested]
  
  get <name> <value>
  
  where value is
  • basicState
    get the basic state
  • extendedState
    get the extended state
  
  The attr subType must be heatRecovery.00. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out.



• Valve Control (EEP D2-A0-01)
  
  get <name> <value>
  
  where value is
  • state
    get the state of the valve controler (master)
  
  The attr subType must be valveCtrl.00. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out. The profile behaves like a master or slave, see devMode.

Attributes

• actualTemp t/°C
  The value of the actual temperature, used by a Room Sensor and Control Unit or when controlling HVAC components e. g. Battery Powered Actuators (MD15 devices). Should by filled via a notify from a distinct temperature sensor.
  If absent, the reported temperature from the HVAC components is used.
• alarmAction <channel1>[:<channel2>[:<channel3>[:<channel4>]]]
  [alarmAction] = no|stop|opens|closes, default is no
  Action that is executed before the actuator is entering the "alarm" mode.
  Notice subType blindsCrtl.00, blindsCrtl.01: The attribute can only be set while the actuator is online.
• alwaysUpdateReadings 0|1, [alwaysUpdateReadings] = 0 is default.
  The readings of the device are always updated if alwaysUpdateReadings is set.
• angleMax αs/°, [αs] = -180 ... 180, 90 is default.
  Slat angle end position maximum.
  angleMax is supported for shutter.
• angleMin αo/°, [αo] = -180 ... 180, -90 is default.
  Slat angle end position minimum.
  angleMin is supported for shutter.
• angleTime <channel1>[:<channel2>[:<channel3>[:<channel4>]]]
  subType blindsCtrl.00, blindsCtrl.01: [angleTime] = 0|0.01 .. 2.54, 0 is default.
  subType manufProfile: [angleTime] = 0 ... 6, 0 is default.
  Runtime value for the sunblind reversion time. Select the time to revolve the sunblind from one slat angle end position to the other end position.
  Notice subType blindsCrtl.00: The attribute can only be set while the actuator is online.
• blockDateTime yes|no, [blockDateTime] = no is default.
  blockDateTime is supported for roomCtrlPanel.00.
• blockDisplay yes|no, [blockDisplay] = no is default.
  blockDisplay is supported for roomCtrlPanel.00.
• blockFanSpeed yes|no, [blockFanSpeed] = no is default.
  blockFanSpeed is supported for roomCtrlPanel.00.
• blockKey yes|no, [blockKey] = no is default.
  blockKey is supported for roomCtrlPanel.00 and hvac.04.
• blockMotion yes|no, [blockMotion] = no is default.
  blockMotion is supported for roomCtrlPanel.00.
• blockOccupancy yes|no, [blockOccupancy] = no is default.
  blockOccupancy is supported for roomCtrlPanel.00.
• blockTemp yes|no, [blockTemp] = no is default.
  blockTemp is supported for roomCtrlPanel.00.
• blockTimeProgram yes|no, [blockTimeProgram] = no is default.
  blockTimeProgram is supported for roomCtrlPanel.00.
• blockSetpointTemp yes|no, [blockSetpointTemp] = no is default.
  blockSetPointTemp is supported for roomCtrlPanel.00.
• blockUnknownMSC yes|no, [blockUnknownMSC] = no is default.
  If the structure of the MSC telegrams can not interpret the raw data to be output. Setting this attribute to yes, the output can be suppressed.
• brightnessDayNight E_min/lx:E_max/lx, [brightnessDayNight] = 0...99000:0...99000, 10:20 is default.
  Set switching thresholds for reading dayNight based on the reading brightness.
• brightnessDayNightCtrl custom|sensor, [brightnessDayNightCtrl] = custom|sensor, sensor is default.
  Control the dayNight reading through the device-specific or custom threshold and delay.
• brightnessDayNightDelay t_reset/s:t_set/s, [brightnessDayNightDelay] = 0...99000:0...99000, 600:600 is default.
  Set switching delay for reading dayNight based on the reading brightness. The reading dayNight is reset or set if the thresholds are permanently undershot or exceed during the delay time.
• brightnessRefDev <name>
  Name of the device whose reference value is read. The reference values is the reading brightness.
• brightnessSunny E_min/lx:E_max/lx, [brightnessSunny] = 0...99000:0...99000, 20000:40000 is default.
  Set switching thresholds for reading isSunny based on the reading brightness.
• brightnessSunnyDelay t_reset/s:t_set/s, [brightnessSunnyDelay] = 0...99000:0...99000, 120:30 is default.
  Set switching delay for reading isSunny based on the reading brightness. The reading isSunny is reset or set if the thresholds are permanently undershot or exceed during the delay time.
• brightnessSunnyEast E_min/lx:E_max/lx, [brightnessSunny] = 0...99000:0...99000, 20000:40000 is default.
  Set switching thresholds for reading isSunnyEast based on the reading sunEast.
• brightnessSunnyEastDelay t_reset/s:t_set/s, [brightnessSunnyDelay] = 0...99000:0...99000, 120:30 is default.
  Set switching delay for reading isSunnyEast based on the reading sunEast. The reading isSunnyEast is reset or set if the thresholds are permanently undershot or exceed during the delay time.
• brightnessSunnySouth E_min/lx:E_max/lx, [brightnessSunny] = 0...99000:0...99000, 20000:40000 is default.
  Set switching thresholds for reading isSunnySouth based on the reading sunSouth.
• brightnessSunnySouthDelay t_reset/s:t_set/s, [brightnessSunnyDelay] = 0...99000:0...99000, 120:30 is default.
  Set switching delay for reading isSunnySouth based on the reading sunSouth. The reading isSunnySouth is reset or set if the thresholds are permanently undershot or exceed during the delay time.
• brightnessSunnyWest E_min/lx:E_max/lx, [brightnessSunny] = 0...99000:0...99000, 20000:40000 is default.
  Set switching thresholds for reading isSunnyWest based on the reading sunWest.
• brightnessSunnyWestDelay t_reset/s:t_set/s, [brightnessSunnyDelay] = 0...99000:0...99000, 120:30 is default.
  Set switching delay for reading isSunnyWest based on the reading sunWest. The reading isSunnyWest is reset or set if the thresholds are permanently undershot or exceed during the delay time.
• calAtEndpoints no|yes, [calAtEndpoints] = no is default
  Callibrize shutter position at the endpoints. The shutter motor is switched on with the time of shutTimeCloses if the end positions are selected.
• comMode biDir|confirm|uniDir, [comMode] = uniDir is default.
  Communication Mode between an enabled EnOcean device and Fhem.
  Unidirectional communication means a point-to-multipoint communication relationship. The EnOcean device e. g. sensors does not know the unique Fhem SenderID.
  If the attribute is set to confirm Fhem awaits confirmation telegrams from the remote device.
  Bidirectional communication means a point-to-point communication relationship between an enabled EnOcean device and Fhem. It requires all parties involved to know the unique Sender ID of their partners. Bidirectional communication needs a teach-in / teach-out process, see Bidirectional Teach-In / Teach-Out.
• customCmdAlarmOff <command>
  customCmdAlarmOn <command>
  Command being executed if an alarm is set (on) or deleted (off). If <command> is enclosed in {}, then it is a perl expression, if it is enclosed in "", then it is a shell command, else it is a "plain" fhem.pl command (chain). In the <command> you can access the name of the device by using $NAME, $TYPE and the current readings
  $BRIGHTNESS, $DAYNIGHT, $HEMISPHERE, $ISRAINING, $ISSTORMY, $ISSUNNY, $ISSUNNYEAST, $ISSUNNYSOUTH", $ISSUNNYWEST, $ISWINDY, $NAME, $SUNEAST, $SUNSOUTH, $SUNWEST, $TEMPERATURE, $TYPE, $WINDSPEED, $WINDSTENGTH.
  The eventMap replacements are taken into account. This data is available as a local variable in perl, as environment variable for shell scripts, and will be textually replaced for Fhem commands.
  The alarm commands have a higher priority than the up and down commands.
• customCmdDown <command>
  customCmdUp <command>
  The command is executed if the Up or Down command is triggered, see customCmdDownTrigger or customCmdUpTrigger. If <command> is enclosed in {}, then it is a perl expression, if it is enclosed in "", then it is a shell command, else it is a "plain" fhem.pl command (chain). In the <command> you can access the name of the device by using $NAME, $TYPE and the current readings
  $BRIGHTNESS, $DAYNIGHT, $HEMISPHERE, $ISRAINING, $ISSTORMY, $ISSUNNY, $ISSUNNYEAST, $ISSUNNYSOUTH", $ISSUNNYWEST, $ISWINDY, $NAME, $SUNEAST, $SUNSOUTH, $SUNWEST, $TEMPERATURE, $TYPE, $WINDSPEED, $WINDSTENGTH.
  The eventMap replacements are taken into account. This data is available as a local variable in perl, as environment variable for shell scripts, and will be textually replaced for Fhem commands.
  The alarm commands have a higher priority than the up and down commands.
• customCmdDownPeriod once|threeTimes|3|10|180|600
  customCmdUpPeriod once|threeTimes|3|10|180|600
  [customCmdDownPeriod] = once|threeTimes|3|10|180|600, once is default.
  Number or period of custom command to be executed.
• customCmdDownTrigger dayNight|isRaining|isStormy|isSunny|isSunnyEast|isSunnySouth|isSunnyWest|isWindy
  The commands in the attribute customCmdDown are executed if one of the selected readings is triggered as follows:
  • [dayNight] = night
  • [isRaining] = no
  • [isStormy] = no
  • [isSunny] = yes
  • [isSunnyEast] = yes
  • [isSunnySouth] = yes
  • [isSunnyWest] = yes
  • [isWindy] = no
  The commands in the attribute customCmdDown are executed periodically every second if the attribute is not set.
• customCmdUpTrigger dayNight|isRaining|isStormy|isSunny|isSunnyEast|isSunnySouth|isSunnyWest|isWindy
  The commands in the attribute customCmdUp are executed if one of the selected readings is triggered as follows:
  • [dayNight] = day
  • [isRaining] = yes
  • [isStormy] = yes
  • [isSunny] = no
  • [isSunnyEast] = no
  • [isSunnySouth] = no
  • [isSunnyWest] = no
  • [isWindy] = yes
  The commands in the attribute customCmdUp are executed periodically every second if the attribute is not set.
• customCmdPriority down|up, [customCmdPriority] = down|up, up is default.
  Priority of custom commands. If both the up and down command are triggered, only the prioritized command is executed.
• dataEnc VAES|AES-CBC, [dataEnc] = VAES is default
  Data encryption algorithm
• defaultChannel <channel> subType actuator.01: [defaultChannel] = all|input|0 ... 29, all is default.
  subType blindsCtrl.00, blindsCtrl.01: [defaultChannel] = all|1 ... 4, all is default.
  Default device channel
• daylightSavingTime supported|not_supported, [daylightSavingTime] = supported is default.
  daylightSavingTime is supported for roomCtrlPanel.00.
• demandRespAction <command>
  Command being executed after an demand response command is set. If <command> is enclosed in {}, then it is a perl expression, if it is enclosed in "", then it is a shell command, else it is a "plain" fhem.pl command (chain). In the <command> you can access the demand response readings $TYPE, $NAME, $LEVEL, $SETPOINT, $POWERUSAGE, $POWERUSAGESCALE, $POWERUSAGELEVEL, $STATE. In addition, the variables $TARGETNAME, $TARGETTYPE, $TARGETSTATE can be used if the action is executed on the target device. This data is available as a local variable in perl, as environment variable for shell scripts, and will be textually replaced for Fhem commands.
• demandRespMax A0|AI|B0|BI|C0|CI|D0|DI, [demandRespMax] = B0 is default
  Switch command which is executed if the demand response switches to a maximum.
• demandRespMin A0|AI|B0|BI|C0|CI|D0|DI, [demandRespMax] = BI is default
  Switch command which is executed if the demand response switches to a minimum.
• demandRespRefDev <name>
  
• demandRespRandomTime t/s [demandRespRandomTime] = 1 is default
  Maximum length of the random delay at the start or end of a demand respose event in slave mode.
• demandRespThreshold 0...15 [demandRespTheshold] = 8 is default
  Threshold for switching the power usage level between minimum and maximum in the master mode.
• demandRespTimeoutLevel max|last [demandRespTimeoutLevel] = max is default
  Demand response timeout level in slave mode.
• devChannel 00 ... FF, [devChannel] = FF is default
  Number of the individual device channel, FF = all channels supported by the device
• destinationID multicast|unicast|00000001 ... FFFFFFFF, [destinationID] = multicast is default
  Destination ID, special values: multicast = FFFFFFFF, unicast = [DEF]
• devMode master|slave, [devMode] = master is default.
  device operation mode.
• devUpdate auto|off, [devUpdate] = auto is default.
  device status update mode.
• devStateIcon
• dimMax dim/%|off, [dimMax] = 255 is default.
  maximum brightness value
  dimMax is supported for the profile gateway/dimming.
• dimMin dim/%|off, [dimMax] = off is default.
  minimum brightness value
  If [dimMax] = off, then the actuator takes down the ramp time set there. dimMin is supported for the profile gateway/dimming.
• dimValueOn dim/%|last|stored, [dimValueOn] = 100 is default.
  Dim value for the command "on".
  The dimmer switched on with the value 1 % ... 100 % if [dimValueOn] = 1 ... 100.
  The dimmer switched to the last dim value received from the bidirectional dimmer if [dimValueOn] = last.
  The dimmer switched to the last Fhem dim value if [dimValueOn] = stored.
  dimValueOn is supported for the profile gateway/dimming.
• disable 0|1
  If applied set commands will not be executed.
• disabledForIntervals HH:MM-HH:MM HH:MM-HH-MM...
  Space separated list of HH:MM tupels. If the current time is between the two time specifications, set commands will not be executed. Instead of HH:MM you can also specify HH or HH:MM:SS. To specify an interval spawning midnight, you have to specify two intervals, e.g.:
  23:00-24:00 00:00-01:00
• displayContent humidity|off|setpointTemp|temperatureExtern|temperatureIntern|time|default|no_change, [displayContent] = no_change is default.
  displayContent is supported for roomCtrlPanel.00.
• displayOrientation rad/°, [displayOrientation] = 0|90|180|270, 0 is default.
  Display orientation of the actuator
• do_not_notify
• eep <00...FF>-<00...3F>-<00...7F>
  EnOcean Equipment Profile (EEP)
• eventMap
• gpDef <name of channel 00>:<O|I>:<channel type>:<signal type>:<value type>[:<resolution>[:<engineering min>:<scaling min>:<engineering max>:<scaling max>]] ... <name of channel 64>:<O|I>:<channel type>:<signal type>:<value type>[:<resolution>[:<engineering min>:<scaling min>:<engineering max>:<scaling max>]]
  Generic Profiles channel definitions are set automatically in master mode. If the profile in slave mode is operated, the channel definition must be entered manually. For each channel, the channel definitions are to be given in ascending order. The channel parameters to be specified in decimal. First, the outgoing channels (direction = O) are to be defined, then the incoming channels (direction = I) should be described. The channel numbers are assigned automatically starting with 00th.
• gwCmd switching|dimming|setpointShift|setpointBasic|controlVar|fanStage|blindCmd
  Gateway Command Type, see Gateway profile
• humidity rH/%
  The value of the actual humidity, used by a Room Sensor and Control Unit. Should by filled via a notify from a distinct humidity sensor.
• humidityRefDev <name>
  Name of the device whose reference value is read. The reference values is the reading humidity.
• ignore
• IODev EnOcean IODev name
• keyRcv <private key 16 byte hex>
  Private Key for receive direction
• keySnd <private key 16 byte hex>
  Private Key for send direction
• macAlgo no|3|4
  MAC Algorithm
• manufID <000 ... 7FF>
  Manufacturer ID number
• measurementCtrl enable|disable
  Enable or disable the temperature measurements of the actuator. If the temperature measurements are turned off, the foot temperature may be displayed and an external temperature sensor must be exists, see attribute temperatureRefDev.
• measurementTypeSelect foot|room
  Select the temperature measurements type displayed by the actuator. If the temperature measurements are turned to foot, the foot temperature may be displayed and an external temperature sensor must be exists, see attribute temperatureRefDev.
• model
• motionMode fully|semi, [motionMode] = fully is default.
  Fully automatic or semi automatic motion detection
• motionRefDev <name>
  Name of the device whose reference value is read. The reference values is the reading motion.
• observe off|on, [observe] = off is default.
  Observing and repeating the execution of set commands
• observeCmdRepetition 1..5, [observeCmdRepetition] = 2 is default.
  Maximum number of command retries
• observeErrorAction <command>
  Command being executed after an error. If <command> is enclosed in {}, then it is a perl expression, if it is enclosed in "", then it is a shell command, else it is a "plain" fhem.pl command (chain). In the <command> you can access the set command. $TYPE, $NAME, $FAILEDDEV, $EVENT, $EVTPART0, $EVTPART1, $EVTPART2, etc. contains the space separated set parts. The eventMap replacements are taken into account. This data is available as a local variable in perl, as environment variable for shell scripts, and will be textually replaced for Fhem commands.
• observeInterval 1/s ... 255/s, [observeInterval] = 1 is default.
  Interval between two observations
• observeLogic and|or, [observeLogic] = or is default.
  Observe logic
• observeRefDev <name> [<name> [<name>]], [observeRefDev] = <name of the own device> is default
  Names of the devices to be observed. The list must be separated by spaces.
• openLoopCtrlScale <dimHigh>:<brightness1> <dimLow>:<brightness2>, [openLoopCtrlScale] = 100:100 0:0 is default.
  Bases of the straight-line characteristic of the open loop control dimming function.
• pidActorCallBeforeSetting, [pidActorCallBeforeSetting] = not defined is default
  Callback-function, which can manipulate the actorValue. Further information see modul PID20.
• pidActorErrorAction freeze|errorPos, [pidActorErrorAction] = freeze is default
  required action on error
• pidActorErrorPos valvePos/%, [pidActorErrorPos] = 0...100, 0 is default
  actor's position to be used in case of error
• pidActorLimitLower valvePos/%, [pidActorLimitLower] = 0...100, 0 is default
  lower limit for actor
• pidActorLimitUpper valvePos/%, [pidActorLimitUpper] = 0...100, 100 is default
  upper limit for actor
• pidActorTreshold valvePos/%, [pidActorTreshold] = 1...100, 1 is default
  actor treshold
• pidCtrl on|off, [pidCtrl] = on is default
  Activate the Fhem PID regulator
• pidDeltaTreshold <floating-point number>, [pidDeltaTreshold] = 0 is default
  if delta < delta-threshold the pid will enter idle state
• pidFactor_P <floating-point number>, [pidFactor_P] = 25 is default
  P value for PID
• pidFactor_I <floating-point number>, [pidFactor_I] = 0.25 is default
  I value for PID
• pidFactor_D <floating-point number>, [pidFactor_D] = 0 is default
  D value for PID
• pidIPortionCallBeforeSetting [pidIPortionCallBeforeSetting] = not defined is default
  Callback-function, which can manipulate the value of I-Portion. Further information see modul PID20.
• pidSensorTimeout t/s [pidSensorTimeout] = 3600 is default
  number of seconds to wait before sensor temperatureRefDev will be recognized n/a
• pollInterval t/s, [pollInterval] = 10 is default.
  [pollInterval] = 1 ... 1440.
  pollInterval is supported for roomCtrlPanel.00.
• rampTime t/s or relative, [rampTime] = 1 is default.
  No ramping or for Eltako dimming speed set on the dimmer if [rampTime] = 0.
  Gateway/dimmung: Ramping time 1 s to 255 s or relative fast to low dimming speed if [rampTime] = 1 ... 255.
  lightCtrl.01: Ramping time 1 s to 65535 s
  rampTime is supported for gateway, command dimming and lightCtrl.01.
• readingFnAttributes
• rcvRespAction <command>
  Command being executed after an message from the aktor is received and before an response message is sent. If <command> is enclosed in {}, then it is a perl expression, if it is enclosed in "", then it is a shell command, else it is a "plain" fhem.pl command (chain). In the <command> you can access the name of the device by using $NAME and the current readings
  $ACTUATORSTATE, $BATTERY, $COVER, $ENERGYINPUT, $ENERGYSTORAGE, $MAINTENANCEMODE, $OPERATIONMODE, $ROOMTEMP, $SELFCTRL, $SETPOINT, $SETPOINTTEMP, $SUMMERMODE, $TEMPERATURE, $WINDOW for the subType hvac.01,
  $NAME, $BATTERY, $FEEDTEMP, $MAINTENANCEMODE, $OPERATIONMODE, $ROOMTEMP, $SETPOINT, $SETPOINTTEMP, $SUMMERMODE, $TEMPERATURE for the subType hvac.04 and
  $ACTUATORSTATE, $BATTERY, $ENERGYINPUT, $ENERGYSTORAGE, $FEEDTEMP, $MAINTENANCEMODE, $OPERATIONMODE, $RADIOCOMERR, $RADIOSIGNALSTRENGTH, $ROOMTEMP, $SETPOINT, $SETPOINTTEMP, $SETPOINTTEMPLOCAL, $SUMMERMODE, $TEMPERATURE, $WINDOW for the subType hvac.06. This data is available as a local variable in perl, as environment variable for shell scripts, and will be textually replaced for Fhem commands.
• remoteCode <00000000...FFFFFFFE>
  Remote Management Security Code, 00000000 is interpreted as on code has been set.
• remoteEEP <00...FF>-<00...3F>-<00...7F>
  Remote Management EnOcean Equipment Profile (EEP)
• remoteID <00000001...FFFFFFFE>
  Remote Management Remote Device ID
• remoteManagement client|manager|off, [remoteManagement] = off is default.
  Enable Remote Management for the device.
• remoteManufID <000...7FF>
  Remote Management Manufacturer ID
• repeatingAllowed yes|no, [repeatingAllowed] = yes is default.
  EnOcean Repeater in the transmission range of Fhem may forward data messages of the device, if the attribute is set to yes.
• releasedChannel A|B|C|D|I|0|auto, [releasedChannel] = auto is default.
  Attribute releasedChannel determines via which SenderID (subDefA ... subDef0) the command released is sent. If [releasedChannel] = auto, the SenderID the last command A0, AI, B0, BI, C0, CI, D0 or DI is used. Attribute releasedChannel is supported for attr switchType = central and attr switchType = channel.
• reposition directly|opens|closes, [reposition] = directly is default.
  Attribute reposition specifies how to adjust the internal positioning tracker before going to the new position.
• rlcAlgo 2++|3++|4++|no
  RLC Algorithm
• rlcRcv <rolling code 2 or 3 byte hex>
  Rolling Code for receive direction
• rlcSnd <rolling code 2 or 3 byte hex>
  Rolling Code for send direction
• rlcTX false|true
  Rolling Code is expected in the received telegram
• rltRepeat 16|32|64|128|256, [rltRepeat] = 16 is default.
  Number of RLT MasterTest messages sent
• rltType 1BS|4BS, [rltType] = 4BS is default.
  Type of RLT MasterTest message
• rotationSpeed high|low, [rotationSpeed] = high is default.
  Rotation Speed
• scaleDecimals 0 ... 9
  Decimal rounding with x digits of the scaled reading setpoint
• teachMethod 1BS|4B|confirm|GP|RPS|smartAck|STE|UTE
  teach-in method
• scaleMax <floating-point number>
  Scaled maximum value of the reading setpoint
• scaleMin <floating-point number>
  Scaled minimum value of the reading setpoint
• secLevel encapsulation|encryption|off, [secLevel] = off is default
  Security level of the data
• secMode rcv|snd|biDir
  Telegram direction, which is secured
• sendDevStatus no|yes, [sendDevStatus] = no is default.
  Send new status of the device.
• sendTimePeriodic t/s|off, [sendTimePeriodic] = off | 1 ... 86400, 600 is default.
  Time period of time telegrams.
• sensorMode switch|pushbutton, [sensorMode] = switch is default.
  The status "released" will be shown in the reading state if the attribute is set to "pushbutton".
• serviceOn no|yes, [serviceOn] = no is default.
  Device in Service Mode.
• setCmdTrigger man|refDev, [setCmdTrigger] = man is default.
  Operation mode to send set commands
  If the attribute is set to "refDev", a device-specific set command is sent when the reference device is updated. For the subType "roomSensorControl.05" and "fanCrtl.00" the reference "temperatureRefDev" is supported.
  For the subType "roomSensorControl.01" the references "humidityRefDev" and "temperatureRefDev" are supported.
  
• setpointRefDev <name>
  Name of the device whose reference value is read. The reference values is the reading setpoint.
• setpointSummerMode valvePos/%, [setpointSummerMode] = 0...100, 0 is default
  Valve position in summer operation
• setpointTempRefDev <name>
  Name of the device whose reference value is read. The reference values is the reading setpointTemp.
• settingAccuracy high|low, [settingAccuracy] = low is default.
  set setting accurancy.
• showtime
• shutTime <channel1>[:<channel2>[:<channel3>[:<channel4>]]]
  subType blindsCtrl.00, blindsCtrl.01: [shutTime] = 5 ... 300, 300 is default.
  subType manufProfile: [shutTime] = 1 ... 255, 255 is default.
  Use the attr shutTime to set the time delay to the position "Halt" in seconds. Select a delay time that is at least as long as the shading element or roller shutter needs to move from its end position to the other position.
  Notice subType blindsCrtl.00: The attribute can only be set while the actuator is online.
• shutTimeCloses t/s, [shutTimeCloses] = 1 ... 255, [shutTimeCloses] = [shutTime] is default.
  Set the attr shutTimeCloses to define the runtime used by the commands opens and closes. Select a runtime that is at least as long as the value set by the delay switch of the actuator.
  shutTimeCloses is supported for shutter.
• signal off|on, [signal] = off is default.
  Activate the request functions of signal telegram messages.
• signOfLife off|on, [signOfLife] = off is default.
  Monitoring signOfLife telegrams from sensors.
• signOfLifeInterval 1...65535
  Monitoring period in seconds for signOfLife telegrams from sensors.
• subDef <EnOcean SenderID>, [subDef] = [DEF] is default.
  SenderID (TCM BaseID + offset) to control a bidirectional switch or actor.
  In order to control devices that send acknowledge telegrams, you cannot reuse the ID of this devices, instead you have to create your own, which must be in the allowed ID-Range of the underlying IO device. For this first query the TCM with the "get <tcm> idbase" command. You can use up to 128 IDs starting with the base shown there.
  If [subDef] = getNextID FHEM can assign a free SenderID alternatively. The system configuration needs to be reloaded. The assigned SenderID will only displayed after the system configuration has been reloaded, e.g. Fhem command rereadcfg.
• subDefA <EnOcean SenderID>, [subDefA] = [subDef] is default.
  SenderID (TCM BaseID + offset) for [value] = A0|AI|released
  Used with switch type "channel". Set attr switchType to channel.
  subDefA is supported for switches.
  Second action is not sent.
  If [subDefA] = getNextID FHEM can assign a free SenderID alternatively. The assigned SenderID will only displayed after the system configuration has been reloaded, e.g. Fhem command rereadcfg.
• subDefB <EnOcean SenderID>, [subDefB] = [subDef] is default.
  SenderID (TCM BaseID + offset) for [value] = B0|BI|released
  Used with switch type "channel". Set attr switchType to channel.
  subDefB is supported for switches.
  Second action is not sent.
  If [subDefB] = getNextID FHEM can assign a free SenderID alternatively. The assigned SenderID will only displayed after the system configuration has been reloaded, e.g. Fhem command rereadcfg.
• subDefC <EnOcean SenderID>, [subDefC] = [subDef] is default.
  SenderID (TCM BaseID + offset) for [value] = C0|CI|released
  Used with switch type "channel". Set attr switchType to channel.
  subDefC is supported for switches.
  Second action is not sent.
  If [subDefC] = getNextID FHEM can assign a free SenderID alternatively. The assigned SenderID will only displayed after the system configuration has been reloaded, e.g. Fhem command rereadcfg.
• subDefD <EnOcean SenderID>, [subDefD] = [subDef] is default.
  SenderID (TCM BaseID + offset) for [value] = D0|DI|released
  Used with switch type "channel". Set attr switchType to channel.
  subDefD is supported for switches.
  Second action is not sent.
  If [subDefD] = getNextID FHEM can assign a free SenderID alternatively. The assigned SenderID will only displayed after the system configuration has been reloaded, e.g. Fhem command rereadcfg.
• subDef0 <EnOcean SenderID>, [subDef0] = [subDef] is default.
  SenderID (TCM BaseID + offset) for [value] = A0|B0|C0|D0|released
  Used with switch type "central". Set attr switchType to central.
  Use the sensor type "zentral aus/ein" for Eltako devices.
  subDef0 is supported for switches.
  Second action is not sent.
  If [subDef0] = getNextID FHEM can assign a free SenderID alternatively. The assigned SenderID will only displayed after the system configuration has been reloaded, e.g. Fhem command rereadcfg.
• subDefI <EnOcean SenderID>, [subDefI] = [subDef] is default.
  SenderID (TCM BaseID + offset) for [value] = AI|BI|CI|DI
  Used with switch type "central". Set attr switchType to central.
  Use the sensor type "zentral aus/ein" for Eltako devices.
  subDefI is supported for switches.
  Second action is not sent.
  If [subDefI] = getNextID FHEM can assign a free SenderID alternatively. The assigned SenderID will only displayed after the system configuration has been reloaded, e.g. Fhem command rereadcfg.
• subDefH <EnOcean SenderID>, [subDefH] = undef is default.
  SenderID (TCM BaseID + offset)
  Used with subType "multisensor.00". If the attribute subDefH is set, the position of the window handle as EEP F6-10-00 (windowHandle) telegram is forwarded.
  If [subDefH] = getNextID FHEM can assign a free SenderID alternatively.
• subDefW <EnOcean SenderID>, [subDefW] = undef is default.
  SenderID (TCM BaseID + offset)
  Used with subType "multisensor.00". If the attribute subDefW is set, the window state as EEP D5-00-01 (contact) telegram is forwarded.
  If [subDefW] = getNextID FHEM can assign a free SenderID alternatively.
• subType Type of device (EEP Profile). The profile has to fit their basic profile. More information can be found in the basic profiles.
• subTypeReading <type of device>, [subTypeReading] = [subType] is default.
  Type of device (EEP Profile) used for readings. Set the Attribute manually. The profile has to fit their basic profile. More information can be found in the basic profiles.
• subTypeSet <type of device>, [subTypeSet] = [subType] is default.
  Type of device (EEP Profile) used for sending commands. Set the Attribute manually. The profile has to fit their basic profile. More information can be found in the basic profiles.
• summerMode off|on, [summerMode] = off is default.
  Put Battery Powered Actuator (hvac.01/hvac.06) or Heating Radiator Actuating Drive (hvac.04) in summer operation to reduce energy consumption. If [summerMode] = on, the set commands are not executed.
• switchHysteresis <value>, [switchHysteresis] = 1 is default.
  Switch Hysteresis
• switchMode switch|pushbutton, [switchMode] = switch is default.
  The set command "released" immediately after <value> is sent if the attribute is set to "pushbutton".
• switchType direction|universal|central|channel, [switchType] = direction is default.
  EnOcean Devices support different types of sensors, e. g. direction switch, universal switch or pushbutton, central on/off.
  For Eltako devices these are the sensor types "Richtungstaster", "Universalschalter" or "Universaltaster", "Zentral aus/ein".
  With the sensor type direction switch on/off commands are accepted, e. g. B0, BI, released. Fhem can control an device with this sensor type unique. This is the default function and should be preferred.
  Some devices only support the universal switch or pushbutton. With a Fhem command, for example, B0 or BI is switched between two states. In this case Fhem cannot control this device unique. But if the Attribute switchType is set to universal Fhem synchronized with a bidirectional device and normal on/off commands can be used. If the bidirectional device response with the channel B confirmation telegrams also B0 and BI commands are to be sent, e g. channel A with A0 and AI. Also note that confirmation telegrams needs to be sent.
  Partly for the switchType central two different SenderID are required. In this case set the Attribute switchType to central and define the Attributes subDef0 and subDefI.
  Furthermore, SenderIDs can be used depending on the channel A, B, C or D. In this case set the Attribute switchType to channel and define the Attributes subDefA, subDefB, subDefC, or subDefD.
• temperatureRefDev <name>
  Name of the device whose reference value is read. The reference values is the reading temperature.
• temperatureScale F|C|default|no_change, [temperatureScale] = no_change is default.
  temperatureScale is supported for roomCtrlPanel.00.
• timeNotation 12|24|default|no_change, [timeNotation] = no_change is default.
  timeNotation is supported for roomCtrlPanel.00.
• timeProgram1
  timeProgram2
  timeProgram3
  timeProgram4 <period> <starttime> <endtime> <roomCtrlMode>, [timeProgam[1-4]] = <none> is default.
  [period] = FrMo|FrSu|ThFr|WeFr|TuTh|MoWe|SaSu|MoFr|MoSu|Su|Sa|Fr|Th|We|Tu|Mo
  [starttime] = [00..23]:[00|15|30|45]
  [endtime] = [00..23]:[00|15|30|45]
  [roomCtrlMode] = buildingProtection|comfort|economy|preComfort
  The Room Control Panel Kieback & Peter RBW322-FTL supports only [roomCtrlMode] = comfort.
  timeProgram is supported for roomCtrlPanel.00.
• trackerWakeUpCycle t/s, [wakeUpCycle] =10 s, 20 s, 30 s, 40 s, 60 s, 120 s, 180 s, 240 s, 3600, 86400 s, 30 s is default.
  Transmission cycle of the tracker.
• updateState default|yes|no, [updateState] = default is default.
  update reading state after set commands
• uteResponseRequest yes|no
  request UTE teach-in/teach-out response message, the standard value depends on the EEP profil
• verbose
• wakeUpCycle t/s, [wakeUpCycle] = auto|10 s ... 151200 s, 300 s is default for hvac.04 and auto for hvac.06.
  Transmission cycle of the actuator.
• webCmd
• windowOpenCtrl disable|enable, disable s is default.
  Window open detection. Valve will be closed if the window is open.
• windSpeedStormy v_min/m/s:v_max/m/s, [windSpeedStormy] = 0...35:0...35, 13.9:17.2 is default.
  Set switching thresholds for reading isStormy based on the reading windSpeed.
• windSpeedStormyDelay t_reset/s:t_set/s, [windSpeedStormyDelay] = 0...99000:0...99000, 60:3 is default.
  Set switching delay for reading isStormy based on the reading windSpeed. The reading isStormy is reset or set if the thresholds are permanently undershot or exceed during the delay time.
• windSpeedWindy v_min/m/s:v_max/m/s, [windSpeedWindy] = 0...35:0...35, 1.6:3.4 is default.
  Set switching thresholds for reading isWindy based on the reading windSpeed.
• windSpeedWindyDelay t_reset/s:t_set/s, [windSpeedWindyDelay] = 0...99000:0...99000, 60:3 is default.
  Set switching delay for reading isWindy based on the reading windSpeed. The reading isWindy is reset or set if the thresholds are permanently undershot or exceed during the delay time.
• updateGlobalAttr no|yes, [timeEvent] = no|yes, no is default.
  Update the global attributes latitude and longitude with the received GPS coordinates.

Generated events

• Remote Management
  
  • remoteDevCfg<0000...FFFF>: <device config>
  • remoteFunction<01...99>: <remote function number>:<remote manufacturer ID>:<explanation>
  • remoteLastFunctionNumber: 001...FFF
  • remoteLastStatusReturnCode: 00...FF
  • remoteLearn: not_supported|supported
  • remoteLinkCfg<in|out><00...FF>: <data index>:<device config>
  • remoteLinkTableDesc<in|out><00...FF>: <DeviceID>:<EEP>:<channel>
  • remoteLinkTableGPDesc<in|out><00...FF>: <name of channel 00>:<O|I>:<channel type>:<signal type>:<value type>[:<resolution>[:<engineering min>:<scaling min>:<engineering max>:<scaling max>]]
  • remoteProductID: 00000000...FFFFFFFF
  • remoteRepeaterFilter: AND|OR
  • remoteRepeaterFunction: on|off|filter
  • remoteRepeaterLevel: 1|2
  • remoteTeach: not_supported|supported
  • remoteRSSI: LP/dBm
  • teach: <result of teach procedure>



• Signal Telegram
  
  • harvester: very_good|good|average|bad|very_bad
  • hwVersion: 00000000...FFFFFFFF
  • trigger: heartbeat
  • smartAckMailbox: empty|not_exists|reset
  • swVersion: 00000000...FFFFFFFF



• Bistable Switch (EEP F6-02-01 ... F6-02-04)
  [EnOcean PTM 202 Module]
  
  • B0
  • BI
  • channelB: B0|BI
  • state: B0|BI
  
  Single rocker operation only (Button B0 or BI) and energy bow pressed only, no release telegram.



• Pushbutton Switch (EEP F6-02-01 ... F6-03-02)
  [EnOcean PTM 210, PTM 215 Module]
  
  • A0
  • AI
  • B0
  • BI
  • C0
  • CI
  • D0
  • DI
  • <BtnX,BtnY> First and second action where BtnX and BtnY is one of the above, e.g. A0 BI or D0 CI
  • buttons: pressed|released
  • state: <BtnX>[,<BtnY>]
  
  Switches (remote controls) or actors with more than one (pair) keys may have multiple channels e. g. B0/BI, A0/AI with one SenderID or with separate addresses.



• Pushbutton Switch, Pushbutton Input Module (EEP F6-02-01 ... F6-02-02, F6-01-01)
  [Eltako FT55, FSM12, FSM61, FTS12]
  
  • A0
  • AI
  • B0
  • BI
  • C0
  • CI
  • D0
  • DI
  • <BtnX,BtnY> First and second action where BtnX and BtnY is one of the above, e.g. A0,BI or D0,CI
  • released
  • buttons: pressed|released
  • state: <BtnX>[,<BtnY>] [released]
  
  The status of the device may become "released", this is not the case for a normal switch.
  Set attr model to Eltako_FT55|FSM12|FSM61|FTS12 or attr sensorMode to pushbutton manually.



• Wireless 4-way colour pushbuttons display (EEP F6-02-01)
  [Eltako F4CT55]
  
  • A0
  • AI
  • B0
  • BI
  • <BtnX,BtnY> First and second action where BtnX and BtnY is one of the above, e.g. A0,BI
  • released
  • buttons: pressed|released
  • colourAll: <RRGGBB>
  • colourAI: <RRGGBB>
  • colourA0: <RRGGBB>
  • colourBI: <RRGGBB>
  • colourB0: <RRGGBB>
  • state: <BtnX>[,<BtnY>] [released]
  
  The attr subType must be set to switch, manufID to 00D and attr model to Eltako_F4CT55. If the released state is to be displayed after the end of a keystroke, set attr sensorMode to pushbutton manually.



• Pushbutton Switch (EEP F6-3F-7F)
  [Eltako FGW14/FAM14 with internal decryption and RS-485 communication]
  
  • A0
  • AI
  • B0
  • BI
  • C0
  • CI
  • D0
  • DI
  • <BtnX,BtnY> First and second action where BtnX and BtnY is one of the above, e.g. A0,BI or D0,CI
  • released
  • buttons: pressed|released
  • state: <BtnX>[,<BtnY>] [released]
  
  Set attr subType to switch.7F and manufID to 00D.
  The status of the device may become "released", this is not the case for a normal switch. Set attr sensorMode to pushbutton manually.



• Pushbutton Switch (EEP D2-03-00)
  [EnOcean PTM 210 / PTM 215 Module]
  
  • A0
  • AI
  • B0
  • BI
  • <BtnX,BtnY> First and second action where BtnX and BtnY is one of the above, e.g. A0,BI
  • pressed
  • released
  • teach: <result of teach procedure>
  • energyBow: pressed|released
  • state: <BtnX>|<BtnX>,<BtnY>|released|pressed|teachIn|teachOut
  
  The attr subType must be switch.00. This is done if the device was created by autocreate. Set attr sensorMode to pushbutton manually if needed.



• Pushbutton Switch (EEP D2-03-0A)
  [Nodon Soft Button]
  
  • on
  • off
  • batteryPercent: r/% (Sensor Range: r = 1 % ... 100 %)
  • buttonD: on|off
  • buttonL: on|off
  • buttonS: on|off
  • state: on|off
  
  The attr subType must be switch.0A. This is done if the device was created by autocreate.



• Heating/Cooling Relay (EEP F6-02-01 ... F6-02-02)
  [Eltako FAE14, FHK14, untested]
  
  • controllerMode: auto|off
  • energyHoldOff: normal|holdoff
  • buttons: pressed|released
  
  Set attr subType to switch and model to Eltako_FAE14|FHK14 manually. In addition every telegram received from a teached-in temperature sensor (e.g. FTR55H) is repeated as a confirmation telegram from the Heating/Cooling Relay FAE14, FHK14. In this case set attr subType to e. g. roomSensorControl.05 and attr manufID to 00D.



• Key Card Activated Switch (EEP F6-04-01)
  [Eltako FKC, FKF, FZS, untested]
  
  • keycard_inserted
  • keycard_removed
  • state: keycard_inserted|keycard_removed
  
  Set attr subType to keycard manually.



• Wind Speed Threshold Detector (EEP F6-05-00)
  
  • on
  • off
  • alarm: dead_sensor|off
  • windSpeed: dead_sensor|on|off
  • battery: low|ok
  • state: on|off
  
  Set attr subType to windSpeed.00 manually.



• Liquid Leakage Sensor (EEP F6-05-01)
  [untested]
  
  • dry
  • wet
  • state: dry|wet
  
  Set attr subType to liquidLeakage manually.



• Smoke Detector (EEP F6-05-02)
  [Eltako FRW]
  
  • smoke-alarm
  • off
  • alarm: dead_sensor|smoke-alarm|off
  • battery: low|ok
  • state: smoke-alarm|off
  
  Set attr subType to smokeDetector.02 manually. A monitoring period can be set for signOfLife telegrams of the sensor, see signOfLife and signOfLifeInterval. Default is "on" and an interval of 1440 sec.



• Window Handle (EEP F6-10-00, D2-03-10)
  [HOPPE SecuSignal, Eltako FHF, Eltako FTKE]
  
  • closed
  • open
  • tilted
  • open_from_tilted
  • state: closed|open|tilted|open_from_tilted
  
  The device windowHandle or windowHandle.10 should be created by autocreate.



• Single Input Contact, Door/Window Contact
  1BS Telegram (EEP D5-00-01)
  [EnOcean EMCS, STM 320, STM 329, STM 250, Eltako FTK, Peha D 450 FU, Eltako TK-TKB]
  • closed
  • open
  • alarm: dead_sensor
  • battery: U/V (Range: U = 0 V ... 5 V
  • energyStorage: U/V (Range: U = 0 V ... 5 V
  • teach: <result of teach procedure>
  • state: open|closed
The device should be created by autocreate. A monitoring period can be set for signOfLife telegrams of the sensor, see signOfLife and signOfLifeInterval. Default is "off" and an interval of 1980 sec.


• Temperature Sensors with with different ranges (EEP A5-02-01 ... A5-02-30)
  [EnOcean STM 330, Eltako FTF55, Thermokon SR65 ...]
  
  • t/°C
  • temperature: t/°C (Sensor Range: t = <t min> °C ... <t max> °C)
  • state: t/°C
  
  A monitoring period can be set for signOfLife telegrams of the sensor, see signOfLife and signOfLifeInterval. Default is "off" and an interval of 1230 sec.
  The attr subType must be tempSensor.01 ... tempSensor.30. This is done if the device was created by autocreate.



• Temperatur and Humidity Sensor (EEP A5-04-02)
  [Eltako FAFT60, FIFT63AP]
  
  • T: t/°C H: rH/% B: unknown|low|ok
  • battery: unknown|low|ok
  • energyStorage: unknown|empty|charged|full
  • humidity: rH/% (Sensor Range: rH = 0 % ... 100 %)
  • temperature: t/°C (Sensor Range: t = -20 °C ... 60 °C)
  • voltage: U/V
  (Sensor Range: U = 0 V ... 6.6 V)
  • state: T: t/°C H: rH/% B: unknown|low|ok
  
  The attr subType must be tempHumiSensor.02 and attr manufID must be 00D for Eltako Devices. This is done if the device was created by autocreate.
  A monitoring period can be set for signOfLife telegrams of the sensor, see signOfLife and signOfLifeInterval. Default is "off" and an interval of 3300 sec.



• Temperatur and Humidity Sensor (EEP A5-04-03)
  [untested]
  
  • T: t/°C H: rH/%
  • alarm: dead_sensor
  • humidity: rH/% (Sensor Range: rH = 0 % ... 100 %)
  • telegramType: heartbeat|event
  • temperature: t/°C (Sensor Range: t = -20 °C ... 60 °C)
  • state: T: t/°C H: rH/%
  
  The attr subType must be tempHumiSensor.03. This is done if the device was created by autocreate.
  A monitoring period can be set for signOfLife telegrams of the sensor, see signOfLife and signOfLifeInterval. Default is "off" and an interval of 1540 sec.



• Barometric Sensor (EEP A5-05-01)
  [untested]
  
  • P/hPa
  • airPressure: P/hPa (Sensor Range: P = 500 hPa ... 1150 hPa
  • telegramType: heartbeat|event
  • state: P/hPa
  
  The attr subType must be baroSensor.01. This is done if the device was created by autocreate.



• Light Sensor (EEP A5-06-01)
  [Eltako FAH60, FAH63, FIH63, Thermokon SR65 LI]
  
  • E/lx
  • alarm: dead_sensor
  • brightness: E/lx (Sensor Range: 300 lx ... 30 klx, 600 lx ... 60 klx , Sensor Range for Eltako: E = 0 lx ... 100 lx, 300 lx ... 30 klx)
  • voltage: U/V
  (Sensor Range: U = 0 V ... 5.1 V)
  • state: E/lx
  
  Please set the attribute model to Eltako_FAH60 if the sensor is from the production year 2015 or later.
  The attr subType must be lightSensor.01 and attr manufID must be 00D for Eltako Devices. This is done if the device was created by autocreate.
  signOfLifeInterval ([signOfLifeInterval] = 110 is default).
  



• Light Sensor (EEP A5-06-02)
  [untested]
  
  • E/lx
  • brightness: E/lx (Sensor Range: 0 lx ... 1020 lx
  • voltage: U/V (Sensor Range: U = 0 V ... 5.1 V)
  • state: E/lx
  
  The attr subType must be lightSensor.02. This is done if the device was created by autocreate.



• Light Sensor (EEP A5-06-03)
  [untested]
  
  • E/lx
  • brightness: E/lx (Sensor Range: E = 0 lx ... 1000 lx, over range)
  • errorCode: 251 ... 255
  • state: E/lx
  
  The attr subType must be lightSensor.03. This is done if the device was created by autocreate.



• Light Sensor (EEP A5-06-04)
  [untested]
  
  • T: t/°C E: E/lx B: ok|low
  • battery: ok|low
  • brightness: E/lx (Sensor Range: E = 0 lx ... 65535 lx)
  • energyStorage: 1/%
  • temperature: t/°C (Sensor Range: t = -20 °C ... 60 °C)
  • state: T: t/°C E: E/lx B: ok|low
  
  The attr subType must be lightSensor.04. This is done if the device was created by autocreate.



• Light Sensor (EEP A5-06-05)
  [untested]
  
  • E/lx
  • brightness: E/lx (Sensor Range: 0 lx ... 10200 lx
  • voltage: U/V (Sensor Range: U = 0 V ... 5.1 V)
  • state: E/lx
  
  The attr subType must be lightSensor.05. This is done if the device was created by autocreate.



• Occupancy Sensor (EEP A5-07-01, A5-07-02)
  [EnOcean EOSW]
  
  • on|off
  • alarm: dead_sensor
  • battery: ok|low
  • button: pressed|released
  • current: I/µA (Sensor Range: I = 0 V ... 127.0 µA)
  • errorCode: 251 ... 255
  • motion: on|off
  • sensorType: ceiling|wall
  • voltage: U/V (Sensor Range: U = 0 V ... 5.0 V)
  • state: on|off
  
  The attr subType must be occupSensor.<01|02>. This is done if the device was created by autocreate. Current is the solar panel current. Some values are displayed only for certain types of devices.
  signOfLifeInterval ([signOfLifeInterval] = 1320 is default).
  



• Eltako/PioTek-Tracker TF-TTB (EEP A5-07-01)
  
  • on|off
  • battery: ok|low
  • button: pressed|released
  • motion: on|off
  • voltage: U/V (Sensor Range: U = 0 V ... 5.0 V)
  • state: on|off
  
  The attr subType must be occupSensor.01. This is done if the device was created by autocreate. The attr model has to be set manually to tracker. Alternatively, the profile will be defined with inofficial EEP G5-07-01.
  The transmission cycle is set using the attribute trackerWakeUpCycle.



• Occupancy Sensor (EEP A5-07-03)
  [untested]
  
  • M: on|off E: E/lx U: U/V
  • alarm: dead_sensor
  • battery: ok|low
  • brightness: E/lx (Sensor Range: E = 0 lx ... 1000 lx, over range)
  • errorCode: 251 ... 255
  • motion: on|off
  • voltage: U/V (Sensor Range: U = 0 V ... 5.0 V)
  • state: M: on|off E: E/lx U: U/V
  
  The attr subType must be occupSensor.03. This is done if the device was created by autocreate.
  signOfLifeInterval ([signOfLifeInterval] = 1320 is default).
  



• Light, Temperatur and Occupancy Sensor (EEP A5-08-01 ... A5-08-03)
  [Eltako FABH63, FBx5B, FBH55, FBH63, FBH65x, FBHF65SB, FIBH63, Thermokon SR-MDS, PEHA 482 FU-BM DE]
  
  • M: on|off E: E/lx P: absent|present T: t/°C U: U/V
  • alarm: dead_sensor
  • brightness: E/lx (Sensor Range: E = 0 lx ... 510, 1020, 1530 or 2048 lx)
  • motion: on|off
  • presence: absent|present
  • temperature: t/°C (Sensor Range: t = 0 °C ... 51 °C or -30 °C ... 50 °C)
  • voltage: U/V
  (Sensor Range: U = 0 V ... 5.1 V)
  • state: M: on|off E: E/lx P: absent|present T: t/°C U: U/V
  
  Eltako and PEHA devices only support Brightness and Motion.
  The attr subType must be lightTempOccupSensor.<01|02|03> and attr manufID must be 00D for Eltako Devices. This is done if the device was created by autocreate. Set model to Eltako_TF manually for Eltako TF devices or to FBH55SB, FBH65SB, FBHF65SB.
  signOfLifeInterval ([signOfLifeInterval] = 1320 is default).
  



• Gas Sensor, CO Sensor (EEP A5-09-01)
  [untested]
  
  • CO: c/ppm (Sensor Range: c = 0 ppm ... 255 ppm)
  • temperature: t/°C (Sensor Range: t = 0 °C ... 255 °C)
  • state: c/ppm
  
  The attr subType must be COSensor.01. This is done if the device was created by autocreate.



• Gas Sensor, CO Sensor (EEP A5-09-02)
  [untested]
  
  • CO: c/ppm (Sensor Range: c = 0 ppm ... 1020 ppm)
  • temperature: t/°C (Sensor Range: t = 0 °C ... 51.0 °C)
  • voltage: U/V
  (Sensor Range: U = 0 V ... 5.1 V)
  • state: c/ppm
  
  The attr subType must be COSensor.02. This is done if the device was created by autocreate.



• Gas Sensor, CO2 Sensor (EEP A5-09-04)
  [Thermokon SR04 CO2 *, Eltako FCOTF63, untested]
  
  • airQuality: high|mean|moderate|low (Air Quality Classes DIN EN 13779)
  • CO2: c/ppm (Sensor Range: c = 0 ppm ... 2550 ppm)
  • humidity: rH/% (Sensor Range: rH = 0 % ... 100 %)
  • temperature: t/°C (Sensor Range: t = 0 °C ... 51 °C)
  • state: T: t/°C H: rH/% CO2: c/ppm AQ: high|mean|moderate|low
  
  The attr subType must be tempHumiCO2Sensor.01. This is done if the device was created by autocreate.



• Gas Sensor, Volatile organic compounds (VOC) Sensor (EEP A5-09-05, A5-09-0C)
  [untested]
  
  • concentration: c/[unit] (Sensor Range: c = 0 ... 655350
  • concentrationUnit: ppb|μ/m3
  • vocName: Name of last measured VOC
  • state: c/[unit]
  
  The attr subType must be vocSensor.01. This is done if the device was created by autocreate.



• Gas Sensor, Radon Sensor (EEP A5-09-06)
  [untested]
  
  • Rn: A m3/Bq (Sensor Range: A = 0 Bq/m3 ... 1023 Bq/m3)
  • state: A m3/Bq
  
  The attr subType must be radonSensor.01. This is done if the device was created by autocreate.



• Gas Sensor, Particles Sensor (EEP A5-09-07)
  [untested]
  Three channels with particle sizes of up to 10 μm, 2.5 μm and 1 μm are supported
  .
  • particles_10: p m3/μg | inactive (Sensor Range: p = 0 μg/m3 ... 511 μg/m3)
  • particles_2_5: p m3/μg | inactive (Sensor Range: p = 0 μg/m3 ... 511 μg/m3)
  • particles_1: p m3/μg | inactive (Sensor Range: p = 0 μg/m3 ... 511 μg/m3)
  • state: PM10: p m3/μg PM2_5: p m3/μg PM1: p m3/μg
  
  The attr subType must be particlesSensor.01. This is done if the device was created by autocreate.



• CO2 Sensor (EEP A5-09-08, A5-09-09)
  [untested]
  
  • CO2: c/ppm (Sensor Range: c = 0 ppm ... 2000 ppm)
  • powerFailureDetection: detected|not_detected
  • state: c/ppm
  
  The attr subType must be CO2Sensor.01. This is done if the device was created by autocreate.



• H Sensor (EEP A5-09-0A)
  [untested]
  
  • c/ppm
  • voltage: U/V (Sensor Range: U = 2 V ... 5 V)
  • H: c/ppm (Sensor Range: c = 0 ppm ... 2000 ppm)
  • temperature: t/°C (Sensor Range: t = -20 °C ... 60 °C)
  • state: c/ppm
  
  The attr subType must be HSensor.01. This is done if the device was created by autocreate.



• Radiation Sensor (EEP A5-09-0B)
  [untested]
  
  • 1/[unit]
  • radioactivity: 1/[unit] (Sensor Range: c = 0 [unit] ... 65535 [unit])
  • unit: uSv/h|cpm|Bq/L|Bq/kg
  • voltage: U/V (Sensor Range: U = 2 V ... 5 V)
  • state: 1/[unit]
  
  The attr subType must be radiationSensor.01. This is done if the device was created by autocreate.



• Room Sensor and Control Unit (EEP A5-10-01 ... A5-10-0D)
  [Eltako FTR55*, Thermokon SR04 *, Thanos SR *]
  
  • T: t/°C SP: 0 ... 255 F: 0|1|2|3|auto SW: 0|1
  • fanStage: 0|1|2|3|auto
  • switch: on|off
  • setpoint: 0 ... 255
  • setpointScaled: <floating-point number>
  • temperature: t/°C (Sensor Range: t = 0 °C ... 40 °C)
  • state: T: t/°C SP: 0 ... 255 F: 0|1|2|3|auto SW: on|off
  
  Alternatively for Eltako devices
  • T: t/°C SPT: t/°C NR: t/°C
  • block: lock|unlock
  • nightReduction: t/K
  • setpointTemp: t/°C
  • temperature: t/°C (Sensor Range: t = 0 °C ... 40 °C)
  • state: T: t/°C SPT: t/°C NR: t/K
  
  
  
  The scaling of the setpoint adjustment is device- and vendor-specific. Set the attributes scaleMax, scaleMin and scaleDecimals for the additional scaled reading setpointScaled. Use attribut userReadings to adjust the scaling alternatively.
  A monitoring period can be set for signOfLife telegrams of the sensor, see signOfLife and signOfLifeInterval. Default is "off" and an interval of 1320 sec.
  The attr subType must be roomSensorControl.05 and attr manufID must be 00D for Eltako Devices. This is done if the device was created by autocreate.



• Room Sensor and Control Unit (EEP A5-04-01, A5-10-10 ... A5-10-14)
  [Eltako FUTH65D, Thermokon SR04 * rH, Thanos SR *]
  
  • T: t/°C H: rH/% SP: 0 ... 255 SW: 0|1
  • humidity: rH/% (Sensor Range: rH = 0 % ... 100 %)
  • switch: 0|1
  • temperature: t/°C (Sensor Range: t = 0 °C ... 40 °C)
  • setpoint: 0 ... 255
  • setpointScaled: <floating-point number>
  • state: T: t/°C H: rH/% SP: 0 ... 255 SW: 0|1
  
  The scaling of the setpoint adjustment is device- and vendor-specific. Set the attributes scaleMax, scaleMin and scaleDecimals for the additional scaled reading setpointScaled. Use attribut userReadings to adjust the scaling alternatively.
  The attr subType must be roomSensorControl.01 and attr manufID must be 00D for Eltako Devices. This is done if the device was created by autocreate.



• Room Sensor and Control Unit (EEP A5-10-15 ... A5-10-17)
  [untested]
  
  • T: t/°C SP: 0 ... 63 P: absent|present
  • presence: absent|present
  • temperature: t/°C (Sensor Range: t = -10 °C ... 41.2 °C)
  • setpoint: 0 ... 63
  • setpointScaled: <floating-point number>
  • state: T: t/°C SP: 0 ... 63 P: absent|present
  
  The scaling of the setpoint adjustment is device- and vendor-specific. Set the attributes scaleMax, scaleMin and scaleDecimals for the additional scaled reading setpointScaled. Use attribut userReadings to adjust the scaling alternatively.
  The attr subType must be roomSensorControl.02. This is done if the device was created by autocreate.



• Room Sensor and Control Unit (EEP A5-10-18)
  [untested]
  
  • T: t/°C B: E/lx F: 0|1|2|3|4|5|auto|off SP: t/°C P: absent|present|disabled
  • brightness: E/lx (Sensor Range: E = 0 lx ... 1000 lx, over range)
  • fan: 0|1|2|3|4|5|auto|off
  • presence: absent|present|disabled
  • temperature: t/°C (Sensor Range: t = 0 °C ... 40 °C)
  • setpoint: t/°C (Sensor Range: t = 0 °C ... 40 °C)
  • state: T: t/°C B: E/lx F: 0|1|2|3|4|5|auto|off SP: t/°C P: absent|present|disabled
  
  The attr subType must be roomSensorControl.18. This is done if the device was created by autocreate.



• Room Sensor and Control Unit (EEP A5-10-19)
  [untested]
  
  • T: t/°C H: rH/% F: 0|1|2|3|4|5|auto|off SP: t/°C P: absent|present|disabled
  • fan: 0|1|2|3|4|5|auto|off
  • humidity: rH/% (Sensor Range: rH = 0 % ... 100 %)
  • presence: absent|present|disabled
  • setpoint: t/°C (Sensor Range: t = 0 °C ... 40 °C)
  • temperature: t/°C (Sensor Range: t = 0 °C ... 40 °C)
  • state: T: t/°C H: rH/% F: 0|1|2|3|4|5|auto|off SP: t/°C P: absent|present|disabled
  
  The attr subType must be roomSensorControl.19. This is done if the device was created by autocreate.



• Room Sensor and Control Unit (EEP A5-10-1A)
  [untested]
  
  • T: t/°C F: 0|1|2|3|4|5|auto|off SP: t/°C P: absent|present|disabled U: U/V
  • errorCode: 251 ... 255
  • fan: 0|1|2|3|4|5|auto|off
  • presence: absent|present|disabled
  • setpoint: t/°C (Sensor Range: t = 0 °C ... 40 °C)
  • temperature: t/°C (Sensor Range: t = 0 °C ... 40 °C)
  • voltage: U/V (Sensor Range: U = 0 V ... 5.0 V)
  • state: T: t/°C F: 0|1|2|3|4|5|auto|off SP: t/°C P: absent|present|disabled U: U/V
  
  The attr subType must be roomSensorControl.1A. This is done if the device was created by autocreate.



• Room Sensor and Control Unit (EEP A5-10-1B)
  [untested]
  
  • T: t/°C B: E/lx F: 0|1|2|3|4|5|auto|off P: absent|present|disabled U: U/V
  • brightness: E/lx (Sensor Range: E = 0 lx ... 1000 lx, over range)
  • errorCode: 251 ... 255
  • fan: 0|1|2|3|4|5|auto|off
  • presence: absent|present|disabled
  • temperature: t/°C (Sensor Range: t = 0 °C ... 40 °C)
  • voltage: U/V (Sensor Range: U = 0 V ... 5.0 V)
  • state: T: t/°C B: E/lx F: 0|1|2|3|4|5|auto|off P: absent|present|disabled U: U/V
  
  The attr subType must be roomSensorControl.1B. This is done if the device was created by autocreate.



• Room Sensor and Control Unit (EEP A5-10-1C)
  [untested]
  
  • T: t/°C B: E/lx F: 0|1|2|3|4|5|auto|off SP: E/lx P: absent|present|disabled
  • brightness: E/lx (Sensor Range: E = 0 lx ... 1000 lx, over range)
  • fan: 0|1|2|3|4|5|auto|off
  • presence: absent|present|disabled
  • setpoint: E/lx (Sensor Range: E = 0 lx ... 1000 lx, over range)
  • temperature: t/°C (Sensor Range: t = 0 °C ... 40 °C)
  • state: T: t/°C B: E/lx F: 0|1|2|3|4|5|auto|off SP: E/lx P: absent|present|disabled
  
  The attr subType must be roomSensorControl.1C. This is done if the device was created by autocreate.



• Room Sensor and Control Unit (EEP A5-10-1D)
  [untested]
  
  • T: t/°C H: rH/% F: 0|1|2|3|4|5|auto|off SP: rH/% P: absent|present|disabled
  • humidity: rH/% (Sensor Range: rH = 0 % ... 100 %)
  • fan: 0|1|2|3|4|5|auto|off
  • presence: absent|present|disabled
  • setpoint: rH/% (Sensor Range: rH = 0 % ... 100 %)
  • temperature: t/°C (Sensor Range: t = 0 °C ... 40 °C)
  • state: T: t/°C H: rH/% F: 0|1|2|3|4|5|auto|off SP: rH/% P: absent|present|disabled
  
  The attr subType must be roomSensorControl.1D. This is done if the device was created by autocreate.



• Room Sensor and Control Unit (EEP A5-10-1F)
  [untested]
  
  • T: t/°C F: 0|1|2|3|auto SP: 0 ... 255 P: absent|present|disabled
  • fan: 0|1|2|3|auto
  • presence: absent|present|disabled
  • setpoint: 0 ... 255
  • setpointScaled: <floating-point number>
  • temperature: t/°C (Sensor Range: t = 0 °C ... 40 °C)
  • state: T: t/°C F: 0|1|2|3|auto SP: 0 ... 255 P: absent|present|disabled
  
  The scaling of the setpoint adjustment is device- and vendor-specific. Set the attributes scaleMax, scaleMin and scaleDecimals for the additional scaled reading setpointScaled. Use attribut userReadings to adjust the scaling alternatively.
  The attr subType must be roomSensorControl.1F. This is done if the device was created by autocreate.



• Room Operation Panel (EEP A5-10-20, A5-10-21)
  [untested]
  
  • T: t/°C H: rH/% SP: 0 ... 255 B: ok|low
  • activity: yes|no
  • battery: ok|low
  • humidity: rH/% (Sensor Range: rH = 0 % ... 100 %)
  • setpoint: 0 ... 255
  • setpointMode: auto|frostProtect|setpoint
  • setpointScaled: <floating-point number>
  • temperature: t/°C (Sensor Range: t = 0 °C ... 40 °C)
  • state: t/°C H: rH/% SP: 0 ... 255 B: ok|low
  
  The scaling of the setpoint adjustment is device- and vendor-specific. Set the attributes scaleMax, scaleMin and scaleDecimals for the additional scaled reading setpointScaled. Use attribut userReadings to adjust the scaling alternatively.
  The attr subType must be roomSensorControl.20. This is done if the device was created by autocreate.



• Room Operation Panel (EEP A5-10-22, A5-10-23)
  [untested]
  
  • T: t/°C H: rH/% SP: 0 ... 255 F: auto|off|1|2|3 O: occupied|unoccupied
  • fanSpeed: auto|off|1|2|3
  • humidity: rH/% (Sensor Range: rH = 0 % ... 100 %)
  • occupancy: occupied|unoccupied
  • setpoint: 0 ... 255
  • setpointScaled: <floating-point number>
  • temperature: t/°C (Sensor Range: t = 0 °C ... 40 °C)
  • state: t/°C H: rH/% SP: 0 ... 255 F: auto|off|1|2|3 O: occupied|unoccupied
  
  The scaling of the setpoint adjustment is device- and vendor-specific. Set the attributes scaleMax, scaleMin and scaleDecimals for the additional scaled reading setpointScaled. Use attribut userReadings to adjust the scaling alternatively.
  The attr subType must be roomSensorControl.22. This is done if the device was created by autocreate.



• Lighting Controller State (EEP A5-11-01)
  [untested]
  
  • on|off
  • brightness: E/lx (Sensor Range: E = 0 lx ... 510 lx)
  • contact: open|closed
  • daylightHarvesting: enabled|disabled
  • dim: 0 ... 255
  • presence: absent|present
  • illum: 0 ... 255
  • mode: switching|dimming
  • powerRelayTimer: enabled|disabled
  • powerSwitch: on|off
  • repeater: enabled|disabled
  • state: on|off
  
  The attr subType must be lightCtrlState.01 This is done if the device was created by autocreate.



• Temperature Controller Output (EEP A5-11-02)
  [untested]
  
  • t/°C
  • alarm: on|off
  • controlVar: cvar (Sensor Range: cvar = 0 % ... 100 %)
  • controllerMode: auto|heating|cooling|off
  • controllerState: auto|override
  • energyHoldOff: normal|holdoff
  • fan: 0 ... 3|auto
  • presence: present|absent|standby|frost
  • setpointTemp: t/°C (Sensor Range: t = 0 °C ... 51.2 °C)
  • state: t/°C
  
  The attr subType must be tempCtrlState.01 This is done if the device was created by autocreate.



• Blind Status (EEP A5-11-03)
  [untested, experimental status]
  
  • open|closed|not_reached|not_available
  • alarm: on|off|no endpoints defined|not used
  • anglePos: α/° (Sensor Range: α = -180 ° ... 180 °)
  • endPosition: open|closed|not_reached|not_available
  • position: pos/% (Sensor Range: pos = 0 % ... 100 %)
  • positionMode: normal|inverse
  • serviceOn: yes|no
  • shutterState: opens|closes|stopped|not_available
  • state: open|closed|not_reached|not_available
  
  The attr subType must be shutterCtrlState.01 This is done if the device was created by autocreate.
  The profile is linked with Blind Command Central. The profile Blind Command Central controls the devices centrally. For that the attributes subDef, subTypeSet and gwCmd have to be set manually.



• Extended Lighting Status (EEP A5-11-04)
  [untested]
  
  • on|off
  • alarm: off|lamp_failure|internal_failure|external_periphery_failure
  • blue: 0 ... 255
  • current: <formula symbol>/<unit> (Sensor range: <formula symbol> = 0 ... 65535 <unit>
  • currentUnit: mA|A
  • dim: 0 ... 255
  • energy: <formula symbol>/<unit> (Sensor range: <formula symbol> = 0 ... 65535 <unit>
  • energyUnit: Wh|kWh|MWh|GWh
  • green: 0 ... 255
  • measuredValue: <formula symbol>/<unit> (Sensor range: <formula symbol> = 0 ... 65535 <unit>
  • measureUnit: unknown
  • lampOpHours: t/h |unknown (Sensor range: t = 0 h ... 65535 h)
  • power: <formula symbol>/<unit> (Sensor range: <formula symbol> = 0 ... 65535 <unit>
  • powerSwitch: on|off
  • powerUnit: mW|W|kW|MW
  • red: 0 ... 255
  • rgb: RRGGBB (red (R), green (G) or blue (B) color component values: 00 ... FF)
  • serviceOn: yes|no
  • voltage: <formula symbol>/<unit> (Sensor range: <formula symbol> = 0 ... 65535 <unit>
  • voltageUnit: mV|V
  • state: on|off
  
  The attr subType must be lightCtrlState.02 This is done if the device was created by autocreate.



• Dual Channel Switch Actuator (EEP A5-11-05)
  [untested]
  
  • 1: on|off 2: on|off
  • channel1: on|off
  • channel2: on|off
  • workingMode: 1 ... 4
  • state: 1: on|off 2: on|off
  
  The attr subType must be switch.05. This is done if the device was created by autocreate.



• Automated meter reading (AMR), Counter (EEP A5-12-00)
  [Thermokon SR-MI-HS, untested]
  
  • 1/s
  • currentValue<00 ... 15>: 1/s
  • counter<00 ... 15>: 0 ... 16777215
  • state: 1/s
  
  The attr subType must be autoMeterReading.00. This is done if the device was created by autocreate.



• Automated meter reading (AMR), Electricity (EEP A5-12-01)
  [Eltako DSZ14WDRS, FSS12, Thermokon SR-MI-HS, untested]
  [Eltako DSZ14DRS, DSZ14DRSZ, FWZ12-16A tested]
  
  • P/W
  • power: P/W
  • energy<0 ... 15>: E/kWh
  • currentTariff: 0 ... 15
  • serialNumber: S-<nnnnnn>
  • state: P/W
  
  The attr subType must be autoMeterReading.01 and attr manufID must be 00D for Eltako Devices. This is done if the device was created by autocreate.
  For the Eltako meter DSZ14DRSZ, the attribute model must be manually set to Eltako_DSZ14DRSZ.
  The Eltako device Eltako FSR14M should be taught in via Inofficial EEP P5-38-08.
  



• Automated meter reading (AMR), Gas, Water (EEP A5-12-02, A5-12-03)
  [untested]
  
  • Vs/l
  • flowrate: Vs/l
  • consumption<0 ... 15>: V/m3
  • currentTariff: 0 ... 15
  • state: Vs/l
  
  The attr subType must be autoMeterReading.02|autoMeterReading.03. This is done if the device was created by autocreate.



• Automated meter reading (AMR), Temperatur, Load (EEP A5-12-04)
  [untested]
  
  • T: t/°C W: m/g B: full|ok|low|empty
  • battery: full|ok|low|empty
  • temperature: t/°C (Sensor Range: t = -40 °C ... 40 °C)
  • weight: m/g
  • state: T: t/°C W: m/g B: full|ok|low|empty
  
  The attr subType must be autoMeterReading.04. This is done if the device was created by autocreate.



• Automated meter reading (AMR), Temperatur, Container Sensor (EEP A5-12-05)
  [untested]
  
  • T: t/°C L: B: full|ok|low|empty
  • amount: 0 ... 10
  • battery: full|ok|low|empty
  • location<0 ... 9>: possessed|not_possessed
  • temperature: t/°C (Sensor Range: t = -40 °C ... 40 °C)
  • state: T: t/°C L: B: full|ok|low|empty
  
  The attr subType must be autoMeterReading.05. This is done if the device was created by autocreate.



• Automated meter reading (AMR), Current Meter 16 Channels (EEP A5-12-10)
  [untested]
  
  • I/mA
  • current<00 ... 15>: I/mA (Sensor Range: I = 0 mA ... 16777215 mA)
  • electricChange<00 ... 15>: Q/Ah (Sensor Range: Q = 0 Ah ... 16777215 Ah)
  • currentTariff: 00 ... 15
  • state: I/mA
  
  The attr subType must be autoMeterReading.10. This is done if the device was created by autocreate.



• Environmental Applications
  Weather Station (EEP A5-13-01)
  Sun Intensity (EEP A5-13-02)
  [AWAG XFJ, Eltako FWS61]
  
  • T: t/°C B: E/lx W: Vs/m IR: yes|no
  • alarm: dead_sensor
  • brightness: E/lx (Sensor Range: E = 0 lx ... 150 klx)
  • dayNight: day|night
  • hemisphere: north|south
  • isRaining: yes|no
  • isStormy: no|yes
  • isSunny: no|yes
  • isSunnyEast: no|yes
  • isSunnySouth: no|yes
  • isSunnyWest: no|yes
  • isWindy: no|yes
  • sunEast: E/lx (Sensor Range: E = 0 lx ... 150 klx)
  • sunSouth: E/lx (Sensor Range: E = 0 lx ... 150 klx)
  • sunWest: E/lx (Sensor Range: E = 0 lx ... 150 klx)
  • temperature: t/°C (Sensor Range: t = -40 °C ... 80 °C)
  • windSpeed: Vs/m (Sensor Range: V = 0 m/s ... 70 m/s)
  • windStrength: B (Sensor Range: B = 0 Beaufort ... 12 Beaufort)
  • state:T: t/°C B: E/lx W: Vs/m IR: yes|no
  
  Brightness is the strength of the dawn light. SunEast, sunSouth and sunWest are the solar radiation from the respective compass direction. IsRaining is the rain indicator.
  The attr subType must be environmentApp. This is done if the device was created by autocreate.
  The Eltako Weather Station FWS61 supports not the day/night indicator (dayNight). The thresholds and delay times can be adjusted by the attributes
  brightnessDayNight, brightnessDayNightCtrl, brightnessDayNightDelay, brightnessSunny, brightnessSunnyDelay, brightnessSunnyEast, brightnessSunnyEastDelay, brightnessSunnySouth, brightnessSunnySouthDelay, brightnessSunnyWest, brightnessSunnyWestDelay, windSpeedStormy, windSpeedStormyDelay, windSpeedWindy, windSpeedWindyDelay.
  Execution of custom alarm commands, see customCmdAlarmOff, customCmdAlarmOn, signOfLife ([signOfLive] = on is default) and signOfLifeInterval ([signOfLifeInterval] = 660 is default).
  Execution of custom up and down commands that can be triggered by the readings dayNight, isRaining, isStormy, isSunny, isSunnyEast, isSunnySouth, isSunnyWest and isWindy, see customCmdDown and customCmdUp.



• Environmental Applications
  Data Exchange (EEP A5-13-03)
  Time and Day Exchange (EEP A5-13-04)
  Direction Exchange (EEP A5-13-05)
  Geographic Exchange (EEP A5-13-06)
  
  • date: JJJJ-MM-DD
  • latitude: φ/° (Sensor Range: φ = -90 ° ... 90 °)
  • longitude: λ/° (Sensor Range: λ = -180 ° ... 180 °)
  • sunAzimuth: α/° (Sensor Range: α = 0 ° ... 359 °)
  • sunElevation: β/° (Sensor Range: β = -90 ° ... 90 °)
  • time: hh:mm:ss [AM|PM]
  • timeSource: GPS|RTC
  • twilight: T/% (Sensor Range: T = 0 % ... 100 %)
  • weekday: Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday
  
  The attr subType must be environmentApp. This is done if the device was created by autocreate. The global attributes latitude and longitude are set automatically if the attribute updateGlobalAttr is set.
  



• Environmental Applications
  Sun Position and Radiation (EEP A5-13-10)
  [untested]
  
  • SRA: E m2/W SNA: α/° SNE: β/°
  • dayNight: day|night
  • solarRadiation: E m2/W (Sensor Range: E = 0 W/m2 ... 2000 W/m2)
  • sunAzimuth: α/° (Sensor Range: α = -90 ° ... 90 °)
  • sunElevation: β/° (Sensor Range: β = 0 ° ... 90 °)
  • state:SRA: E m2/W SNA: α/° SNE: β/°
  
  The attr subType must be environmentApp. This is done if the device was created by autocreate.



• Wind Sensor (EEP A5-13-07)
  [Hideki, untested]
  
  • Vh/km (Sensor Range: V = 0 km/h ... 199.9 km/h)
  • battery: ok|low
  • windSpeedAverage: Vh/km (Sensor Range: V = 0 km/h ... 199.9 km/h)
  • windSpeedDirection: NNE|NE|ENE|E|ESE|SE|SSE|S|SSW|SW|WSW|W|WNW|NW|NNW|N
  • windSpeedMax: Vh/km (Sensor Range: V = 0 km/h ... 199.9 km/h)
  • state:Vh/km (Sensor Range: V = 0 km/h ... 199.9 km/h)
  
  The attr subType must be windSensor.01. This is done if the device was created by autocreate.
  



• Rain Sensor (EEP A5-13-08)
  [Hideki, untested]
  
  • H/mm
  • battery: ok|low
  • rain: H/mm
  • state:H/mm
  
  The amount of rainfall is calculated at intervals of 183 s.
  The attr subType must be rainSensor.01. This is done if the device was created by autocreate.
  



• Multi-Func Sensor (EEP A5-14-01 ... A5-14-06)
  [Eimsig EM-FSGE-00 sensor]
  
  • C: open|closed V: on|off E: E/lx U: U/V
  • batteryState: low|ok
  • brightness: E/lx (Sensor Range: E = 0 lx ... 1000 lx, over range)
  • contact: open|closed
  • errorCode: 251 ... 255
  • vibration: on|off
  • voltage: U/V (Sensor Range: U = 0 V ... 5.0 V)
  • state: C: open|closed V: on|off E: E/lx U: U/V
  
  The attr subType must be multiFuncSensor. This is done if the device was created by autocreate. A monitoring period can be set for signOfLife telegrams of the sensor, see signOfLife and signOfLifeInterval. Default is "on" and an interval of 132 sec.



• Dual Door Contact (EEP A5-14-07, A5-14-08)
  [Eimsig EM-FSGE-00 sensor]
  
  • C: open|closed B: unlocked|locked V: on|off U: U/V
  • alarm: dead_sensor
  • batteryState: low|ok
  • block: unlocked|locked
  • contact: open|closed
  • vibration: on|off
  • voltage: U/V (Sensor Range: U = 0 V ... 5.0 V)
  • state: C: open|closed B: unlocked|locked V: on|off U: U/V
  
  The attr subType must be doorContact. This is done if the device was created by autocreate.
  A monitoring period can be set for signOfLife telegrams of the sensor, see signOfLife and signOfLifeInterval. Default is "on" and an interval of 132 sec.



• Window/Door Contact (EEP A5-14-09, A5-14-0A)
  [Eimsig EM-FSGE-00 sensor]
  
  • W: open|tilt|closed B: unlocked|locked V: on|off U: U/V
  • alarm: dead_sensor
  • batteryState: low|ok
  • vibration: on|off
  • voltage: U/V (Sensor Range: U = 0 V ... 5.0 V)
  • window: open|tilt|closed
  • state: W: open|tilt|closed V: on|off U: U/V
  
  The attr subType must be windowContact. This is done if the device was created by autocreate.
  A monitoring period can be set for signOfLife telegrams of the sensor, see signOfLife and signOfLifeInterval. Default is "on" and an interval of 132 sec.



• Battery Powered Actuator (EEP A5-20-01)
  [Kieback&Peter MD15-FTL-xx]
  
  • T: t/°C SPT: t/°C SP: setpoint/%
  • actuatorState: obstructed|ok
  • alarm: no_response_from_actuator
  • battery: ok|low
  • cover: open|closed
  • delta: <floating-point number>
  • energyInput: enabled|disabled
  • energyStorage: charged|empty
  • maintenanceMode: off|runInit|valveClosed|valveOpend:runInit
  • operationMode: off|setpoint|setpointTemp
  • p_d: <floating-point number>
  • p_i: <floating-point number>
  • p_p: <floating-point number>
  • pidAlarm: actuator_in_errorPos|dead_sensor|no_temperature_value|setpoint_device_missing
  • pidState: alarm|idle|processing|start|stop|
  • roomTemp: t/°C
  • selfCtl: on|off
  • setpoint: setpoint/%
  • setpointSet: setpoint/%
  • setpointCalc: setpoint/%
  • setpointTemp: t/°C
  • setpointTempSet: t/°C
  • teach: <result of teach procedure>
  • temperature: t/°C
  • waitingCmds: no_change|runInit|setpoint|setpointTemp|valveCloses|valveOpens
  • wakeUpCycle: t/s
  • window: open|closed
  • state: T: t/°C SPT: t/°C SP: setpoint/%
  
  The internal temperature sensor (roomTemp) of the Micropelt iTRV is not suitable as a room thermostat.
  The attr subType must be hvac.01. This is done if the device was created by autocreate.



• Heating Radiator Actuating Drive (EEP A5-20-04)
  [Holter SmartDrive MX]
  
  • T: t/°C SPT: t/°C SP: setpoint/%
  • alarm: no_response_from_actuator|measurement_error|battery_empty|frost_protection|blocked_valve|end_point_detection_error|no_valve|not_taught_in|no_response_from_controller|teach-in_error
  • battery: ok|low
  • blockKey: yes|no
  • delta: <floating-point number>
  • feedTemp: t/°C
  • maintenanceMode: off|runInit|valveClosed|valveOpend:runInit
  • measurementState: active|inactive
  • operationMode: off|setpoint|setpointTemp
  • p_d: <floating-point number>
  • p_i: <floating-point number>
  • p_p: <floating-point number>
  • pidAlarm: actuator_in_errorPos|dead_sensor|no_temperature_value|setpoint_device_missing
  • pidState: alarm|idle|processing|start|stop|
  • roomTemp: t/°C
  • setpoint: setpoint/%
  • setpointSet: setpoint/%
  • setpointCalc: setpoint/%
  • setpointTemp: t/°C
  • setpointTempSet: t/°C
  • teach: <result of teach procedure>
  • temperature: t/°C
  • waitingCmds: no_change|runInit|setpoint|setpointTemp|valveCloses|valveOpens
  • wakeUpCycle: t/s
  • state: T: t/°C SPT: t/°C SP: setpoint/%
  
  The attr subType must be hvac.04. This is done if the device was created by autocreate.



• Heating Radiator Actuating Drive (EEP A5-20-06)
  [Micropelt iTRV MVA-005, OPUS Micropelt HOME]
  
  • T: t/°C SPT: t/°C SP: setpoint/%
  • alarm: no_response_from_actuator
  • battery: ok|low
  • blockKey: yes|no
  • delta: <floating-point number>
  • feedTemp: t/°C
  • maintenanceMode: off|runInit|valveClosed|valveOpend:runInit
  • measurementState: active|inactive
  • operationMode: off|setpoint|setpointTemp
  • p_d: <floating-point number>
  • p_i: <floating-point number>
  • p_p: <floating-point number>
  • pidAlarm: actuator_in_errorPos|dead_sensor|no_temperature_value|setpoint_device_missing
  • pidState: alarm|idle|processing|start|stop|
  • radioComErr: off|on
  • radioSignalStrength: obstructed|ok
  • roomTemp: t/°C
  • setpoint: setpoint/%
  • setpointSet: setpoint/%
  • setpointCalc: setpoint/%
  • setpointTemp: t/°C
  • setpointTempSet: t/°C
  • teach: <result of teach procedure>
  • temperature: t/°C
  • waitingCmds: no_change|runInit|setpoint|setpointTemp|standby
  • wakeUpCycle: auto|t/s
  • window: open|closed
  • state: T: t/°C SPT: t/°C SP: setpoint/%
  
  The attr subType must be hvac.06. This is done if the device was created by autocreate.



• Generic HVAC Interface (EEP A5-20-10)
  [IntesisBox PA-AC-ENO-1i]
  
  • on|off
  • ctrl: auto|0...100
  • fanSpeed: auto|1...14
  • occupancy: occupied|off|standby|unoccupied
  • mode: auto|heat|morning_warmup|cool|night_purge|precool|off|test|emergency_heat|fan_only|free_cool|ice|max_heat|eco|dehumidification|calibration|emergency_cool|emergency_stream|max_cool|hvc_load|no_load|auto_heat|auto_cool
  • vanePosition: auto|horizontal|position_2|position_3|position_4|vertical|swing|vertical_swing|horizontal_swing|hor_vert_swing|stop_swing
  • powerSwitch: on|off
  • teach: <result of teach procedure>
  • state: on|off
  
  The attr subType must be hvac.10. This is done if the device was created by autocreate.



• Generic HVAC Interface - Error Control (EEP A5-20-11)
  [IntesisBox PA-AC-ENO-1i]
  
  • error|ok
  • alarm: error|ok
  • errorCode: 0...65535
  • externalDisable: disable|enable
  • keyCardDisable: disable|enable
  • otherDisable: disable|enable
  • powerSwitch: on|off
  • remoteCtrl: disable|enable
  • teach: <result of teach procedure>
  • window: closed|opened
  • windowDisable: disable|enable
  • state: error|ok
  
  The attr subType must be hvac.11. This is done if the device was created by autocreate.



• Digital Input (EEP A5-30-01, A5-30-02)
  [Thermokon SR65 DI, untested]
  
  • open|closed
  • battery: ok|low (only EEP A5-30-01)
  • contact: open|closed
  • teach: <result of teach procedure>
  • state: open|closed
  
  The attr subType must be digitalInput.01 or digitalInput.02. This is done if the device was created by autocreate.



• Digital Input (EEP A5-30-03)
  4 digital Inputs, Wake, Temperature [untested]
  
  • T: t/°C I: 0|1 0|1 0|1 0|1 W: 0|1
  • in0: 0|1
  • in1: 0|1
  • in2: 0|1
  • in3: 0|1
  • teach: <result of teach procedure>
  • temperature: t/°C (Sensor Range: t = 0 °C ... 40 °C)
  • wake: high|low
  • state: T: t/°C I: 0|1 0|1 0|1 0|1 W: high|low
  
  The attr subType must be digitalInput.03. This is done if the device was created by autocreate.



• Smoke Detector (EEP A5-30-03)
  [Eltako TF-RWB]
  
  • smoke-alarm
  • off
  • alarm: dead_sensor|smoke-alarm|off
  • teach: <result of teach procedure>
  • temperature: t/°C (Sensor Range: t = 0 °C ... 40 °C)
  • state: smoke-alarm|off
  
  The attr subType must be digitalInput.03. This is done if the device was created by autocreate. Set attr model to Eltako_TF_RWB manually.



• Digital Input (EEP A5-30-04)
  3 digital Inputs, 1 digital Input 8 bits [untested]
  
  • 0|1 0|1 0|1 0...255
  • in0: 0|1
  • in1: 0|1
  • in2: 0|1
  • in3: 0...255
  • teach: <result of teach procedure>
  • state: 0|1 0|1 0|1 0...255
  
  The attr subType must be digitalInput.04. This is done if the device was created by autocreate.



• Digital Input, single input contact, retransmission, battery monitor (EEP A5-30-05)
  [untested]
  
  • error|event|heartbeat
  • battery: U/V (Range: U = 0 V ... 3.3 V
  • signalIdx: 0 ... 127
  • teach: <result of teach procedure>
  • telegramType: event|heartbeat
  • state: error|event|heartbeat
  
  The attr subType must be digitalInput.05. This is done if the device was created by autocreate.
• Energy management, demand response (EEP A5-37-01)
  
  
  • on|off|waiting_for_start|waiting_for_stop
  • level: 0...15
  • powerUsage: powerUsage/%
  • powerUsageLevel: max|min
  • powerUsageScale: rel|max
  • randomEnd: yes|no
  • randomStart: yes|no
  • setpoint: 0...255
  • teach: <result of teach procedure>
  • timeout: yyyy-mm-dd hh:mm:ss
  • state: on|off|waiting_for_start|waiting_for_stop
  
  The attr subType must be energyManagement.01. This is done if the device was created by autocreate.



• Gateway (EEP A5-38-08)
  Switching
  [Eltako FLC61, FSA12, FSR14]
  
  • on
  • off
  • executeTime: t/s (Sensor Range: t = 0.1 s ... 6553.5 s or 0 if no time specified)
  • executeType: duration|delay
  • block: lock|unlock
  • teach: <result of teach procedure>
  • state: on|off
  
  The attr subType must be gateway and gwCmd must be switching. This is done if the device was created by autocreate.
  For Eltako devices attributes must be set manually. Eltako devices only send on/off.



• Gateway (EEP A5-38-08)
  Dimming
  [Eltako FUD14, FUD61, FUD70, FSG14, ...]
  
  • on
  • off
  • block: lock|unlock
  • dim: dim/% (Sensor Range: dim = 0 % ... 100 %)
  • dimValueLast: dim/%
    Last value received from the bidirectional dimmer.
  • dimValueStored: dim/%
    Last value saved by set <name> dim <value>.
  • rampTime: t/s (Sensor Range: t = 1 s ... 255 s or 0 if no time specified, for Eltako: t = 1 = fast dimming ... 255 = slow dimming or 0 = dimming speed on the dimmer used)
  • teach: <result of teach procedure>
  • state: on|off
  
  The attr subType must be gateway, gwCmd must be dimming and attr manufID must be 00D for Eltako Devices. This is done if the device was created by autocreate.
  For Eltako devices attributes must be set manually. Eltako devices only send on/off and dim.



• Gateway (EEP A5-38-08)
  Setpoint shift
  [untested]
  
  • 1/K
  • setpointShift: 1/K (Sensor Range: T = -12.7 K ... 12.8 K)
  • teach: <result of teach procedure>
  • state: 1/K
  
  The attr subType must be gateway, gwCmd must be setpointShift. This is done if the device was created by autocreate.



• Gateway (EEP A5-38-08)
  Basic Setpoint
  [untested]
  
  • t/°C
  • setpoint: t/°C (Sensor Range: t = 0 °C ... 51.2 °C)
  • teach: <result of teach procedure>
  • state: t/°C
  
  The attr subType must be gateway, gwCmd must be setpointBasic. This is done if the device was created by autocreate.



• Gateway (EEP A5-38-08)
  Control variable
  [untested]
  
  • auto|heating|cooling|off
  • controlVar: cvov (Sensor Range: cvov = 0 % ... 100 %)
  • controllerMode: auto|heating|cooling|off
  • controllerState: auto|override
  • energyHoldOff: normal|holdoff
  • presence: present|absent|standby
  • teach: <result of teach procedure>
  • state: auto|heating|cooling|off
  
  The attr subType must be gateway, gwCmd must be controlVar. This is done if the device was created by autocreate.



• Gateway (EEP A5-38-08)
  Fan stage
  [untested]
  
  • 0 ... 3|auto
  • teach: <result of teach procedure>
  • state: 0 ... 3|auto
  
  The attr subType must be gateway, gwCmd must be fanStage. This is done if the device was created by autocreate.



• Extended Lighting Control (EEP A5-38-09)
  [untested]
  
  • on
  • off
  • block: unlock|on|off|local
  • blue: <blue channel value> (Range: blue = 0 ... 255)
  • dimMax: <maximum dimming value> (Range: dim = 0 ... 255)
  • dimMin: <minimum dimming value> (Range: dim = 0 ... 255)
  • green: <green channel value> (Range: green = 0 ... 255)
  • rampTime: t/s (Range: t = 0 s ... 65535 s)
  • red: <red channel value> (Range: red = 0 ... 255)
  • rgb: RRGGBB (red (R), green (G) or blue (B) color component values: 00 ... FF)
  • teach: <result of teach procedure>
  • state: on|off
  
  Another readings, see subtype lightCtrlState.02.
  The attr subType or subTypSet must be lightCtrl.01. This is done if the device was created by autocreate.
  The subType is associated with the subtype lightCtrlState.02.



• Manufacturer Specific Applications (EEP A5-3F-7F)
  
  Wireless Analog Input Module
  [Thermokon SR65 3AI, untested]
  
  • I1: U/V I2: U/V I3: U/V
  • input1: U/V (Sensor Range: U = 0 V ... 10 V)
  • input2: U/V (Sensor Range: U = 0 V ... 10 V)
  • input3: U/V (Sensor Range: U = 0 V ... 10 V)
  • teach: <result of teach procedure>
  • state: I1: U/V I2: U/V I3: U/V
  
  The attr subType must be manufProfile and attr manufID must be 002 for Thermokon Devices. This is done if the device was created by autocreate.



• Manufacturer Specific Applications (EEP A5-3F-7F)
  
  Thermostat Actuator
  [AWAG omnio UPH230/1x]
  
  • on|off
  • emergencyMode<channel>: on|off
  • nightReduction<channel>: on|off
  • setpointTemp<channel>: t/°C
  • teach: <result of teach procedure>
  • temperature<channel>: t/°C
  • window<channel>: on|off
  • state: on|off
  
  The attr subType must be manufProfile and attr manufID must be 005 for AWAG omnio Devices. This is done if the device was created by autocreate.



• Manufacturer Specific Applications (EEP A5-3F-7F)
  
  Shutter
  [Eltako FSB12, FSB14, FSB61, FSB70]
  
  • open|open_ack
    The status of the device will become "open" after the TOP endpoint is reached, or it has finished an "opens" or "position 0" command.
  • closed
    The status of the device will become "closed" if the BOTTOM endpoint is reached
  • stop
    The status of the device become "stop" if stop command is sent.
  • not_reached
    The status of the device become "not_reached" between one of the endpoints.
  • anglePos: α/° (Sensor Range: α = -180 ° ... 180 °)
  • endPosition: open|open_ack|closed|not_reached|not_available
  • position: pos/% (Sensor Range: pos = 0 % ... 100 %)
  • teach: <result of teach procedure>
  • state: open|open_ack|closed|not_reached|stop|teach
  
  The values of the reading position and anglePos are updated automatically, if the command position is sent or the reading state was changed manually to open or closed.
  



• Manufacturer Specific Applications (EEP A5-3F-7F)
  
  Shutter
  [Eltako FRM60]
  
  • <pos/%>
  • open
    The status of the device will become "open" after the TOP endpoint is reached.
  • closed
    The status of the device will become "closed" if the BOTTOM endpoint is reached
  • endPosition: open|closed|not_reached
  • position: pos/% (Sensor Range: pos = 0 % ... 100 %)
  • teach: <result of teach procedure>
  • state: open|closed|<pos/%>
  
  



• Electronic switches and dimmers with Energy Measurement and Local Control (D2-01-00 - D2-01-12)
  [Telefunken Funktionsstecker, PEHA Easyclick, AWAG Elektrotechnik AG Omnio UPS 230/xx,UPD 230/xx]
  
  • on
  • off
  • autoOffTime<1...29|All|Input>: 1/s
  • channel<0...29|All|Input>: on|off
  • delayOffTime<1...29|All|Input>: 1/s
  • dayNight: day|night
  • defaultState: on|off|last
  • devTemp: t/°C|invalid
  • devTempState: ok|max|warning
  • dim<0...29|Input>: dim/% (Sensor Range: dim = 0 % ... 100 %)
  • energy<channel>: E/[Ws|Wh|KWh]
  • energyUnit<channel>: Ws|Wh|KWh
  • error<channel>: ok|warning|failure|not_supported
  • extSwitchMode<1...29|All|Input>: unavailable|switch|pushbutton|auto
  • extSwitchType<1...29|All|Input>: toggle|direction
  • firmwareVersion: [000000 ... FFFFFF]
  • loadClassification: no
  • localControl<channel>: enabled|disabled
  • loadLink: connected|disconnected
  • loadOperation: 3-wire
  • loadState: on|off
  • measurementMode: energy|power
  • measurementReport: auto|query
  • measurementReset: not_active|trigger
  • measurementDelta: E/[Ws|Wh|KWh|W|KW]
  • measurementUnit: Ws|Wh|KWh|W|KW
  • overCurrentOff<channel>: executed|ready
  • overCurrentShutdown<channel>: off|restart
  • overCurrentShutdownReset<channel>: not_active|trigger
  • power<channel>: P/[W|KW]
  • powerFailure<channel>: enabled|disabled
  • powerFailureDetection<channel>: detected|not_detected
  • powerUnit<channel>: W|KW
  • rampTime<1...3l>: 1/s
  • responseTimeMax: 1/s
  • responseTimeMin: 1/s
  • roomCtrlMode: off|comfort|comfort-1|comfort-2|economy|buildingProtection
  • serialNumber: [00000000 ... FFFFFFFF]
  • taughtInDevID<00...23>: [00000001 ... FFFFFFFE]
  • taughtInDevNum: [0 ... 23]
  • teach: <result of teach procedure>
  • teachInDev: enabled|disabled
  • state: on|off
  
  The attr subType must be actuator.01. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out.



• Blind Control for Position and Angle (D2-05-00, D2-05-01, D2-05-02, D2-05-04, D2-05-05)
  [AWAG Elektrotechnik AG OMNIO UPJ 230/12, REGJ12/04M, miniJ01]
  
  • open
    The status of the device will become "open" after the TOP endpoint is reached, or it has finished an "opens" or "position 0" command.
  • closed
    The status of the device will become "closed" if the BOTTOM endpoint is reached
  • stop
    The status of the device become "stop" if stop command is sent.
  • not_reached
    The status of the device become "not_reached" between one of the endpoints.
  • pos/% (Sensor Range: pos = 0 % ... 100 %)
  • anglePos<channel>: α/% (Sensor Range: α = 0 % ... 100 %)
  • currentRun<channel>: down|stopped|up|unknown
  • block<channel>: unlock|lock|alarm
  • endPosition<channel>: open|closed|not_reached|unknown
  • position<channel>: unknown|pos/% (Sensor Range: pos = 0 % ... 100 %)
  • teach: <result of teach procedure>
  • state: open|closed|in_motion|stopped|pos/% (Sensor Range: pos = 0 % ... 100 %)
  
  The attr subType must be blindsCtrl.00 or blindsCtrl.01. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out.



• Multisensor Window Handle (D2-06-01)
  [Soda GmbH]
  
  • T: t/°C H: -|rH/% E: -|E/lx M: off|on|invalid|not_supported|unknown
  • alarms: <alarms> (Range: alarms = 00000000 ... FFFFFFFF)
  • battery: ok|low
  • batteryLowClick: enabled|disabled
  • blinkInterval: t/s|unknown (Range: t = 3 s ... 255 s)
  • blinkIntervalSet: t/s|unknown (Range: t = 3 s ... 255 s)
  • brightness: E/lx|over_range|invalid|not_supported|unknown (Sensor Range: E = 0 lx ... 60000 lx)
  • burglaryAlarm: off|on|invalid|not_supported|unknown
  • buttonLeft: pressed|released|invalid|not_supported|unknown
  • buttonLeftPresses: <buttonLeftPresses> (Range: buttonLeftPresses = 00000000 ... FFFFFFFF)
  • buttonRight: pressed|released|invalid|not_supported|unknown
  • buttonRightPresses: <buttonRightPresses> (Range: buttonRightPresses = 00000000 ... FFFFFFFF)
  • energyStorage: 1/%|unknown
  • handle: up|down|left|right|invalid|not_supported|unknown
  • handleClosedClick: enabled|disabled
  • handleMoveClosed: <handleMoveClosed> (Range: handleMoveClosed = 00000000 ... FFFFFFFF)
  • handleMoveOpend: <handleMoveOpend> (Range: handleMoveOpend = 00000000 ... FFFFFFFF)
  • handleMoveTilted: <handleMoveTilted> (Range: handleMoveTilted = 00000000 ... FFFFFFFF)
  • humidity: rH/%|invalid|not_supported|unknown
  • motion: off|on|invalid|not_supported|unknown
  • powerOns: <powerOns> (Range: powerOns = 00000000 ... FFFFFFFF)
  • presence: absent|present|invalid|not_supported|unknown
  • protectionAlarm: off|on|invalid|not_supported|unknown
  • temperature: t/°C|invalid|not_supported|unknown (Sensor Range: t = -20 °C ... 60 °C)
  • updateInterval: t/s|unknown (Range: t = 5 s ... 65535 s)
  • updateIntervalSet: t/s|unknown (Range: t = 5 s ... 65535 s)
  • waitingCmds: <integer number>
  • window: undef|not_tilted|tilted|invalid|not_supported|unknown
  • windowTilts: <windowTilts> (Range: windowTilts = 00000000 ... FFFFFFFF)
  • state: T: t/°C H: -|rH/% E: -|E/lx M: off|on|invalid|not_supported|unknown
  
  The attr subType must be multisensor.01. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out.



• Window and Handle Position Multisensor (D2-06-50)
  [senso secure SIEGENIA-AUBI KG]
  
  • closed|open|tilted
  • alarm: dead_sensor
  • battery: ok|low
  • batteryPercent: 0 ... 100/%
  • burglaryAlarm: off|on
  • calibrationStep: none|close_handle|open_handle|tilt_handle|close_window
  • handle: closed|open|tilted
  • statusAcceleration: ok|error|not_supported
  • statusCalibration: ok|error|invalid
  • statusCntr: <statusCntr> (Range: statusCntr = 00000000 ... FFFFFFFF)
  • statusMagnetic: ok|error|not_supported
  • statusMotion: ok|error|not_supported
  • statusSystem: ok|error|not_supported
  • telegramType: event|heartbeat
  • window: closed|open|tilted
  • state: W: closed|open|tilted H: closed|open|tilted B: ok|low
  
  The multisensor is configured using the following attributes:
  
  • subDefH
  • subDefW
  A monitoring period can be set for signOfLife telegrams of the sensor, see signOfLife and signOfLifeInterval. Default is "on" and an interval of 990 sec.
  After the teach-in, the sensor must be calibrated immediately. The procedure is described in the user manual. If calibration was successful, the reading calibrationStep displays none and statusCalibration ok.
  The attr subType must be multisensor.50. This is done if the device was created by autocreate.



• Room Control Panels (D2-10-00 - D2-10-02)
  [Kieback & Peter RBW322-FTL]
  
  • T: t/°C H: -|rH/% F: 0 ... 100/% SPT: t/°C O: -|absent|present M: -|on|off
  • battery: ok|low|empty|-
  • cooling: auto|on|off|-
  • customWarning[1|2]: on|off
  • fanSpeed: 0 ... 100/%
  • fanSpeedMode: central|local
  • heating: auto|on|off|-
  • humidity: -|rH/%
  • moldWarning: on|off
  • motion: on|off|-
  • occupancy: -|absent|present
  • roomCtrlMode: buildingProtection|comfort|economy|preComfort
  • setpointBuildingProtectionTemp: -|t/°C (Range: t = 0 °C ... 40 °C)
  • setpointComfortTemp: -|t/°C (Range: t = 0 °C ... 40 °C)
  • setpointEconomyTemp: -|t/°C (Range: t = 0 °C ... 40 °C)
  • setpointPreComfortTemp: -|t/°C (Range: t = 0 °C ... 40 °C)
  • setpointTemp: t/°C (Range: t = 0 °C ... 40 °C)
  • solarPowered: yes|no
  • temperature: t/°C (Sensor Range: t = 0 °C ... 40 °C)
  • window: closed|open
  • state: T: t/°C H: -|rH/% F: 0 ... 100/% SPT: t/°C O: -|absent|present M: -|on|off
  
  The attr subType must be roomCtrlPanel.00. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out.



• Room Control Panels (D2-11-01 - D2-11-08)
  [Thermokon EasySens SR06 LCD-2T/-2T rh -4T/-4T rh]
  
  • T: t/°C H: rH/% SPT: t/°C F: auto|off|1|2|3 O: occupied|unoccupied
  • cooling: on|off
  • fanSpeed: auto|off|1|2|3
  • heating: on|off
  • humidity: rH/%
  • occupancy: occupied|unoccupied
  • setpointBase: t/°C (Range: t = 15 °C ... 30 °C)
  • setpointShift: t/K (Range: t = -10 K ... 10 K)
  • setpointShiftMax: t/K (Range: t = 0 K ... 10 K)
  • setpointTemp: t/°C (Range: t = 5 °C ... 40 °C)
  • setpointType: setpointTemp|setpointShift
  • temperature: t/°C (Sensor Range: t = 0 °C ... 40 °C)
  • trigger: heartbeat|sensor|input
  • window: closed|open
  • state: T: t/°C H: rH/% SPT: t/°C F: auto|off|1|2|3 O: occupied|unoccupied
  
  The attr subType must be roomCtrlPanel.01. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired by Smart Ack, see SmartAck Learning.



• Sensor for Smoke, Air quality, Hygrothermal comfort, Temperature and Humidity (D2-14-30)
  [INSAFE+ Origin I870EO untested]
  
  • off|smoke-alarm
  • airQuality: optimal|air_dry|humidity_high|teperature_humidity_high|error
  • alarm: off|smoke-alarm|dead_sensor
  • battery: ok|medium|low|critical
  • endOffLife: t/month (Range t = 0...120 month
  • humidity: rH/%
  • hygrothermalComfort: good|medium|bad|error
  • maintenanceLast: t/week (Range t = 0...250 week
  • sensorFaultMode: off|on
  • smokeAlarmHumidity: ok|not_ok
  • smokeAlarmMaintenance: ok|not_done
  • smokeAlarmTemperature: ok|not_ok
  • teach: <result of teach procedure>
  • temperature: t/°C (Sensor Range: t = 0 °C ... 50 °C)
  • state: off|smoke-alarm
  
  The attr subType must be multiFuncSensor.30. This is done if the device was created by autocreate.



• Sensor for Temperature and Humidity, XYZ Acceleration, Illumination, Contact (D2-14-40 - D2-14-41)
  [EnOcean ST 550, EnOcean EMSIA]
  
  • T: <temperature> H: <humidity> B: <brightness> AS <acceleration status> C: closed|open
  • acceleration_status: heartbeat|treshold_1|treshold_2|reserved
  • acceleration_x: α/g (Sensor Range: α = 0 g ... 2.5 g)
  • acceleration_y: α/g (Sensor Range: α = 0 g ... 2.5 g)
  • acceleration_z: α/g (Sensor Range: α = 0 g ... 2.5 g)
  • alarm: temperature_out_of_range_negative|temperature_out_of_range_positive|temperature_error|humidity_error|brightness_error| acceleration_x_out_of_range_negative|acceleration_x_out_of_range_positive|acceleration_x_error|dead_sensor
  • batteryPercent: 1/%
  • brightness: E/lx (Sensor Range: E = 0 lx ... 100000 lx)
  • contact: closed|open
  • humidity: rH/%
  • teach: <result of teach procedure>
  • temperature: t/°C (Sensor Range: t = -40 °C ... 60 °C)
  • state: T: <temperature> H: <humidity> B: <brightness> AS <acceleration status> C: closed|open
  
  The attr subType must be multiFuncSensor.40. This is done if the device was created by autocreate. A monitoring period can be set for signOfLife telegrams of the sensor, see signOfLife and signOfLifeInterval. Default is "on" and an interval of 216 sec.
  



• People Activity Counter (D2-15-00)
  [EOcean EASYFIT EPAC untested]
  
  • 0 ... 100/%
  • activity: 0 ... 100/%
  • alarm: off|dead_sensor
  • battery: ok|medium|low|critical
  • present: present|absent|not_detectable|error
  • teach: <result of teach procedure>
  • state: 0 ... 100/%
  
  The attr subType must be multiFuncSensor.00. This is done if the device was created by autocreate.



• Fan Control (D2-20-00 - D2-20-02)
  [Maico ECA x RC/RCH, ER 100 RC, untested]
  
  • on|off|not_supported
  • fanSpeed: 0 ... 100/%
  • error: ok|air_filter|hardware|not_supported
  • humidity: rH/%|not_supported
  • humidityCtrl: disabled|enabled|not_supported
  • roomSize: 0...350/m²|max
  • roomSizeRef: unsed|not_used|not_supported
  • setpointTemp: t/°C (Range: t = 0 °C ... 40 °C)
  • teach: <result of teach procedure>
  • temperature: t/°C (Sensor Range: t = 0 °C ... 40 °C)
  • state: on|off|not_supported
  
  The attr subType must be fanCtrl.00. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out.



• AC Current Clamp (D2-32-00 - D2-32-02)
  [untested]
  
  • I1: I/A I2: I/A I3: I/A
  • current1: I/A (Range: I = 0 A ... 4095 A)
  • current2: I/A (Range: I = 0 A ... 4095 A)
  • current3: I/A (Range: I = 0 A ... 4095 A)
  • teach: <result of teach procedure>
  • state: I1: I/A I2: I/A I3: I/A
  
  The attr subType must be currentClamp.00|currentClamp.01|currentClamp.02. This is done if the device was created by autocreate.



• Heating Actuator (D2-34-00 - D2-34-02)
  [AWAG UPS230/10, UPS230/12, REGH12/08M]
  
  • <0...29|All>: heating
  • <0...29|All>: no_heating
  • <0...29|All>: off
  • <0...29|All>: temperature_unknown
  • channel<0...29|All>: setpointTempRefDev|setpointTemp|setpointTempShift
  • operationMode<1...29|All>: heating|no_heating|off|temperature_unknown
  • overridePeriod<1...29|All|>: t/h
  • setpointTemp<1...29|All>: t/°C
  • setpointTempRefDev<1...29|All>: t/°C
  • setpointTempShift<1...29|All>: t/K
  • teach: <result of teach procedure>
  • temperature<1...29|All>: t/°C
  • state: <0...29|All>: heating|no_heating|off|temperature_unknown
  
  The attr subType must be heatingActuator.00. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out.



• LED Controller Status (EEP D2-40-00 - D2-40-01)
  [untested]
  
  • on|off
  • blue: 0 % ... 100 %
  • daylightHarvesting: on|off
  • demandResp: on|off
  • dim: 0 % ... 100 %
  • green: 0 % ... 100 %
  • occupany: unoccupied|occupied|unknown
  • powerSwitch: on|off
  • red: 0 % ... 100 %
  • rgb: RRGGBB (red (R), green (G) or blue (B) color component values: 00 ... FF)
  • teach: <result of teach procedure>
  • telegramType: event|heartbeat
  • state: on|off
  
  The attr subType must be ledCtrlState.00|ledCtrlState.01 This is done if the device was created by autocreate.



• Heat Recovery Ventilation (D2-50-00 - D2-50-11)
  [untested]
  
  • off|1...4|auto|demand|supplyAir|exhaustAir
  • airQualidity1: 1/%
  • airQualidity2: 1/%
  • airQualidityThreshold: default|1/%
  • CO2Threshold: default|1/%
  • coolingProtection: on|off
  • defrost: on|off
  • deviceMode: master|slave
  • drainHeater: on|off
  • exhaustAirFlap: closed|opend
  • exhaustAirFlow: h/m3 (Sensor Range: Q = 0 m3/h ... 1023 m3/h)
  • exhaustFanSpeed: min (Sensor Range: n = 0 / min ... 4095 / min)
  • exhaustTemp: t/°C (Sensor Range: t = -63 °C ... 63 °C)
  • fault: bbbbbbbb bbbbbbbb bbbbbbbb bbbbbbbb (b = 0|1)
  • filterMaintenance: required|not_required
  • fireplaceSafetyMode: disabled|enabled
  • heatExchangerBypass: closed|opend
  • humidityThreshold: default|rH/%
  • info: bbbbbbbb bbbbbbbb (b = 0|1)
  • input: bbbbbbbb bbbbbbbb (b = 0|1)
  • operationHours: [0 ... 589815]
  • output: bbbbbbbb bbbbbbbb (b = 0|1)
  • outdoorAirHeater: on|off
  • outdoorTemp: t/°C (Sensor Range: t = -63 °C ... 63 °C)
  • roomTemp: t/°C (Sensor Range: t = -63 °C ... 63 °C)
  • roomTempCtrl: on|off
  • roomTempSet: default|t/°C (Sensor Range: t = -63 °C ... 63 °C)
  • supplyAirFlow: h/m3 (Sensor Range: Q = 0 m3/h ... 1023 m3/h)
  • supplyAirFlap: closed|opend
  • supplyAirHeater: on|off
  • supplyFanSpeed: min (Sensor Range: n = 0 / min ... 4095 / min)
  • supplyTemp: t/°C (Sensor Range: t = -63 °C ... 63 °C)
  • SWVersion: [0 ... 4095]
  • timerMode: on|off
  • weeklyTimer: on|off
  • state: off|1...4|auto|demand|supplyAir|exhaustAir
  
  The attr subType must be heatRecovery.00. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out.



• Valve Control (EEP D2-A0-01)
  
  • opens
  • open
  • closes
  • closed
  • teach: <result of teach procedure>
  • state: opens|open|closes|closed|teachIn|teachOut
  
  The attr subType must be valveCtrl.00. This is done if the device was created by autocreate. To control the device, it must be bidirectional paired, see Bidirectional Teach-In / Teach-Out.



• Liquid Leakage Sensor (EEP D2-B0-51)
  [untested]
  
  • dry
  • wet
  • state: dry|wet
  
  The attr subType must be liquidLeakage.51. This is done if the device was created by autocreate.



• Generic Profiles
  
  • <00...64>-<channel name>: <value>
  • <00...64>-<channel name>Unit: <value>
  • <00...64>-<channel name>ValueType: value|setpointAbs|setpointRel
  • <00...64>-<channel name>ChannelType: teachIn|data|flag|enum
  • teach: <result of teach procedure>
  
  The attr subType must be genericProfile. This is done if the device was created by autocreate. If the profile in slave mode is operated, especially the channel definition in the gpDef attributes must be entered manually.



• RAW Command
  
  • RORG: 1BS|4BS|ENC|MCS|RPS|SEC|STE|UTE|VLD
  • dataSent: data (Range: 1 Byte hex ... 512 Byte hex)
  • statusSent: status (Range: 0x00 ... 0xFF)
  • state: RORG: rorg DATA: data STATUS: status ODATA: odata
  
  With the help of this command data messages in hexadecimal format can be sent and received. The telegram types (RORG) 1BS and RPS are always received protocol-specific. For further information, see EnOcean Equipment Profiles (EEP).
  Set attr subType to raw manually.



• Light and Presence Sensor
  [Omnio Ratio eagle-PM101]
  
  • on
  • off
  • brightness: E/lx (Sensor Range: E = 0 lx ... 1000 lx)
  • channel1: on|off
    Motion message in depending on the brightness threshold
  • channel2: on|off
    Motion message
  • motion: on|off
    Channel 2
  • state: on|off
    Channel 2
  
  The sensor also sends switching commands (RORG F6) with the SenderID-1.
  Set attr subType to PM101 manually. Automatic teach-in is not possible, since no EEP and manufacturer ID are sent.



• Radio Link Test
  
  • standby|active|stopped
  • msgLost: msgLost/%
  • rssiMasterAvg: LP/dBm
  • state: standby|active|stopped
    
  
  The attr subType must be readioLinkTest. This is done if the device was created by autocreate or manually by define <name> EnOcean A5-3F-00
  .

EseraAnalogInOut

This module implements a 1-wire analog input/output. It uses 66_EseraOneWire
as I/O device.

Define
define <name> EseraAnalogInOut <ioDevice> <oneWireId> <deviceType> <lowLimit> <highLimit>
<oneWireId> specifies the 1-wire ID of the analog input/output chip.
Use the "get devices" query of EseraOneWire to get a list of 1-wire IDs,
or simply rely on autocreate.
Supported values for deviceType:
• SYS3 (analog output build into the Esera Controller 2, Note: This does not show up in the "get devices" response.)
• DS2450 (4x analog input)
• 11202 (4x analog input)
• 11203 (4x analog input)
• 11208 (analog output, voltage)
• 11219 (analog output, current)
This module knows the high and low limits of the supported devices. You might
want to further reduce the output range, e.g. to protect hardware connected to the
output from user errors. You can use the parameters <lowLimit> and <highLimit> to do
so. You can also give "-" for <lowLimit> and <highLimit>. In this case the module uses
the maximum possible output range.


Set
This applies to analog outputs only.
• set <name> out <value>
  Controls the analog output. <value> specifies the new value.
  
• set <name> on
  Switch output to "high" value. The on value has to be specified as attribute HighValue.
  
• set <name> off
  Switch output to "low" value. The on value has to be specified as attribute LowValue.
  

Get
• no get functionality

Attributes
• LowValue (see above)
• HighValue (see above)

Readings
• in – analog input value
• out – analog output value

EseraCount

This module supports DS2423 1-wire dual counters.
It uses 66_EseraOneWire as I/O device.

Define
define <name> EseraCount <ioDevice> <oneWireId> <deviceType>
<oneWireId> specifies the 1-wire ID of the sensor. Use the "get devices"
query of EseraOneWire to get a list of 1-wire IDs, or simply rely on autocreate.
The only supported <deviceType> is DS2423.
Set
• no get functionality

Get
• no get functionality

Attributes
• ticksPerUnit1
ticksPerUnit2
  These attribute are applied to readings count1 / count2 and
  count1Today / count2Today.
  The default value is 1. The attribute is used to convert the raw
  tick count to meaningful value with a unit.
• movingAverageCount1
movingAverageCount2
  see description of reading count1MovingAverage and count2MovingAverage
  default: 1
• movingAverageFactor1
movingAverageFactor2
  see description of reading count1MovingAverage and count2MovingAverage
  default: 1

Readings
• count1
count2
  The counter values for channel 1 and 2. These are the counter values with
  attributes ticksPerUnit1 and ticksPerUnit2 applied.
• count1Today
count2Today
  Similar to count1 and count2 but with a reset at midnight.
• count1MovingAverage
count2MovingAverage
  Moving average of the last movingAverageCount1 and movingAverageCount2samples,
  multiplied with movingAverageFactor1 or movingAverageFactor2. This reading and
  the related attributes are used to derive a power value value from the S0 count of an
  energy meter. Samples must have a fixed and known period. This is the case with the Esera 1-wire
  controller. When selecting a value for movingAverageFactor1 and movingAverageFactor2 the sample
  period has to be considered.
  

EseraDigitalInOut

This module implements a 1-wire digital input/output. It uses 66_EseraOneWire
as I/O device.

Define
define <name> EseraDigitalInOut <ioDevice> <oneWireId> <deviceType> <bitPos> <bitCount>
<oneWireId> specifies the 1-wire ID of the digital input/output chip.
Use the "get devices" query of EseraOneWire to get a list of 1-wire IDs,
or simply rely on autocreate.
Supported values for deviceType:
• DS2408
• 11220/11228 (Esera "Digital Out 8-Channel with push-button interface")
• 11233 (Esera "Digital Out 2-Channel with push-button interface")
• 11229 (Esera "Digital Out 8-Channel")
• 11216 (Esera "8-Channel Digital Input DC")
• SYS1 (Esera Controller 2, digital input, not listed by "get devices")
• SYS2 (Esera Controller 2, digital output, not listed by "get devices")
The bitPos and bitCount parameters is used to specify a subset of bits only.
For example, the DS2408 has 8 inputs, and you can define a EseraDigitalInOut
that uses bits 4..7 (in range 0..7). In this case you specify bitPos = 4 and
bitWidth = 4.
You can also give "-" for bitPos and bitWidth. In this case the module uses
the maximum possible bit range, which is bitPos = 0 and bitWidth = 8 for DS2408.
In typical use cases the n bits of a digital input device are used to control
or observe n different things, e.g. 8 motion sensors connected to 8 digital inputs.
In this case you would define 8 EseraDigitalInOut devices, one for each motion sensor.


Set
• set <name> out <bitMask> <bitValue>
  Controls digital outputs. The bitMask selects bits that are programmed,
  and bitValue specifies the new value.
  Examples: set myEseraDigitalInOut out 0xf 0x3
  In this example the four lower outputs are selected by the mask,
  and they get the new value 0x3 = 0b0011.
  bitMask and bitValue can be specified as hex number (0x...), binary
  number (0b....) or decimal number.
  Note: If all bits are selected by mask the outputs are set by a single
  access to the controller. If subset of bits is selected the bits are set
  by individual accesses, one after the other, as fast as the controller allows.
  
• set <name> on
  Switch on all outputs.
  
• set <name> off
  Switch off all outputs.
  

Get
• no get functionality

Attributes
• no attributes

Readings
• in – digital input state
• out – digital output state

EseraDimmer

This module implements an Esera 1-wire dimmer. It uses 66_EseraOneWire as I/O device.

Define
define <name> EseraDimmer <ioDevice> <oneWireId> <deviceType> <channel>
<oneWireId> specifies the 1-wire ID of the digital input/output chip.
Use the "get devices" query of EseraOneWire to get a list of 1-wire IDs,
or simply rely on autocreate.
Supported values for deviceType:
• 11221
• 11222
<channel> specifies the channel, 1 or 2.

Set
• set <name> out <value>
  
• set <name> on
  Sets the dimmer to the maximum value 31.
  
• set <name> off
  Sets the dimmer to the minimum value 0.
  
• set <name> up
  Increase dimmer value by 1.
  
• set <name> down
  Reduce dimmer value by 1.
  

Readings
• out – output state
• button – state of the push button, 1=pressed, 0=not pressed

EseraIButton

This module supports 1-wire iButton devices. It uses 66_EseraOneWire as I/O device.
Events are generated for connecting and disconnecting an iButton.

The Esera Controller needs to know the iButton so that it can detect it quickly when it
is connected. The iButton needs to be in the list of devices which is stored in a non-volatile
memory in the controller. Initially, you need to connect a new iButton for ~10 seconds. Use the
"get devices" query of EseraOneWire to check whether the device has been detected. When it has
been detected use "set savelist" to store the current list in the controller. Repeat the same
procedure with additional iButtons. Alternatively, you can use the "Config Tool 3" software from
Esera to store iButton devices in the controller.

It is stronly recommended to use the additional license "iButton Fast Mode" from Esera (product
number 40202). With this license the controller detects iButton devices quickly. Without that
license the controller sometimes needs quite long to detect an iButton.

See the "Programmierhandbuch" from Esera for details.

Define
define <name> EseraIButton <ioDevice> <oneWireId> <deviceType>
<oneWireId> specifies the 1-wire ID of the iButton.
Supported values for deviceType: DS2401


Set
• no set functionality

Get
• no get functionality

Attributes
• no attributes

Readings
• status – connection status 0 or 1

EseraMulti

This module supports an Esera 1-wire multi sensor or a DS2438 1-wire IC.
It uses 66_EseraOneWire as I/O device.

Define
define <name> EseraMulti <ioDevice> <oneWireId> <deviceType>
<oneWireId> specifies the 1-wire ID of the sensor. Use the "get devices"
query of EseraOneWire to get a list of 1-wire IDs, or simply rely on autocreate.
Supported values for deviceType:
• DS2438
• 11112 (Esera product number, multi sensor Solar)
• 11121 (Esera product number)
• 11132 (Esera product number, multi sensor Unterputz)
• 11133 (Esera product number, multi sensor Unterputz)
• 11134 (Esera product number, multi sensor Aufputz)
• 11135 (Esera product number, multi sensor Outdoor)
With deviceType DS2438 this device generates readings with un-interpreted data
from DS2438. This can be used with any DS2438 device, independent of an Esera
product. With deviceType 11112/11121/11132/11133/11134/11135 this module provides interpreted
readings like humidity or dew point.

Set
• no get functionality

Get
• no get functionality

Attributes
• no attributes

Readings
readings for DS2438:

• VAD
• VCC
• VSense
• temperature
readings for Esera 11121/11132/11133/11134/11135:

• temperature
• humidity
• dewpoint
• brightness
• voltage
readings for Esera 11112:

• temperature (°C)
• radiation (W/m²)
• brightness (Lux)
• voltage (V)

EseraOneWire

This module provides an interface to Esera 1-wire controllers.
The module works in conjunction with 66_Esera* modules which support
various 1-wire devices. See these modules for more information
about supported 1-wire devices. This module supports autocreate.

The module is tested with "Controller 1" and "Controller 2" with
TCP/IP interface, implementing the Esera ASCII protocol as described
in the Esera Controller Programmierhandbuch. The module
supports serial connections as well, for controllers with serial/USB
interface. It is tested with EseraStation 200.

Tested with Esera controller firmware version 12029.

Define
define <name> EseraOneWire <ip-address>
Example: define myEseraOneWireController EseraOneWire 192.168.0.15
Example: define myEseraOneWireController EseraOneWire /dev/ttyUSB0


Set
• set <name> clearlist
  Clear the list of devices which is persistently stored in the controller.
  
• set <name> savelist
  Save the current list of devices persistently in the controller. This is only
  required when using iButton devices. See module EseraIButton for more information.
• set <name> reset controller
  Sends a reset command to the controller.
  
• set <name> reset tasks
  The module internally queues tasks. Tasks are requests to the controller
  which need to executed one after the other. For debug purposes only the
  module provides a way to clear the queue.
  
• set <name> refresh
  Triggers a read of updated information from the controller, including
  settings, list of devices and controller info. In normal operation it
  is not needed to call thi when the 1-wire devices are added. The module
  triggers a re-read automatically if readings are received from unknown
  devices.
  
• set <name> raw <command>
  Debug only: Allows the user to send an arbitrary low level command to the
  controller. The command is a command as described in the Esera Controller
  Programmierhandbuch, without spaces, with commas as seperators, and without
  trailing new line character.
  The raw command and the received response are stored as internals
  RAW_COMMAND and RAW_RESPONSE.
  
  Examples:
  
  • set myEseraOneWireController raw get,sys,datatime
  • set myEseraOneWire raw set,sys,datatime,0
• set <name> close
  Close the TCP/IP connection to the controller.
  
• set <name> open
  Open the TCP/IP connection to the controller.
  

Get
• get <name> info
  Prints various information about the controller like part number,
  serial number, date of manufacturing.
  
• get <name> settings
  Returns various controller settings for debug purposes. New information
  is retrieved when set refresh or get settings is called. New data
  can then be printed with the following call of get settings. It is
  implemented like this because it is a simple way to avoid blocking reads.
  For more information regarding the individual settings please refer to the
  Esera Controller Programmierhandbuch which can be downloaded from
  www.esera.de .
  
• get <name> devices
  Returns the list of currently connected 1-wire devices.
  The format of each list entry is
  <oneWireId>,<eseraId>,<deviceType>;
  
• get <name> status
  Reports currently known status of all connected 1-wire devices.
  The format of each list entry is
  <oneWireId>,<eseraId>,<deviceType>,<status>,<errors>;
  New status information is retrieved from the known devices when
  get status is called. New data can then be printed with
  the following call of get status. It is implemented like
  this because it is a simple way to avoid blocking reads.
  

Readings
• state – possible values are:
  • opened – connection to controller established (from DevIo)
  • disconnected – disconnected from controller (from DevIo)
  • failed – connection to controller failed (from DevIo)
  • initializing – controller initialization in progress
  • initialized – controller initialization done
  • ready – fully functional

Attributes
• pollTime – POLLTIME setting of the controller, see controller manual, default: 5
• dataTime – DATATIME setting of the controller, see controller manual, default: 10

Events
• CONNECTED – from DevIo
• DISCONNECTED – from DevIo
• FAILED – from DevIo
• READY – fully functional

EseraShutter

This module implements an Esera 1-wire shutter. It uses 66_EseraOneWire as I/O device.

Define
define <name> EseraShutter <ioDevice> <oneWireId> <deviceType>
<oneWireId> specifies the 1-wire ID of the shutter device.
Do not rely on autocreate. The Esera product by default shows up as a DS2408 in the device list of the
Esera controller. Autocreate would create a EseraDigitalInOut FHEM device. Use Esera's ConfigTool3 to
assign the appropriate article number, e.g. 11231, to the 1-wire device in the controller, and set up
the FHEM device with the same <deviceType>.
Supported values for deviceType:

• 11209
• 11231

Set
• set <name> down
  
• set <name> up
  
• set <name> stop
  

Get
• no get functionality

Attributes
• no attributes

Readings
• input – none|down|up|stop
• output – none|down|up|stop

EseraTemp

This module implements a 1-wire temperature sensor. It uses 66_EseraOneWire
as I/O device.

Define
define <name> EseraTemp <ioDevice> <oneWireId> <deviceType>
<oneWireId> specifies the 1-wire ID of the sensor. Use the "get devices"
query of EseraOneWire to get a list of 1-wire IDs, or simply rely on autocreate.
Supported values for deviceType:

• DS1820
Note: Esera 11131 temperature sensor is a DS1820.

Set
• no set functionality

Get
• no get functionality

Attributes
• no attributes

Readings
• temperature – temperature in degrees Celsius

FBAHA

Note: Fritz!OS 6.90 and later does not offer the AHA service needed by this module. Use the successor FBAHAHTTP instead of this module.
This module connects to the AHA server (AVM Home Automation) on a FRITZ!Box. It serves as the "physical" counterpart to the FBDECT devices. Note: you have to enable the access to this feature in the FRITZ!Box frontend first.

Define
define <name> FBAHA <device>

<device> is either a <host>:<port> combination, where <host> is normally the address of the FRITZ!Box running the AHA server (fritz.box or localhost), and <port> 2002, or UNIX:SEQPACKET:/var/tmp/me_avm_home_external.ctl, the latter only works on the fritz.box. With FRITZ!OS 5.50 the network port is available, on some Labor variants only the UNIX socket is available.
Example:
define fb1 FBAHA fritz.box:2002
define fb1 FBAHA UNIX:SEQPACKET:/var/tmp/me_avm_home_external.ctl


Set
• createDevs
  create a FHEM device for each DECT device found on the AHA-Host, see also get devList.
• reopen
  close and reopen the connection to the AHA server. Debugging only.
• reregister
  release existing registration handle, and get a new one. Debugging only.

Get
• devList
  return a list of devices with short info.

Attributes
• dummy

Generated events:
• UNDEFINED FBDECT_$ahaName_${NR} FBDECT $id"

As sometimes the FRITZ!Box reassigns the internal id's of the FBDECT devices, the FBAHA module compares upon connect/reconnect the stored names (FBNAME) with the current value. This feature will only work, if you assign each FBDECT device a unique Name in the FRITZ!Box, and excecute the FHEM "get FBDECTDEVICE devInfo" command, which saves the FBNAME reading.

FBAHAHTTP

This module connects to the AHA server (AVM Home Automation) on a FRITZ!Box via HTTP, it is a successor/drop-in replacement for the FBAHA module. It is necessary, as the FBAHA interface is deprecated by AVM. Since the AHA HTTP interface do not offer any notification mechanism, the module is regularly polling the FRITZ!Box.
Important: For an existing installation with an FBAHA device, defining a new FBAHAHTTP device will change the IODev of all FBDECT devices from the old FBAHA to this FBAHAHTTP device, and it will delete the FBAHA device.
This module serves as the "physical" counterpart to the FBDECT devices. Note: you have to enable the access to Smart Home in the FRITZ!Box frontend for the fritzbox-user, and take care to configure the login in the home network with username AND password.

Define
define <name> FBAHAHTTP <hostname>

<hostnamedevice> is most probably fritz.box. Example:
define fb1 FBAHAHTTP fritz.box

Note: to specify HTTPS for the connection use https://fritz.box as hostname. To explicitly specify the port, postfix the hostname with :port, as in https://fritz.box:443

Set
• password <password>
  This is the only way to set the password
• refreshstate
  The state of all devices is polled every <polltime> seconds (default is 300). This command forces a state-refresh.
• template <templateName>
  Set the the template. Note: reported to work for templates without space characters (Forum #98913)

Get
• templateList
  get the list of templates from the Fritz!Box, and store the in the templateList reading. Needed for the set template command.

Attributes
• async_delay
  additional delay inserted, when switching more than one device, default is 0.2 seconds. Note: even with async_delay 0 there will be a delay, as FHEM avoids sending commands in parallel, to avoid malfunctioning of the Fritz!BOX AHA server).
• disable
• disabledForIntervals
• dummy
• fritzbox-user
• polltime
  measured in seconds, default is 300 i.e. 5 minutes
• fbTimeout
  timeout for getting answer from the Fritz!BOX. Default is 4 (seconds).

FBDECT

This module is used to control AVM FRITZ!DECT devices via FHEM, see also the FBAHA or FBAHAHTTP module for the base.

Define
define <name> FBDECT [<FBAHAname>:]<id> props

Example:
define lamp FBDECT 16 switch,powerMeter

Note:Usually the device is created via autocreate. If you rename the corresponding FBAHA device, take care to modify the FBDECT definitions, as it is not done automatically.


Set Note: not all commands are supported for all devices.
• on/off
  set the device on or off.
• dim <value>
  dim the device (if it is supported), value is between 0 and 100 (in %)
• open/close/stop
  set the blind correspondingly
• desired-temp <value>
  set the desired temp on a Comet DECT (FBAHAHTTP IOdev only). The value 7.5 corresponds to off, and 28.5 to on.
• boost <duration>
  set the boost mode on a Comet/Fritz DECT 301 (FBAHAHTTP IOdev only) for duration in seconds. The value 0 means deactivate previously set boost mode.
• windowopen <duration>
  set the windowopen mode on a Comet/Fritz DECT (FBAHAHTTP IOdev only) for duration in seconds. The value 0 means deactivate previously set windowopen mode.
• set extensions are supported.
• msgInterval <sec>
  Number of seconds between the sensor messages (FBAHA IODev only).
• color <colorname>
  Color name for color bulbs: red, orange, yellow, lawngreen, green, turquoise, cyan, azure, blue, violet, magenta, pink. If the bulb was in "white" mode, it will change to "color" mode.
• colortemperature <temperature>
  Color temperature in Kelvin (> 2000) otherwise micro-reciprocal degrees (mired). If temperature is not given, it will only change from "color" to "white" mode. As the Fritzbox only accepts pre-defined values, it will be set back to the nearest authorized value in Kelvin (run set <devicename> raw getcolordefaults to know the accepted values). If the bulb was in "color" mode, it will change to "white" mode, except if temperature given in mireds leads to no change of temperature in Kelvin.
• sat_index <index>
  Index from 1 to 3 of accepted saturation levels. Sets the bulb to the corresponding saturation for the set color. If the bulb was in "white" mode, it will change to "color" mode.
• hue <huevalue>
  Hue value from 0 to 359. As the Fritzbox only accepts pre-defined values, it will be set back to the nearest authorized value. (run set <devicename> raw getcolordefaults to know the accepted values). The saturation will change to the accepted saturation for the color and sat_index set. If the bulb was in "white" mode, it will change to "color" mode.
• saturation <value>
  Color saturation from 0 to 255. As the Fritzbox only accepts pre-defined values, it will be set back to the nearest authorized value for the set color (run set <devicename> raw getcolordefaults to know the accepted values for each color). If the bulb was in "white" mode, it will change to "color" mode.
• raw ...
  Used for debugging.
  Sends switchcmd=..., further parameters are joined with &.

Get
• devInfo
  report device information (FBAHA IODev only)

Attributes
• IODev
• disable
• disabledForIntervals
• do_not_notify
• ignore
• dummy
• showtime
• model
• readingFnAttributes

Generated events:
• on
• off
• set_on
• set_off
• current: $v A
• voltage: $v V
• power: $v W
• energy: $v Wh
• powerFactor: $v"
• temperature: $v C (measured)
• tempadjust: $v C
• options: uninitialized
• options: powerOnState:[on|off|last],lock:[none,webUi,remoteFb,button]
• control: disabled
• control: on power < $v delay:$d sec do:state [on|off]
• relaytimes: disabled
• relaytimes: HEX

FB_CALLLIST

The FB_CALLLIST module creates a call history list by processing events of a FB_CALLMONITOR definition. It logs all calls and displays them in a historic table.

You need a defined FB_CALLMONITOR instance where you can attach FB_CALLLIST to process the call events.

Depending on your configuration the status will be shown as icons or as text. You need to have the openautomation icon set configured in your corresponding FHEMWEB instance (see FHEMWEB attribute iconPath).

The icons have different colors.


• blue - incoming call (active or finished)
• green - outgoing call (active or finished)
• red - missed incoming call

If you use no icons (see show-icons) the following states will be shown:


• <= ((o)) - outgoing call (ringing) - icon: outgoing.ring
• => ((o)) - incoming call (ringing) - icon: incoming.ring


• <= [=] - outgoing call (currently active) - icon: outgoing.connected
• => [=] - incoming call (currently active) - icon: incoming.connected


• <= X - outgoing unsuccessful call (nobody picked up) - icon: outgoing.missed
• => X - incoming unsuccessful call (missed call) - icon: incoming.missed


• => O_O - incoming finished call recorded on answering machine - icon: incoming.tam


• <= - outgoing finished call - icon: outgoing.done
• => - incoming finished call - icon: incoming.done

The default icon mapping for all states can be changed by the corresponding attribute.

Define
define <name> FB_CALLLIST <FB_CALLMONITOR name>


Set

• clear - clears the list completely
• removeItem <index> - removes a specific item from the list (row number)

Get

No get commands implemented.

Attributes


• do_not_notify
• readingFnAttributes


• answMachine-is-missed-call 0,1
If activated, a incoming call, which is answered by an answering machine, will be treated as a missed call. This is only relevant if list-type is set to "missed-call" or create-readings is set.

Possible values: 0 => disabled, 1 => enabled (successful answering machine calls will be treated as "missed call").
Default Value is 0 (disabled)


• connection-mapping <hash>
Defines a custom mapping of connection names to custom values. The mapping is performed in a hash table.

e.g.

attr <name> connection-mapping {'DECT_1' => 'Mobile Kitchen', 'FON1' => 'Fax'}

The mapped name will be displayed in the table instead of the original value from FB_CALLMONITOR.

Default Value: empty (no mapping is performed)


• create-readings 0,1
If enabled, for all visible calls in the list, readings and events will be created. It is recommended to set the attribute event-on-change-reading to .* (all readings), to reduce the amount of generated readings for certain call events.

Possible values: 0 => no readings will be created, 1 => readings and events will be created.
Default Value is 0 (no readings will be created)


• contactImageDirectory <directory>
If set, FB_CALLLIST will use this directory to display a contact image for each call. This image will be shown in the column "image", which needs to be explicit configured via attribute visible-columns. If this directory contains a file with the external number as filename (e.g. "0123456789.jpg" or "0345678901.gif"), it will be displayed in the call list.

Supported formats are: JPEG, GIF, PNG, BMP

By default, no directory is set and therefore no images will be displayed


• contactDefaultImage <filename>
If contact images are configured (via attribute contactImageDirectory) and there is no image file available or the external number is unknown, FB_CALLLIST will use this file (e.g. unkown.jpg) as contact image in case there is no image for the external number available or the external number is unknown. The file must be located in the directory configured via attribute contactImageDirectory.

If not configured, no images will be shown for such calls.


• disable 0,1,2,3
Optional attribute to disable the call list. When disabled, call events will not be processed and the list wouldn't be updated accordingly. Depending on the value, the call list can

Possible values:
• 0 => FB_CALLLIST is activated, proccess events and updates the table
• 1 => Events will NOT be processed. table will NOT be updated (stays as it is)
• 2 => Events will NOT be processed. table just shows "disabled" (no items)
• 3 => Events will NOT be processed. table will NOT be shown entirely

Default Value is 0 (activated)


• disabledForIntervals HH:MM-HH:MM HH:MM-HH:MM...
Optional attribute to disable event processing and updates of the call list during a specific time interval. The attribute contains a space separated list of HH:MM tupels. If the current time is between any of these time specifications, the callist will be disabled and no longer updated. Instead of HH:MM you can also specify HH or HH:MM:SS.

To specify an interval spawning midnight, you have to specify two intervals, e.g.:

23:00-24:00 00:00-01:00

Default Value is empty (no intervals defined, calllist is always active)


• processEventsWhileDisabled 0,1
If enabled, events where still be processed, even FB_CALLLIST is disabled (see disable and disabledForIntervals). So after re-enabling FB_CALLLIST, all calls during disabled state are completely available.

Possible values: 0 => no event processing when FB_CALLIST is disabled, 1 => events are still processed, even FB_CALLLIST is disabled
Default Value is 0 (no event processing when disabled)


• expire-calls-after <timeframe>
Optional attribute to automatically delete finished calls which are older than a given timeframe. If a finished call is older than this timeframe, it will be deleted from the list.

A timeframe can be specified as follows:
• as minutes: 1 minute or 30 minutes
• as hours: 1 hour or 12 hours
• as days: 1 day or 5 days
• as months: 1 month or 6 months (in this case one month is equal to 30 days)
• as years: 1 year or 2 years (in this case one year is equal to 365 days)

IMPORTANT: In this case, the ending time of each call is checked, not the beginning time.

If no unit is given, the given number ist interpreted as seconds. Float values can also be used (e.g. 0.5 day). The value 0 means no expiry of calls, so no calls will be deleted because of expiry.

Default Value is 0 (no calls will be deleted because of expiry)


• external-mapping <hash>
Defines a custom mapping of external connection values (reading: external_connection) to custom values. The mapping is performed in a hash table.

e.g.

attr <name> external-mapping {'ISDN' => 'Fixed Network', 'SIP0' => 'Operator A', 'SIP1' => 'Operator B'}


• icon-mapping <hash>
Defines a custom mapping of call states to custom icons. The mapping is performed in a hash table.

e.g.

attr <name> icon-mapping {'incoming.connected' => 'phone_ring_in@yellow', 'outgoing.missed' => 'phone_missed_out@red'}

The mapped name will be displayed in the table instead of the original value from FB_CALLMONITOR. If you use SVG-based icons, you can set the desired color as name or HTML color code via an optional "@color".

Possible values and their default icon are:


• incoming.ring => phone_ring@blue
• outgoing.ring => phone_ring@green
• incoming.connected => phone_ring_in@blue
• outgoing.connected => phone_ring_in@green
• incoming.missed => phone_missed_in@red
• outgoing.missed => phone_missed_out@green
• incoming.done => phone_call_end_in@blue
• outgoing.done => phone_call_end_out@green
• incoming.tam => phone_answering@blue


Default Value: empty (no mapping is performed)


• internal-number-filter <hash>
This attribute accepts a list of comma seperated internal numbers for filtering incoming or outgoing calls by a specific list of internal numbers or a hash for filtering and mapping numbers to text.

e.g.

attr <name> internal-number-filter 304050,304060

attr <name> internal-number-filter {'304050' => 'business', '304060' => 'private'}

Important: Depending on your provider, the internal number can contain a location area code. The internal-number-filter must contain the same number as it is displayed in the call list. This can be with or without location area code depending on your provider.

If this attribute is set, only the configured internal numbers will be shown in the list. All calls which are not taken via the configured internal numbers, were not be shown in the call list.

Default Value: empty (all internal numbers should be used, no exclusions and no mapping is performed)


• language en,de
Defines the language of the table header, some keywords and the timestamp format. You need to have the selected locale installed and available in your operating system.

Possible values: en => English , de => German
Default Value is en (English)


• list-type all,incoming,outgoing,missed-calls,completed,active
Defines what type of calls should be displayed in the list.

Default Value is "all"


• list-order descending,ascending
Defines whether the newest call should be on top of the list (descending) or on the bottom of the list (ascending).

Default Value is descending (first call at top of the list)


• no-heading 0,1
If activated the headline with a link to the detail page of the current definition will be hidden.

Possible values: 0 => the heading line will be shown , 1 => the heading line will not be shown
Default Value is 0 (the heading line will be shown)


• no-table-header 0,1
If activated the table header containing the name of each column for the current definition will be hidden.

Possible values: 0 => the table header will be shown , 1 => the table header will not be shown
Default Value is 0 (the table header will be shown)


• number-cmd <command>
Can be set, to execute a specific FHEM command, when clicking on a number in the list. The value can be any valid FHEM command or Perl code (in curly brackets: { ... } ). The placeholder $NUMBER will be replaced with the current external number of each row.

This can be used for example to initiate a call to this number. e.g.:


• set FRITZBOX call $NUMBER
• {dialNumber("$NUMBER")}

If not set, no link will be shown in the list.


• number-of-calls 1..40
Defines the maximum number of displayed call entries in the list.

Default Value is 5 calls


• show-icons 0,1
Normally the call state is shown with icons (used from the openautomation icon set). You need to have openautomation in your iconpath attribute of your appropriate FHEMWEB definition to use this icons. If you don't want to use icons you can deactivate them with this attribute.

Possible values: 0 => no icons , 1 => use icons
Default Value is 1 (use icons)


• time-format-string <string>
Defines a format string which should be used to format the timestamp values. It contains several placeholders for different elements of a date/time. The possible values are standard POSIX strftime() values. Common placeholders are:


• %a - The abbreviated weekday name
• %b - The abbreviated month name
• %S - The second as a decimal number
• %M - The minutes as a decimal number
• %H - The hours as a decimal number
• %d - The day of the month as a decimal number
• %m - The month as a decimal number
• %Y - The year as a decimal number including the century.

There are further placeholders available. Please consult the manpage of strftime() or the documentation of your perl interpreter to find out more.

Default value is "%a, %d %b %Y %H:%M:%S" ( = "Sun, 07 Jun 2015 12:50:09")


• visible-columns row,state,timestamp,image,name,number,internal,external,connection,duration
Defines the visible columns, as well as the order in which these columns are displayed in the call list (from left to right). Not all columns must be displayed, you can select only a subset of columns which will be displayed.

The possible values represents the corresponding column. The column "row" represents the row number within the current list.

Possible values: a combination of row,state,timestamp,image,name,number,internal,external,connection,duration
Default Value is "row,state,timestamp,name,number,internal,external,connection,duration" (show all columns, except "image" as it needs to be configured first)



Generated Events:


This module generates only readings if the attribute create-readings is activated. The number and names of the readings depends on the selected columns (see attribute visible-columns) and the configured number of calls (see attribute number-of-calls).

In general the following readings are always created if attribute create-readings is activated:


• count-all - The overall number of displayed calls.
• count-incoming - The number of all displayed incoming calls
• count-outgoing - The number of all displayed outgoing calls
• count-active - The number of running (not yet completed) calls
• count-completed - The number of already completed calls.
• count-missed-calls - The number of missed calls (incoming).

FHEM2FHEM

FHEM2FHEM is a helper module to connect separate FHEM installations.

Define
define <name> FHEM2FHEM <host>[:<portnr>][:SSL] [LOG:regexp|RAW:devicename] {portpassword}

Connect to the remote FHEM on <host>. <portnr> is a telnet port on the remote FHEM, defaults to 7072. The optional :SSL suffix is needed, if the remote FHEM configured SSL for this telnet port. In this case the IO::Socket::SSL perl module must be installed for the local host too.

Notes:
• if the remote FHEM is on a separate host, the telnet port on the remote FHEM must be specified with the global option.
• as of FHEM 5.9 the telnet instance is not configured in default fhem.cfg, so it has to be defined, e.g. as
  define telnetPort telnet 7072 global

The next parameter specifies the connection type:
• LOG
  Using this type you will receive all events generated by the remote FHEM, just like when using the inform on command, and you can use these events just like any local event for FileLog or notify. The regexp will prefilter the events distributed locally, for the syntax see the notify definition.
  Drawbacks: the remote devices wont be created locally, so list wont show them and it is not possible to manipulate them from the local FHEM. It is possible to create a device with the same name on both FHEM instances, but if both of them receive the same event (e.g. because both of them have a CUL attached), then all associated FileLogs/notifys will be triggered twice.
  If the remote device is created with the same name locally (e.g. as dummy), then the local readings are also updated.
• RAW
  By using this type the local FHEM will receive raw events from the remote FHEM device devicename, just like if it would be attached to the local FHEM. Drawback: only devices using the Dispatch function (CUL, FHZ, CM11, SISPM, RFXCOM, TCM, TRX, TUL) generate raw messages, and you must create a FHEM2FHEM instance for each remote device.
  devicename must exist on the local FHEM server too with the same name and same type as the remote device, but with the device-node "none", so it is only a dummy device. All necessary attributes (e.g. rfmode if the remote CUL is in HomeMatic mode) must also be set for the local device. Do not reuse a real local device, else duplicate filtering (see dupTimeout) won't work correctly.
The last parameter specifies an optional portpassword, if the remote server activated portpassword.
Examples:
define ds1 FHEM2FHEM 192.168.178.22:7072 LOG:.*

define RpiCUL CUL none 0000
define ds2 FHEM2FHEM 192.168.178.22:7072 RAW:RpiCUL
and on the RPi (192.168.178.22):
rename CUL_0 RpiCUL


Set
• reopen
  Reopens the connection to the device and reinitializes it.


• cmd <FHEM-command>
  issues the FHEM-command on the remote machine. Note: a possible answer can be seen if it is issued in a telnet session or in the FHEMWEB "command execution window", but not when issued in the other FHEMWEB input lines.


Get
N/A

Attributes
• dummy
• disable
• disabledForIntervals
• eventOnly
  if set, generate only events, do not set corresponding readings. This is a compatibility feature, available only for LOG-Mode.
• addStateEvent
  if set, state events are transmitted correctly. Notes: this is relevant only with LOG mode, setting it will generate an additional "reappeared" Log entry, and the remote FHEM must support inform onWithState (i.e. must be up to date).
• excludeEvents <regexp> do not publish events matching <regexp>. Note: ^ and $ are automatically added to the regexp, like in notify, FileLog, etc.
• keepaliveInterval <sec>
  issues an empty command regularly in order to detect a stale TCP connection faster than the OS.
• loopThreshold
  helps avoiding endless loops. If set, the last update of a given reading must be older than the current value in seconds. Take care if event-on-* attributes are also set.
• setState if set to 1, and there is a local device with the same name, then remote set commands will be executed for the local device.
• reportConnected if set (to 1), a "global CONNECTED <name>" Event will be generated after connection established on the telnet server. This might be used to resend changed values.

fhemApp

Defines a helper device for FHEMapp UI.
Provides configuration storage, special functionalities for a FHEMapp UI.

This requires at least one installation of FHEMApp to be delivered by a Web-Server. If the installation should run on the same computer as FHEM and FHEM should deliver the FHEMApp-UI (recommended) then The installation can be performed by a FHEMAPP device itself locally.

For more information and detailed instructions, see FHEMApp on github: https://github.com/jemu75/fhemApp

Define
define <name> FHEMAPP [pathToLocalFolder|none]

pathToLocalFolder = A local folder that could be accessed by FHEM and from which FHEMapp UI is provided via FHEMWEB. Usually this is a folder below ./www (this will automatcally resolved)

If no local installations should be managed by this device you could specify none instead of a folder path.

Examples:
define fa FHEMAPP fhemapp

define fa2 FHEMAPP none



Important: If the device is deleted with delete command, it also deletes the config file!
The fhemapp application files (in ./www) are currently not deleted if the device is deleted.

Set
• checkVersions
  Executes the version check, which is usually performed cyclic, immediately. This has no effect on the actual version check cycle itself.
  This command is only available for FHEMAPP instances that are managing a local FHEMApp installation
• update
  Updates the locally managed fhemapp installation to the latest release or pre-release, depending on the updatePath (see attribute).
  This command is only available for FHEMAPP instances that are managing a local FHEMApp installation
• rereadCfg
  Reloads the config from the fhemapp config file. Could be used in case of changes to the file were made manually.
• getConfig
  Returns the current configuration JSON in the active window withoud surrounding dialog.
• purge [force]
  Deletes the locally managed fhemapp inatallation. To really delete it the parameter force must be specified as '1'. Could be easily reinstalled with set update command.
  
  Example:
  set fa purge 1
  
  
  
  

Get
• rawconfig
  returns the currently saved config for FHEMapp in json format. This is usually only used by FHEMapp itself, but can be useful for debugging purposes.
• version
  Returns the current version number of a local FHEMapp installation. If no local installation is specified (s. define), there will be no result (undef).

Attributes
• disable
  this will only disable the cyclic version checking!
• interval
  Overrides the default interval (3600 seconds) for cyclic version checking. Max value is 1 day (86400 seconds) and minimum value is 1 minute (60) seconds.
  See also INTERNAL INTERVAL
• sourceUrl
  Overrides the default URL for the source repository, used for version checking, update and installation. This is usally a github repository
  See also INTERNAL SOURCE_URL
• updatePath
  Defines the update path for fhemapp updates and installations. Can be set to "beta" to retreive pre-releases. Default is stable (attribute is unset).
• exposeConfigFile
  By setting this attribute, the config file is made availabel in the "Edit Files" list in FHEM. This is could be usefull for backup purposes.
  !!! Direct editing the config file is explicitly NOT RECOMMENDED!!!
• linkPath
  FHEMAPP instances, that are managing local FHEMApp installations usually have a INTERNAL containing a link to the UI. For instances that are defined with "none", the required path information is missing and could therefore be set here the same way as in DEF for "full" instances.
  This is only relevant for instances without local FHEMApp-Installation.
• requestTimeout
  Timeout in seconds used for http requests collecting vesion and update informations.
  Default value (attribute is not set) is 60s
  Minimum allowed value is 5s.

FHEMWEB

FHEMWEB is the builtin web-frontend, it also implements a simple web server (optionally with Basic-Auth and HTTPS).

Define
define <name> FHEMWEB <tcp-portnr> [global|IP]

Enable the webfrontend on port <tcp-portnr>. If global is specified, then requests from all interfaces (not only localhost / 127.0.0.1) are serviced. If IP is specified, then FHEMWEB will only listen on this IP.
To enable listening on IPV6 see the comments here.


Set
• rereadicons
  reads the names of the icons from the icon path. Use after adding or deleting icons.
• clearSvgCache
  delete all files found in the www/SVGcache directory, which is used to cache SVG data, if the SVGcache attribute is set.
• reopen
  reopen the server port. This is an alternative to restart FHEM when the SSL certificate is replaced.

Get
• icon <logical icon>
  returns the absolute path to the logical icon. Example:
  get myFHEMWEB icon FS20.on
/data/Homeautomation/fhem/FHEM/FS20.on.png
• pathlist
  return FHEMWEB specific directories, where files for given types are located



Attributes
• addHtmlTitle
  If set to 0, do not add a title Attribute to the set/get/attr detail widgets. This might be necessary for some screenreaders. Default is 1.


• alias_<RoomName>
  If you define a userattr alias_<RoomName> and set this attribute for a device assgined to <RoomName>, then this value will be used when displaying <RoomName>.
  Note: you can use the userattr alias_.* to allow all rooms, but in this case the attribute dropdown in the device detail view won't work for the alias_.* attributes.


• allowfrom
  Regexp of allowed ip-addresses or hostnames. If set, only connections from these addresses are allowed.
  NOTE: if this attribute is not defined and there is no valid allowed device defined for the telnet/FHEMWEB instance and the client tries to connect from a non-local net, then the connection is refused. Following is considered a local net:
  
  IPV4: 127/8, 10/8, 192.168/16, 172.16/10, 169.254/16
  IPV6: ::1, fe80/10
  


• allowedHttpMethods
  FHEMWEB implements the GET, POST and OPTIONS HTTP methods. Some external devices require the HEAD method, which is not implemented correctly in FHEMWEB, as FHEMWEB always returns a body, which, according to the spec, is wrong. As in some cases this not a problem, enabling GET may work. To do this, set this attribute to GET|POST|HEAD, default ist GET|POST. OPTIONS is always enabled.


• closeConn
  If set, a TCP Connection will only serve one HTTP request. Seems to solve problems on iOS9 for WebApp startup.


• column
  Allows to display more than one column per room overview, by specifying the groups for the columns. Example:
  
  attr WEB column LivingRoom:FS20,notify|FHZ,notify DiningRoom:FS20|FHZ
  In this example in the LivingRoom the FS20 and the notify group is in the first column, the FHZ and the notify in the second.
  Notes: some elements like SVG plots and readingsGroup can only be part of a column if they are part of a group. This attribute can be used to sort the groups in a room, just specify the groups in one column. Space in the room and group name has to be written as %20 for this attribute. Both the room name and the groups are regular expressions.


• confirmDelete
  confirm delete actions with a dialog. Default is 1, set it to 0 to disable the feature.


• confirmJSError
  JavaScript errors are reported in a dialog as default. Set this attribute to 0 to disable the reporting.


• CORS
  If set to 1, FHEMWEB will supply a "Cross origin resource sharing" header, see the wikipedia for details.


• csrfToken
  If set, FHEMWEB requires the value of this attribute as fwcsrf Parameter for each command. It is used as countermeasure for Cross Site Resource Forgery attacks. If the value is random, then a random number will be generated on each FHEMWEB start. If it is set to the literal string none, no token is expected. Default is random for featurelevel 5.8 and greater, and none for featurelevel below 5.8


• csrfTokenHTTPHeader
  If set (default), FHEMWEB sends the token with the X-FHEM-csrfToken HTTP header, which is used by some clients. Set it to 0 to switch it off, as a measurre against shodan.io like FHEM-detection.


• CssFiles
  Space separated list of .css files to be included. The filenames are relative to the www directory. Example:
  attr WEB CssFiles pgm2/mystyle.css


• Css
  CSS included in the header after the CssFiles section.


• cmdIcon
  Space separated list of cmd:iconName pairs. If set, the webCmd text is replaced with the icon. An easy method to set this value is to use "Extend devStateIcon" in the detail-view, and copy its value.
  Example:
  attr lamp cmdIcon on:control_centr_arrow_up off:control_centr_arrow_down


• defaultRoom
  show the specified room if no room selected, e.g. on execution of some commands. If set hides the motd. Example:
  attr WEB defaultRoom Zentrale


• detailLinks
  number of links to show on the bottom of the device detail page. The rest of the commands is shown in a dropdown menu. Default is 2.
  This can optionally followed by a comma separated list of ids to order or filter the desired links, the ids being one of devSpecHelp, forumCopy, rawDef, style iconFor, style showDSI, delete. Example:
  attr WEB detailLinks 2,devSpecHelp,forumCopy


• devStateIcon
  First form:
  
  Space separated list of regexp:icon-name:cmd triples, icon-name and cmd may be empty.
  If the STATE of the device matches regexp, then icon-name will be displayed as the status icon in the room, and (if specified) clicking on the icon executes cmd. If FHEM cannot find icon-name, then the STATE text will be displayed. Example:
  
  attr lamp devStateIcon on:closed off:open
  attr lamp devStateIcon on::A0 off::AI
  attr lamp devStateIcon .*:noIcon
  
  Note: if the image is referencing an SVG icon, then you can use the @fill:stroke suffix to color the image, where fill replaces the fill color in the SVG (if it is specified as #000000) and the optional stroke the stroke color (if it is specified as #000000). E.g.:
  
  attr Fax devStateIcon on:control_building_empty@red off:control_building_filled:278727
  If the cmd is noFhemwebLink, then no HTML-link will be generated, i.e. nothing will happen when clicking on the icon or text.
  Note: if you need stroke coloring in the devStateIcon, you have to use the alternative @fill@stroke syntax.
  Second form:
  
  Perl code enclosed in {}. If the code returns undef, then the default icon is used, if it retuns a string enclosed in <>, then it is interpreted as an html string. Else the string is interpreted as a devStateIcon of the first fom, see above. Example:
  {'<div style="width:32px;height:32px;background-color:green"></div>'}
Note: The above is valid for each line of STATE. If STATE (through stateFormat) is multilined, multiple icons (one per line) will be created.


• devStateStyle
  Specify an HTML style for the given device, e.g.:
  
  attr sensor devStateStyle style="text-align:left;;font-weight:bold;;"
  


• deviceOverview
  Configures if the device line from the room view (device icon, state icon and webCmds/cmdIcons) should also be shown in the device detail view. Can be set to always, onClick, iconOnly or never. Default is always.


• editConfig
  If this FHEMWEB attribute is set to 1, then you will be able to edit the FHEM configuration file (fhem.cfg) in the "Edit files" section. After saving this file a rereadcfg is executed automatically, which has a lot of side effects.
  


• editFileList
  Specify the list of Files shown in "Edit Files" section. It is a newline separated list of triples, the first is the Title, the next is the directory to search for as a perl expression(!), the third the regular expression. Default is:
  Own modules and helper files:$MW_dir:^(.*sh|[0-9][0-9].*Util.*pm|.*cfg|.*holiday|myUtilsTemplate.pm|.*layout)$
Gplot files:$FW_gplotdir:^.*gplot$
Styles:$FW_cssdir:^.*(css|svg)$

  NOTE: The directory spec is not flexible: all .js/.css/_defs.svg files come from www/pgm2 ($FW_cssdir), .gplot files from $FW_gplotdir (www/gplot), everything else from $MW_dir (FHEM).


• endPlotNow
  Set the default for all SVGs: If this FHEMWEB attribute is set to 1, then day and hour plots will end at current time. Else the whole day, the 6 hour period starting at 0, 6, 12 or 18 hour or the whole hour will be shown. This attribute is not used if the SVG has the attribute startDate defined.


• endPlotNowByHour
  Set the default for all SVGs: If endPlotNow and this attribute are set to 1 and the zoom-level is "day", then the displayed hour ticks will be rounded to the complete hour.


• endPlotToday
  set the default for alls SVGs: If this FHEMWEB attribute is set to 1, then week and month plots will end today. Else the current week or the current month will be shown.


• fwcompress
  Enable compressing the HTML data (default is 1, i.e. yes, use 0 to switch it off).


• extraRooms
  Space or newline separated list of dynamic rooms to add to the room list.
  Example:
  attr WEB extraRooms name=open:devspec=contact=open.* name=closed:devspec=contact=closed.*


• forbiddenroom
  just like hiddenroom (see below), but accessing the room or the detailed view via direct URL is prohibited.


• hiddengroup
  Comma separated list of groups to "hide", i.e. not to show in any room of this FHEMWEB instance.
  Example: attr WEBtablet hiddengroup FileLog,dummy,at,notify


• hiddengroupRegexp
  One regexp for the same purpose as hiddengroup.


• hiddenroom
  Comma separated list of rooms to "hide", i.e. not to show. Special values are input, detail and save, in which case the input areas, link to the detailed views or save button are hidden (although each aspect still can be addressed through URL manipulation).
  The list can also contain values from the additional "Howto/Wiki/FAQ" block, and from the bottom of the detail page: devSpecHelp, forumCopy, rawDef, style iconFor, style showDSI, delete.


• hiddenroomRegexp
  One regexp for the same purpose as hiddenroom. Example:
  attr WEB hiddenroomRegexp .*config
  Note: the special values input, detail and save cannot be specified with hiddenroomRegexp.


• httpHeader
  One or more HTTP header lines to be sent out with each answer. Example:
  attr WEB httpHeader X-Clacks-Overhead: GNU Terry Pratchett


• htmlInEventMonitor
  if set to 1, text enclosed in <html>...</html> will not be escaped in the event monitor.


• HTTPS
  Enable HTTPS connections. This feature requires the perl module IO::Socket::SSL, to be installed with cpan -i IO::Socket::SSL or apt-get install libio-socket-ssl-perl; OSX and the FritzBox-7390 already have this module.
  A local certificate has to be generated into a directory called certs, this directory must be in the modpath directory, at the same level as the FHEM directory.
  mkdir certs
  cd certs
  openssl req -new -x509 -nodes -out server-cert.pem -days 3650 -keyout server-key.pem
  These commands are automatically executed if there is no certificate. Because of this automatic execution, the attribute sslCertPrefix should be set, if necessary, before this attribute.
  
• icon
  Set the icon for a device in the room overview. There is an icon-chooser in FHEMWEB to ease this task. Setting icons for the room itself is indirect: there must exist an icon with the name ico<ROOMNAME>.png in the iconPath.


• iconPath
  colon separated list of directories where the icons are read from. The directories start in the fhem/www/images directory. The default is $styleSheetPrefix:fhemSVG:openautomation:default
  Set it to fhemSVG:openautomation to get only SVG images.


• JavaScripts
  Space separated list of JavaScript files to be included. The filenames are relative to the www directory. For each file an additional user-settable FHEMWEB attribute will be created, to pass parameters to the script. The name of this additional attribute gets the Param suffix, directory and the fhem_ prefix will be deleted. Example:
  attr WEB JavaScripts codemirror/fhem_codemirror.js
attr WEB codemirrorParam { "theme":"blackboard", "lineNumbers":true }
  -fhemweb.js and/or -f18.js will prevent the loading of the corresponding file, this, in combination with the addition of an old version of the file may be a solution for old tablets with an outdated browser.
  attr WEB_iOS6 JavaScripts -fhemweb.js -f18.js pgm2/iOS6_fhemweb.js pgm2/iOS6_f18.js


• logDevice fileLogName
  Name of the FileLog instance, which is used to log each FHEMWEB access. To avoid writing wrong lines to this file, the FileLog regexp should be set to <WebName>:Log


• logFormat ...
  Default is the Apache common Format (%h %l %u %t "%r" %>s %b). Currently only these "short" place holders are replaced. Additionally, each HTTP Header X can be accessed via %{X}i.


• jsLog [1|0]
  if set, and longpoll is websocket, send the browser console log messages to the FHEM log. Useful for debugging tablet/phone problems.


• longpoll [0|1|websocket]
  If activated, the browser is notifed when device states, readings or attributes are changed, a reload of the page is not necessary. Default is 1 (on), use 0 to deactivate it.
  If websocket is specified, then this API is used to notify the browser, else HTTP longpoll. Note: some older browser do not implement websocket.


• longpollSVG
  Reloads an SVG weblink, if an event should modify its content. Since an exact determination of the affected events is too complicated, we need some help from the definition in the .gplot file: the filter used there (second parameter if the source is FileLog) must either contain only the deviceName or have the form deviceName.event or deviceName.*. This is always the case when using the Plot editor. The SVG will be reloaded for any event triggered by this deviceName. Default is off.
  Note: this feature needs the plotEmbed attribute set to 1.


• mainInputLength
  length of the maininput text widget in characters (decimal number).


• menuEntries
  Comma separated list of name,html-link pairs to display in the left-side list. Example:
  attr WEB menuEntries fhem.de,http://fhem.de,culfw.de,http://culfw.de
  attr WEB menuEntries AlarmOn,http://fhemhost:8083/fhem?cmd=set%20alarm%20on
  


• nameDisplay
  The argument is perl code, which is executed for each single device in the room to determine the name displayed. $DEVICE is the name of the current device, and $ALIAS is the value of the alias attribute or the name of the device, if no alias is set. E.g. you can add a a global userattr named alias_hu for the Hungarian translation, and specify nameDisplay for the hungarian FHEMWEB instance as
  AttrVal($DEVICE, "alias_hu", $ALIAS)


• nrAxis
  the number of axis for which space should be reserved on the left and right sides of a plot and optionaly how many axes should realy be used on each side, separated by comma: left,right[,useLeft,useRight]. You can set individual numbers by setting the nrAxis of the SVG. Default is 1,1.


• ploteditor
  Configures if the Plot editor should be shown in the SVG detail view. Can be set to always, onClick or never. Default is always.


• plotEmbed
  If set to 1, SVG plots will be rendered as part of <embed> tags, as in the past this was the only way to display SVG. Setting plotEmbed to 0 will render SVG in-place.
  Setting plotEmbed to 2 will load the SVG via JavaScript, in order to enable parallelization without the embed tag. Default is 2 for multi-CPU hosts on Linux, and 0 everywhere else.


• plotfork
  If set to a nonzero value, run part of the processing (e.g. SVG plot generation or RSS feeds) in parallel processes, default is 0. Note: do not use it on systems with small memory footprint.


• plotmode
  Specifies how to generate the plots:
  • SVG
    The plots are created with the SVG module. This is the default.
  • gnuplot-scroll
    The plots are created with the gnuplot program. The gnuplot output terminal PNG is assumed. Scrolling to historical values is also possible, just like with SVG.
  • gnuplot-scroll-svg
    Like gnuplot-scroll, but the output terminal SVG is assumed.


• plotsize
  the default size of the plot, in pixels, separated by comma: width,height. You can set individual sizes by setting the plotsize of the SVG. Default is 800,160 for desktop, and 480,160 for smallscreen.


• plotWeekStartDay
  Start the week-zoom of the SVG plots with this day. 0 is Sunday, 1 is Monday, etc.
  


• redirectCmds
  Clear the browser URL window after issuing the command by redirecting the browser, as a reload for the same site might have unintended side-effects. Default is 1 (enabled). Disable it by setting this attribute to 0 if you want to study the command syntax, in order to communicate with FHEMWEB.


• redirectTo
  If set, and FHEMWEB cannot handle a request, redirect the client to $FW_ME/$redirectTo$arg. If not set, redirect to $FW_ME. If set to eventFor:, and $arg matches the regexp, then an event for the FHEMWEB instance with $arg will be generated.


• refresh
  If set, a http-equiv="refresh" entry will be genererated with the given argument (i.e. the browser will reload the page after the given seconds).


• rescueDialog
  If set, show a Rescue link in the menu. The goal is to be able to get help from someone with more knowlege (rescuer), who is then able to remote control this installation.
  After opening the dialog, a key is shown, which is to be sent to the rescuer. After the rescuer installed the key (see below), the connection can be established, by entering the adress of the rescuers server.
  
  TODO for the rescuer:
  • Forward a public IP/PORT combination to your SSH server.
  • create a fhemrescue user on this server, and store the key from the client:
    
    useradd -d /tmp -s /bin/false fhemrescue
echo "KEY_FROM_THE_CLIENT" > /etc/sshd/fhemrescue.auth
chown fhemrescue:fhemrescue /etc/sshd/fhemrescue.auth
chmod 600 /etc/sshd/fhemrescue.auth
  • Append to /etc/ssh/sshd_config:
    
    Match User fhemrescue
    
    AllowTcpForwarding remote
    PermitTTY no
    GatewayPorts yes
    ForceCommand /bin/false
    AuthorizedKeysFile /etc/ssh/fhemrescue.auth
    
  • Restart sshd, e.g. with systemctl restart sshd
  • Tell the client your public IP/PORT.
  • After the client started the connection in the rescue dialog, you can access the clients FHEM via your host, port 18083.


• reverseLogs
  Display the lines from the logfile in a reversed order, newest on the top, so that you dont have to scroll down to look at the latest entries. Note: enabling this attribute will prevent FHEMWEB from streaming logfiles, resulting in a considerably increased memory consumption (about 6 times the size of the file on the disk).


• roomIcons
  Space separated list of room:icon pairs, to override the default behaviour of showing an icon, if there is one with the name of "icoRoomName". This is the correct way to remove the icon for the room Everything, or to set one for rooms with / in the name (e.g. Anlagen/EDV). The first part is treated as regexp, so space is represented by a dot. Example:
  attr WEB roomIcons Anlagen.EDV:icoEverything


• smallscreenCommands
  If set to 1, commands, slider and dropdown menues will appear in smallscreen landscape mode.


• sortby
  Take the value of this attribute when sorting the devices in the room overview instead of the alias, or if that is missing the devicename itself. If the sortby value is enclosed in {} than it is evaluated as a perl expression. $NAME is set to the device name.


• showUsedFiles
  In the Edit files section, show only the used files. Note: currently this is only working for the "Gplot files" section.


• sortRooms
  Space separated list of rooms to override the default sort order of the room links. As the rooms in this attribute are actually regexps, space in the roomname has to be specified as dot (.). Example:
  attr WEB sortRooms DG OG EG Keller


• sslVersion
  See the global attribute sslVersion.


• sslCertPrefix
  Set the prefix for the SSL certificate, default is certs/server-, see also the HTTPS attribute.


• styleData
  data-storage used by dynamic styles like f18


• stylesheetPrefix
  prefix for the files style.css, svg_style.css and svg_defs.svg. If the file with the prefix is missing, the default file (without prefix) will be used. These files have to be placed into the FHEM directory, and can be selected directly from the "Select style" FHEMWEB menu entry. Example:
  attr WEB stylesheetPrefix dark
  
  Referenced files:
  
  darksvg_defs.svg
  darksvg_style.css
  darkstyle.css
  
  
  
  Note:if the argument contains the string smallscreen or touchpad, then FHEMWEB will optimize the layout/access for small screen size (i.e. smartphones) or touchpad devices (i.e. tablets)
  The default configuration installs 3 FHEMWEB instances: port 8083 for desktop browsers, port 8084 for smallscreen, and 8085 for touchpad.
  If touchpad or smallscreen is specified, then WebApp support is activated: After viewing the site on the iPhone or iPad in Safari, you can add a link to the home-screen to get full-screen support. Links are rendered differently in this mode to avoid switching back to the "normal" browser.


• SVGcache
  if set, cache plots which won't change any more (the end-date is prior to the current timestamp). The files are written to the www/SVGcache directory. Default is off.
  See also the clearSvgCache command for clearing the cache.


• title
  Sets the title of the page. If enclosed in {} the content is evaluated.


• viewport
  Sets the "viewport" attribute in the HTML header. This can for example be used to force the width of the page or disable zooming.
  Example: attr WEB viewport width=device-width,initial-scale=1,maximum-scale=1,user-scalable=no


• webCmd
  Colon separated list of commands to be shown in the room overview for a certain device. Has no effect on smallscreen devices, see the devStateIcon command for an alternative.
  Example:
  attr lamp webCmd on:off:on-for-timer 10
  
  
  The first specified command is looked up in the "set device ?" list (see the setList attribute for dummy devices). If there it contains some known modifiers (colon, followed by a comma separated list), then a different widget will be displayed. See also the widgetOverride attribute below. Examples:
  define d1 dummy
  attr d1 webCmd state
  attr d1 readingList state
  attr d1 setList state:on,off
  
  define d2 dummy
  attr d2 webCmd state
  attr d2 readingList state
  attr d2 setList state:slider,0,1,10
  
  define d3 dummy
  attr d3 webCmd state
  attr d3 readingList state
  attr d3 setList state:time
  
  If the command is state, then the value will be used as a command.
  Note: this is an attribute for the displayed device, not for the FHEMWEB instance.


• webCmdLabel
  Colon separated list of labels, used to prefix each webCmd. The number of labels must exactly match the number of webCmds. To implement multiple rows, insert a return character after the text and before the colon.


• webname
  Path after the http://hostname:port/ specification. Defaults to fhem, i.e the default http address is http://localhost:8083/fhem


• widgetOverride
  Space separated list of name:modifier pairs, to override the widget for a set/get/attribute specified by the module author. To specify the widget for a specific type, use the name@type:modifier syntax, where type is one of set, get and attr. Following is the list of known modifiers:

  
  To the icon.* widgets listed below applies:
  <color> is specified by a color name or a color number without leading # e.g. FFA500 or orange. Depending on the context @ has to be escaped \@.
  <icon> is the icon name.
  [class<classname>@] as prefix in front of the second parameter, assigns a css-class to the icons.
  Examples for import with raw definition, will be found in FHEMWEB-Widgets

  • iconRadio,[class<classname>@][use4icon@]<select color>,<value>,<icon>[@<color>][,<value>,<icon>[@<color>]]... - displays Icons as radio button and returns value if pushed.
    <value> return or compare value. If a numerical sequence of <value> is specified, the current value will match the next higher <value>. It is allowed to place non numerical <value> in front of or after the sequence but not in between. The numerical sequence has to be ascendind or descending.
    Example: iconRadio,808080,closed,control_arrow_down,10,fts_shutter_10,20,fts_shutter_20,30,fts_shutter_30,open,control_arrow_up
    <select color> the background color of the selected icon or the icon color if the prefix use4icon@ is used.
    The widget contains a CSS-class "iconRadio_widget".
    
  • iconButtons,[class<classname>@][use4icon@]<select color>,<value>,<icon>[@<color>][,<value>,<icon>[@<color>]]... - displays Icons as button bar and returns comma separated values of pushed buttons.
    <value> return value.
    <select color> the background color of the selected icon or the icon color if the prefix use4icon@ is used.
    The widget contains a CSS-class "iconButtons_widget".
    
  • iconLabel[,[class<classname>@]<reference value>,[<icon>][@<color>]][,<reference value>,[<icon>][@<color>]]... - displays states by colorized values, labels and icons, if the current value fits to the reference value. A state is described by a parameter peer. The number of peers is arbitrarily. A peer consists of a <reference value> and an optional display value with an optional color value <reference value> is a number or a regular expression.
    If <icon> is no icon name, the text will be displayed, otherwise the icon. If nothing is specified, the current value will be displayed.
    
  • iconSwitch,[class<classname>@]<reference value>,[<icon>][@<color>][,<reference value>,[<icon>][@<color>]]... - switches cyclic after actuation to the diplayed state and the actual value is set to the reference Value. A state is described by a parameter peer. The number of peers is arbitrarily. A peer consists of a <reference value> and an optional display value with an optional color value [<icon>][@<color>].
    <reference value> is a number or a string.
    If <icon> is no icon name, the text will be displayed, otherwise the icon. If nothing is specified, the reference value will be displayed.
    
  
  
  • :sortable,val1,val2,... - create a new list from the elements of the given list, can add new elements by entering a text, or delete some from the list. This new list can be sorted via drag & drop. The result is a comma separated list.
  • :sortable-strict,val1,val2,... - it behaves like :sortable, without the possibility to enter text.
  • :sortable-given,val1,val2,... - the specified list can be sorted via drag & drop, no elements can be added or deleted.
  • uzsuToggle,state1,state2 - dispay a toggle button with two possible states. the first is the active state.
  • uzsuSelect,val1,val2,... - display a button bar with a button per value from which multiple values can be selected. the result is comma separated.
  • uzsuSelectRadio,val1,val2,... - display a button bar with a button per value from which only one value can be selected.
  • uzsuDropDown,val1,val2,... - display a dropdown with all values.
  • uzsuTimerEntry[,modifier2] - combine uzsuSelect, uzsuDropDown and uzsuToggle into a single line display to select a timer entry. an optional modifier can be given to select the switching value. see examples below. the result is a comma separated list of days followed by a time, an enabled indicator and the switching value all separated by a|. eg: Mo,Di,Sa,So|00:00|enabled|19.5
  • uzsu[,modifier2] - combine multiple uzsuTimerEntry widets to allow the setting of multiple switching times an optional modifier can be given to select the switching value. see examples below. the result is a space separeted list of uzsuTimerEntry results. Examples:
    attr myToggle widgetOverride state:uzsuToggle,123,xyz
    attr mySelect widgetOverride state:uzsuSelect,abc,123,456,xyz
    attr myTemp widgetOverride state:uzsuDropDown,18,18.5,19,19.5,20,20.5,21,21.5,22,22.5,23
    attr myTimerEntry widgetOverride state:uzsuTimerEntry
    attr myTimer widgetOverride state:uzsu
    
    the following gives some examples of for the modifier2 parameter of uzsuTimerEntry and uzsu to combine the setting of a timer with another widget to select the switching value :

    ... widgetOverride state:uzsu,slider,0,5,100                                         -> a slider
    ... widgetOverride state:uzsu,uzsuToggle,off,on                                      -> a on/off button
    ... widgetOverride state:uzsu,uzsuDropDown,18,19,20,21,22,23                         -> a dropDownMenue
    ... widgetOverride state:uzsu,knob,min:18,max:24,step:0.5,linecap:round,fgColor:red  -> a knob widget
    ... widgetOverride state:uzsu,colorpicker                                            -> a colorpicker
    ... widgetOverride state:uzsu,colorpicker,CT,2700,50,5000                            -> a colortemperature selector
            

  • colorpicker,RGB - create an RGB colorpicker
  • colorpicker,HSV - create an HSV colorpicker to set an rgb value
  • colorpicker,HSVp - create an HSV popup colorpicker to set an rgb value
  • colorpicker,HSV,<hue>,<min>,<step>,<max>,<sat>,<min>,<step>,<max>,<bri>,<min>,<step>,<max> - create an HSV colorpicker that uses <hue>, <sat> and <bri> as commands to set the color. can also be used with HSVp to create a popup colorpicker
    if the device has no combined hsv reading it can be create with the following user reading:attr userReadings hsv {ReadingsVal($name,'hue','0').','.ReadingsVal($name,'sat','100').','.ReadingsVal($name,'bri','100')}
  • colorpicker,CT,<min>,<step>,<max> - create a color temperature colorpicker
  • colorpicker,BRI,<min>,<step>,<max> - create a brightness colorpicker
  • colorpicker,HUE,<min>,<step>,<max> - create a hue colorpicker
  please see the fhem wiki Color section for example screenshots.
  
  
  • knob,min:1,max:100,... - shows the jQuery knob widget. The parameters are a comma separated list of key:value pairs, where key does not have to contain the "data-" prefix. For details see the jQuery-knob definition.
    Example: attr dimmer widgetOverride dim:knob,min:1,max:100,step:1,linecap:round
  • noArg - show no input field.
  • time - show a JavaScript driven timepicker.
    Example: attr FS20dev widgetOverride on-till:time
  • textField[,placeholder,inputSize] - show an input field.
    inputSize is the size attribute for the input field, defaults to 30.
    Example: attr WEB widgetOverride room:textField,Name_Of_The_Room,20
  • textFieldNL[,placeholder,inputSize] - show the input field and hide the label.
  • textField-long[,sizePct,inputSize] - show an input-field, but upon clicking on the input field open a textArea. sizePct specifies the size of the dialog relative to the screen, in percent. Default is 75
  • textFieldNL-long[,sizePct,inputSize] - the behaviour is the same as :textField-long, but no label is displayed.
  • slider,<min>,<step>,<max>[,1] - show a JavaScript driven slider. The optional ,1 at the end avoids the rounding of floating-point numbers.
  • multiple,<val1>,<val2>,...[,#inputSize]" - present a multiple-value-selector with an additional textfield. The result is comman separated.
  • multiple-strict,<val1>,<val2>,...[,#inputSize] - like multiple, but without the textfield.
  • selectnumbers,<min>,<step>,<max>,<number of digits after decimal point>,lin|log10" - display a select widget generated with values from min to max with step.
    lin generates a constantly increasing series. log10 generates an exponentially increasing series to base 10, step is related to the exponent, e.g. 0.0625.
  • select,<val1>,<val2>,... - show a dropdown with all values. NOTE: this is also the fallback, if no modifier is found.
  • bitfield,<size><mask> - show a table of checkboxes (8 per line) to set single bits. Default for size is 8 and for mask 2^32-1
  • widgetList,... - show a list of widgets. The arguments are concatenated, and separated be the length of the following argument list.
    Example: widgetList,3,select,opt1,opt2,1,textField
    Note: the values will be sent to FHEM as a comma separated list, and only preloaded widgets can be referenced.

FHT

Fhem can receive FHT radio (868.35 MHz) messages either through an FHZ or an CUL device, so this must be defined first.

Define
define <name> FHT <fhtaddress>

<fhtaddress> is a four digit hex number, corresponding to the address of the FHT80b device.
Examples:
define wz FHT 3232


See the FHT section in set for more.

Set
set <name> <valuetype> <value>

where value is one of:

desired-temp
day-temp night-temp
report1 report2
refreshvalues
mode
holiday1 holiday2 # see mode holiday_short or holiday
manu-temp # No clue what it does.
year month day hour minute
time date adjusthour adjustminute
lowtemp-offset # Alarm-Temp.-Differenz
windowopen-temp
mon-from1 mon-to1 mon-from2 mon-to2
tue-from1 tue-to1 tue-from2 tue-to2
wed-from1 wed-to1 wed-from2 wed-to2
thu-from1 thu-to1 thu-from2 thu-to2
fri-from1 fri-to1 fri-from2 fri-to2
sat-from1 sat-to1 sat-from2 sat-to2
sun-from1 sun-to1 sun-from2 sun-to2

Examples:
set wz desired-temp 22.5
set fl desired-temp 20.5 day-temp 19.0 night-temp 16.0


Notes:
• Following events are reported (more or less regularly) by each FHT device: measured-temp actuator actuator1...actuator8 warnings
  You can use these strings for notify or FileLog definitions.
  • warnings can contain following strings: none, Battery low,Temperature too low, Window open, Fault on window sensor
  • actuator (without a suffix) stands for all actuators.
  • actuator or actuator1..8 can take following values:
    • <value>%
      This is the normal case, the actuator is instructed to open to this value.
    • offset <value>%
      The actuator is running with this offset.
    • lime-protection
      The actuator was instructed to execute the lime-protection procedure.
    • synctime
      If you select Sond/Sync on the FHT80B, you'll see a count down.
    • test
      The actuator was instructed by the FHT80b to emit a beep.
    • pair
      The the FHT80b sent a "you-belong-to-me" to this actuator.


• The FHT is very economical (or lazy), it accepts one message from the FHZ1x00 every 115+x seconds, where x depends on the fhtaddress. Don't be surprised if your command is only accepted 10 minutes later by the device. FHT commands are buffered in the FHZ1x00/CUL till they are sent to the FHT, see the related fhtbuf entry in the get section.
  You can send up to 8 commands in one message at once to the FHT if you specify them all as arguments to the same set command, see the example above.


• time sets hour and minute to local time


• date sets year, month and date to local time


• adjusthour and adjustminute set hour or minute to local time, respectively


• refreshvalues is an alias for report1 255 report2 255


• All *-temp values need a temperature as argument, which will be rounded to 0.5 Celsius.
  Temperature values must between 5.5 and 30.5 Celsius. Value 5.5 sets the actuator to OFF, value 30.5 set the actuator to ON


• mode is one of auto, manual, holiday or holiday_short.
  If the mode is either holiday or holiday_short, then the mode switches back to auto at the specified day and time independent of the current mode of the device and the desired temperature will be set to the night or day temperature according to the defined weekly schedule stored within the device. In case of mode holiday
  • holiday1 sets the end-day of the holiday (at 00:00)
  • holiday2 sets the end-month of the holiday
  For holiday_short (party mode)
  • holiday1 sets the absolute hour to switch back from this mode (in 10-minute steps, max 144)
  • holiday2 sets the day of month to switch back from this mode (can only be today or tomorrow, since holiday1 accepts only 24 hours).
  Example:
  • current date is 29 Jan, time is 18:05
  • you want to switch to party mode until tomorrow 1:00
  • set holiday1 to 6 (6 x 10min = 1hour) and holiday2 to 30
  The temperature for the holiday period is set by the desired-temperature parameter.
  Note that you cannot set holiday mode for days earlier than the day after tomorrow, for this you must use holiday_short.
  The parameters holiday1 and holiday2 must be set in one command together with mode.
  Example:
  set FHT1 mode holiday holiday1 24 holiday2 12 desired-temp 14
  Please note: If the event time specified by the holiday parameters has already past, then the device will immediately switch back to auto mode including the selection of the corresponding day or night temperature. This is valid at least for FHT80b model 2 and 3, Lifetec MD12050. For those devices setting holiday_short with a holiday1 value of 0 and without the parameter holiday2 e.g.
  set FHT1 mode holiday_short holiday1 0
  will immediately switch back the device to mode auto including the adjustment of the desired- temp parameter. Some elderly FHT models, however, only switch the mode to auto, if the event is within the past, but don't adjust the desired temperature. In this case specifying appropriate values for the parameters holiday1 and holiday2 thus defining an event in the very near future (e.g. 10 minutes) could be the solution to force a switch back to the correct automatic mode.


• The *-from1/*-from2/*-to1/*-to2 valuetypes need a time spec as argument in the HH:MM format. They define the periods, where the day-temp is valid. The minute (MM) will be rounded to 10, and 24:00 means off.


• To synchronize the FHT time and to "wake" muted FHTs it is adviseable to schedule following command:
  define fht_sync at +*3:30 set TYPE=FHT time


• report1 with parameter 255 requests all settings for monday till sunday to be sent. The argument is a bitfield, to request unique values add up the following:
  • 1: monday
  • 2: tuesday
  • 4: thursday
  • 8: wednesday
  • 16: friday
  • 32: saturday
  • 64: sunday
  measured-temp and actuator is sent along if it is considered appropriate by the FHT.
  
  Note: This command generates a lot of RF traffic, which can lead to further problems, especially if the reception is not clear.


• report2 with parameter 255 requests the following settings to be reported: day-temp night-temp windowopen-temp lowtemp-offset desired-temp measured-temp mode warnings. The argument is (more or less) a bitfield, to request unique values add up the following:
  • 1: warnings
  • 2: mode
  • 4: day-temp, night-temp, windowopen-temp
  • 8: desired-temp
  • 64: lowtemp-offset
  measured-temp and actuator is sent along if it is considered appropriate by the FHT.


• lowtemp-offset needs a temperature as argument, valid values must be between 1.0 and 5.0 Celsius.
  It will trigger a warning if desired-temp - measured-temp > lowtemp-offset in a room for at least 1.5 hours after the last desired-temp change.


• FHEM optionally has an internal software buffer for FHT devices. This buffer should prevent transmission errors. If there is no confirmation for a given period, FHEM resends the command. You can see the queued commands with list <fht-device>. See the fhtsoftbuffer, retrycount and minfhtbuffer attributes for details.


• If a buffer is still in the softbuffer, it will be sent in the following order:
  desired-temp,mode,report1,report2, holiday1,holiday2,day-temp,night-temp, [all other commands]



Get
N/A

Attributes
• dummy
  Note:It makes sense to define an FHT device even for an FHT8b, else you will receive "unknown FHT device, please define one" message for each FHT8b as the CUL is reporting the 8b valve messages. But you should set the dummy attribute for these devices, else the internal FHT buffer of the CUL will be filled with data for the 8b's which is never consumed. If the buffer is full, you'll get "EOB" messages from the CUL, and you cannot transmit any data to the 80b's


• retrycount
  If the fhtsoftbuffer attribute is set, then resend commands retrycount times if after 240 seconds no confirmation message is received from the corresponding FHT device.
  Default is 1.


• minfhtbuffer
  FHEM won't send commands to the FHZ if its fhtbuffer is below this value, default is 0. If this value is low, then the ordering of fht commands (see the note in the FHT section of set) has little effect, as only commands in the softbuffer can be prioritized. The maximum value should be 7 below the hardware maximum (see fhtbuf).


• lazy
  If the lazy attribute is set, FHEM won't send commands to the FHT if the current reading and the value to be set are already identical. This may help avoiding conflicts with the max-1%-time-on-air rule in large installations. Not set per default.


• tmpcorr
  Correct the temperature reported by the FHT by the value specified. Note: only the measured-temp value reported by FHEM (used for logging) will be modified.


• ignore
• do_not_notify
• model (fht80b)
• showtime
• IODev
• eventMap
• readingFnAttributes

Generated events:
• actuator
• actuator1 actuator2 actuator3 actuator4
  actuator5 actuator6 actuator7 actuator8
  (sent if you configured an offset for the associated valve)
• mon-from1 mon-to1 mon-from2 mon-to2
• tue-from1 tue-to1 tue-from2 tue-to2
• wed-from1 wed-to1 wed-from2 wed-to2
• thu-from1 thu-to1 thu-from2 thu-to2
• fri-from1 fri-to1 fri-from2 fri-to2
• sat-from1 sat-to1 sat-from2 sat-to2
• sun-from1 sun-to1 sun-from2 sun-to2
• mode
• holiday1 holiday2
• desired-temp
• measured-temp measured-low measured-high
• warnings
• manu-temp
• year month day hour minute
• day-temp night-temp lowtemp-offset windowopen-temp
• ack can-xmit can-rcv ack2 start-xmit end-xmit (only if the CUL is configured to transmit FHT protocol data)

FHT8V

Fhem can directly control FHT8V type valves via a CUL device without an intermediate FHT. This paragraph documents one of the building blocks, the other is the PID device.

Define
define <name> FHT8V <housecode> [IODev|FHTID]

<housecode> is a four digit hex number, and must have the following relation to the housecode of the corresponding CUL device:
given the CUL housecode as AABB, then this housecode must be of the form CCBB, where CC is greater or equal to AA, but less then AA+8.
This form is chosen so that the CUL can update all FHT8V valve states within 2 minutes.

<IODev> must be specified if the last defined CUL device is not the one to use. Usually this is done voa the IODev attribute, but as the address checked is performed at the definition, we must use an exception here.
As an alternative you can specify the FHTID of the assigned IODev device (instead of the IODev itself), this method is needed if you are using FHT8V through FHEM2FHEM.
Examples:
define wz FHT8V 3232


Set
• set <name> valve <value;>
  Set the valve to the given value (in percent, from 0 to 100).
• set <name> pair
  Pair the valve with the CUL.
• set <name> decalc
  Start a decalcifying cycle on the given valve

Get
• get <name> valve
  Read back the valve position from the CUL FHT buffer, and convert it to percent (from 0 to 100).

Attributes
• IODev
• dummy
• ignore
• eventMap


• readingFnAttributes

FHZ

Note: this module requires the Device::SerialPort or Win32::SerialPort module if the devices is connected via USB or a serial port.

Define
define <name> FHZ <serial-device>

Specifies the serial port to communicate with the FHZ1000PC or FHZ1300PC. The name(s) of the serial-device(s) depends on your distribution.
If the serial-device is called none, then no device will be opened, so you can experiment without hardware attached.
The program can service multiple devices, FS20 and FHT device commands will be sent out through the last FHZ device defined before the definition of the FS20/FHT device. To change the association, use the IODev attribute.

For GNU/Linux you may want to read our hints for GNU/Linux about multiple USB devices.
Note:The firmware of the FHZ1x00 will drop commands if the airtime for the last hour would exceed 1% (which corresponds roughly to 163 commands). For this purpose there is a command counter for the last hour (see list FHZDEVICE), which triggers with "TRANSMIT LIMIT EXCEEDED" if there were more than 163 commands in the last hour.

If you experience problems (for verbose 4 you get a lot of "Bad CRC message" in the log), then try to define your device as
define <name> FHZ <serial-device> strangetty


Set
set FHZ <variable> [<value>]

where value is one of:

FHTcode
initFS20
initHMS
stopHMS
initfull
raw
open
reopen
close
time

Notes:
• raw is used to send out "raw" FS20/FHT messages ("setters" only - no query messages!). See message byte streams in FHEM/00_FHZ.pm and the doc directory for some examples.
• In order to set the time of your FHT's, schedule this command every minute:
  define fhz_timer at +*00:01:00 set FHZ time
  See the verbose to prevent logging of this command.
• FHTcode is a two digit hex number (from 00 to 63?) and sets the central FHT code, which is used by the FHT devices. After changing it, you must reprogram each FHT80b with: PROG (until Sond appears), then select CEnt, Prog, Select nA.
• If the FHT ceases to work for FHT devices whereas other devices (e.g. HMS, KS300) continue to work, a
  set FHZ initfull
  command could help. Try
  set FHZ reopen
  if the FHZ ceases to work completely. If all else fails, shutdown fhem, unplug and replug the FHZ device. Problems with FHZ may also be related to long USB cables or insufficient power on the USB - use a powered hub to improve this particular part of such issues. See our USB page for detailed USB / electromag. interference troubleshooting.
• initfull issues the initialization sequence for the FHZ device:
  
  get FHZ init2
get FHZ serial
set FHZ initHMS
set FHZ initFS20
set FHZ time
set FHZ raw 04 01010100010000

• reopen closes and reopens the serial device port. This implicitly initializes the FHZ and issues the initfull command sequence.
• stopHMS probably is the inverse of initHMS (I don't have authoritative info on what exactly it does).
• close closes and frees the serial device port until you open it again with open, e.g. useful if you need to temporarily unload the ftdi_sio kernel module to use the bit-bang mode.

Get
get FHZ <value>

where value is one of:

init1
init2
init3
serial
fhtbuf

Notes:
• The mentioned codes are needed for initializing the FHZ1X00
• The answer for a command is also displayed by list FHZ
• The FHZ1x00PC has a message buffer for the FHT (see the FHT entry in the set section). If the buffer is full, then newly issued commands will be dropped, if the attribute fhtsoftbuffer is not set. fhtbuf returns the free memory in this buffer (in hex), an empty buffer in the FHZ1000 is 2c (42 bytes), in the FHZ1300 is 4a (74 bytes). A message occupies 3 + 2x(number of FHT commands) bytes, this is the second reason why sending multiple FHT commands with one set is a good idea. The first reason is, that these FHT commands are sent at once to the FHT.

Attributes
• do_not_notify
  Disable FileLog/notify/inform notification for a device. This affects the received signal, the set and trigger commands.


• dummy


• showtime


• loglevel
  Note:Deprecated! The module maintainer is encouraged to replace it with verbose.
  
  Set the device loglevel to e.g. 6 if you do not wish messages from a given device to appear in the global logfile (FHZ/FS20/FHT). E.g. to set the FHT time, you should schedule "set FHZ time" every minute, but this in turn makes your logfile unreadable. These messages will not be generated if the FHZ attribute loglevel is set to 6.
  On the other hand, if you have to debug a given device, setting its loglevel to a smaller value than the value of the global verbose attribute, it will output its messages normally seen only with higher global verbose levels.


• model (fhz1000,fhz1300)


• fhtsoftbuffer
  As the FHZ command buffer for FHT devices is limited (see fhtbuf), and commands are only sent to the FHT device every 120 seconds, the hardware buffer may overflow and FHT commands get lost. Setting this attribute implements an "unlimited" software buffer.
  Default is disabled (i.e. not set or set to 0).

FLAMINGO

The FLAMINGO module interprets FLAMINGO FA20RF/FA21/FA22RF type of messages received by the SIGNALduino.
Of this smoke detector, there are identical types profitec KD101LA, POLLIN KD101LA or renkforce LM-101LD.

Define
define <name> FLAMINGO <code>


• <code> is the unic code of the autogenerated address of the FLAMINGO device. This changes, after pairing to the master
• <model> is the model name

- if autocreate, the defined model is unknown.
- with manual define you can choose the model which is available as attribute.


Set
• Counterreset
  - set alarmcounter to 0
• Testalarm
  - trigger a test alarm (The testalarm does not increase the alarm ounter!)

Get
N/A

Attributes
• IODev (!)
• do_not_notify
• eventMap
• ignore
• model
  FA20RF, FA21RF, FA22RF, KD-101LA, LM-101LD, unknown
• showtime
• readingFnAttributes


Generated readings
- alarmcounter | counter started with 0
- lastReceive_ID | the protocol ID from SIGNALduino
- state | (no Alarm, Alarm, Testalaram)


manual
Pairing (Master-Slave)
• Determine master
  LEARN button push until the green LED lights on
• Determine slave
  LEARN button push until the red LED lights on
• Master, hold down the TEST button until an alarm signal generated at all "Slaves"

Standalone
• LEARN button push until the green LED lights on
• TEST button hold down until an alarm signal generated

FLOORPLAN

Implements an additional entry "Floorplans" to your fhem menu, leading to a userinterface without fhem-menu, rooms or devicelists. Devices can be displayed at a defined coordinate on the screen, usually with a clickable icon allowing to switch the device on or off by clicking on it. A background-picture can be used - use e.g. a floorplan of your house, or any picture. Use floorplanstyle.css to adapt the representation.
Step-by-step setup guides are available in english and german.

Define
define <name> FLOORPLAN

Hint: Store fp_<name>.png in your image folder (www/images/default , www/pgm2 or FHEM) to use it as background picture.

Example:
define Groundfloor FLOORPLAN
fp_Groundfloor.png


Set
• N/A

Get
get <name> config
Displays the configuration of the floorplan with all attributes. Can be used in an include-file.

Attributes
• userattr fp_<name> <top>,<left>[,<style>[,<description>]]
  
  A userattr fp_<name> will be created automatically if it does not exist yet.
  
  • top = screen-position, pixels from top of screen
  • left = screen-position, pixels from left of screen
  • style =
    • 0 icon/state only
    • 1 devicename and icon/state
    • 2 devicename, icon/state and commands
    • 3 device-reading and optional description
    • 4 S300TH-specific, displays temperature above humidity
    • 5 icon/state and commands
    • 6 device-reading, reading-timestamp and optional description
    • 7 commands only
    • 8 commands popup
  • description will be displayed instead of the original devicename

Examples:


attr lamp1 fp_Groundfloor 100,100	#display lamp1 with icon only at screenposition 100,100
attr lamp2 fp_Groundfloor 100,140,1,Art-Deco	#display lamp2 with description 'Art-Deco-Light' at 100,140
attr lamp2 fp_FirstFloor 130,100,1	#display the same device at different positions on other floorplans
attr myFHT fp_Groundfloor 300,20,10,Temperature	#display given Text + FHT-temperature

Hint: no blanks between parameters


• fp_arrange
  Activates the "arrange mode" which shows an additional menu on the screen to choose style and description.
  When the arrange-mode is activated, devices can be placed freely on the screen by drag&drop. allowing to place devices easily on the screen.
  Example:
  attr Groundfloor fp_arrange 1
attr Groundfloor fp_arrange WEB #activates arrange mode for frontend-device WEB only
  
  
• stylesheet
  Explicitely sets your personal stylesheet for the floorplan. This overrides the standard stylesheet. The standard stylesheet for floorplans is floorplanstyle.css. If the stylesheetPrefix is set for the corresponding FHEMWEB instance, this same stylesheetPrefix is also prepended to the stylesheet for floorplans.
  All stylesheets must be stored in the stylesheet subfolder of the fhem filesystem hierarchy. Store your personal stylesheet along with floorplanstyle.css in the same folder.
  Example:
  attr Groundfloor stylesheet myfloorplanstyle.css
  
  
• fp_default
  The floorplan startscreen is skipped if this attribute is assigned to one of the floorplans in your installation.
Example:
attr Groundfloor fp_default 1


• fp_noMenu
  Suppresses the menu which usually shows the links to all your floorplans.
Example:
attr Groundfloor fp_noMenu 1


• commandfield
  Adds a fhem-commandfield to the floorplan screen.
Example:
attr Groundfloor commandfield 1


• fp_backgroundimg
  Allows to choose a background-picture independent of the floorplan-name.
Example:
attr Groundfloor fp_backgroundimg foobar.png


• fp_viewport
  Allows usage of a user-defined viewport-value for touchpad.
  Default-viewport-value is "width=768".
• fp_roomIcons
  Space separated list of floorplan:icon pairs, to assign icons to the floorplan-menu, just like the functionality for rooms in FHEMWEB. Example:
  attr Grundriss fp_roomIcons Grundriss:control_building_empty Media:audio_eq
• Inherited from FHEMWEB
  The following attributes are inherited from the underlying FHEMWEB instance:
  
  smallscreen
  touchpad
  refresh
  plotmode
  plotsize
  webname
  redirectCmds
  longpoll
  allowedCommands
  

FRAMEBUFFER

Provides a device to display arbitrary content on a linux framebuffer device

You need to have the perl module GD installed. This module is most likely not available for small systems like Fritz!Box.

FRAMEBUFFER uses RSS to create an image that is displayed on the framebuffer.
The binary program fbvs is required to display the image. You can download it from github.

Define
define <name> FRAMEBUFFER <framebuffer_device_name>

Defines a framebuffer device. <framebuffer_device_name> is the name of the linux device file for the kernel framebuffer device, e.g. /dev/fb1 or /dev/fb0. Examples:
define display FRAMEBUFFER /dev/fb1
define TV FRAMEBUFFER /dev/fb0



Set
set <name> absLayoutNo <number>

A list of layout files can be defined with attr layoutList, see below. This command selects the layout with the given number from this list and displays it. This can e.g. be useful if bound to a key of a remote control to display a specific layout.


set <name> layoutFilename <name> [<timeout in seconds>]

Displays the image described by the layout in file <name>. If <name> is an absolute path name it is used as is to access the file. Otherwise the attribute <layoutBasedir> is prepended to the <name>. If a timeout is given, the image is only displayed for timeout seconds before the previously displayed image is displayed again. Useful for displaying an image only for a certain time after an event has occured.


set <name> relLayoutNo <number>

Like absLayoutNo this displays a certain image from the layoutList. Here <number> is added to the current layout number. So
set <name> relLayoutNo 1 displays the next image from the list while
set <name> relLayoutNo -1
displays the previous one. Useful if bound to a next/previous key on a remote control to scroll through all defined layouts.


set <name> updateDisplay

Refreshes the display defined by the currently active layout.


Attributes

size <width>x<height>
The dimensions of the display in pixels. Images will generated using this size. If the size is greater than the actual display size they will be scaled to fit. As this requires computing performance it should be avoided by defining the size to match the display size.
Example
attr <name> size 128x160


layoutBasedir <directory name>
Directory that contains the layout files. If a layout filename is specified using a relative path layoutBasedir will be prepended before accessing the file.
Example
attr <name> layoutBasedir /opt/fhem/layouts


layoutList <file1> [<file2>] ...
Space separated list of layout files. These will be used by absLayoutNo and relLayoutNo. layoutBasedir will be prepended to each file if it is a relative path.
Example
attr <name> layoutList standard.txt wetter.txt schalter.txt


update_interval <interval>
Update interval in minutes. The currently displayed layout will be refreshed every <interval> minutes. The first interval will be scheduled to the beginning of the next minute to help create an accurate time display.

Example
attr <name> update_interval 1


debugFile <file>
Normally the generated image isn't written to a file. To ease debugging of layouts the generated image is written to the filename specified by this attribute. This attribute shouldn't be set during normal operation.


startLayoutNo <number>
The number of the layout to be displayed on startup of the FRAMEBUFFER device.


bgcolor <color>
Sets the background color. <color> is a 6-digit hex number, every 2 digits determining the red, green and blue color components as in HTML color codes (e.g.FF0000 for red, C0C0C0 for light gray).


enableCmd <fhem cmd>
if set this command is executed before a layout with a timeout is displayed. This can e.g. be used to enable a backlight.


disableCmd <fhem cmd>
if set this command is executed after a layout with a timeout has expired. This can e.g. be used to disable a backlight.


Usage information

This module requires the binary program fbvs to be installed in /usr/local/bin and it must be executable by user fhem. fbvs (framebuffer viewer simple) is a stripped down version of fbv that can only display png images. It reads the image from stdin, displays it on the framebuffer and terminates afterwards. This module generates a png image based on a layout description internally and then pipes it to fbvs for display.

Layout definition

FRAMEBUFFER uses the same layout definition as RSS. In fact FRAMEBUFFER calls RSS to generate an image.

FRITZBOX

FRM

This module enables FHEM to communicate with a device (e.g. an Arduino) that implements the Firmata Protocol.

The connection between FHEM and the Firmata device can be established by serial port, USB, LAN or WiFi.

A single FRM device can serve multiple FRM clients from this list:

I2C_BH1750, I2C_BME280, I2C_BMP180, I2C_DS1307, I2C_K30, I2C_LCD, I2C_LM75A, I2C_MCP23008, I2C_MCP23017, I2C_MCP342x, I2C_PCA9532, I2C_PCA9685, I2C_PCF8574, I2C_SHT21, I2C_SHT3x, I2C_TSL2561, FRM_AD, FRM_I2C, FRM_IN, FRM_LCD, FRM_OUT, FRM_PWM, FRM_RGB, FRM_ROTENC, FRM_SERVO, FRM_STEPPER, OWX, OWX_ASYNC

Each client stands for a pin of the Firmata device configured for a specific use (digital/analog in/out) or an integrated circuit connected to Firmata device by I2C.

Define

Prerequisites:

(1) Install version 0.69 or higher of the Perl module Device::Firmata, e.g. via OS command line:

cpan install Device::Firmata

Note that this Perl module was distributed as part of FHEM until August 2020 and must now be installed and updated separately. If a version of the Perl module still exists in the subdir FHEM/lib/Device it must be removed.

(2) Install the Perl module Device::SerialPort (Linux platform) or Win32::SerialPort (Windows platform) if you attach the device via serial port or USB, e.g. via OS command line:

cpan install Device::SerialPort or
cpan install Win32::SerialPort

Additional information on how to install Perl modules can be found in the FHEM Wiki. define <name> FRM {<device> | <port> [global]}


• serial and USB connected devices:
  
  <device> specifies the serial port to communicate with the Firmata device. The name of the serial-device depends on your distribution, under linux the cdc_acm kernel module is responsible, and usually a /dev/ttyACM0 device will be created. If your distribution does not have a cdc_acm module, you can force usbserial to handle the Firmata device by the following command:
  modprobe usbserial vendor=0x03eb product=0x204b
  In this case the device is most probably /dev/ttyUSB0.
  
  You can also specify a baudrate if the device name contains the @ character, e.g.: /dev/ttyACM0@38400
  
  If the baudrate is "directio" (e.g.: /dev/ttyACM0@directio), then the perl module Device::SerialPort is not needed, and FHEM opens the device with simple file io. This might work if the operating system uses the same defaults for the serial parameters as the Firmata device, e.g. some Linux distributions and OSX.
  
  An Arduino compatible device should either use 'StandardFirmata' or 'ConfigurableFirmata' without NetworkFirmata.


• network connected devices:
  
  <port> specifies the port the FRM device listens on. If global is specified the socket is bound to all local IP addresses, otherwise to localhost only.
  
  The connection is initiated by the Firmata device in client-mode. Therefore the IP address and port of the FHEM server has to be configured in the Firmata device, so it knows where to connect to.
  For multiple Firmata you need separate FRM devices configured to different ports.
  
  An Arduino compatible device should run one of 'StandardFirmataEthernet', 'StandardFirmataWiFi', 'ConfigurableFirmata' with NetworkFirmata or 'ConfigurableFirmataWiFi'.


• no device:
  
  If <device> is set to none, no connection will be opened and you can experiment without hardware attached.
  

StandardFirmata supports digital and analog-I/O, servos and I2C. In addition to that ConfigurableFirmata supports 1-Wire and stepper motors.

You can find StandardFirmata, StandardFirmataEthernet and StandardFirmataWiFi in the Arduino IDE in the menu 'File->Examples->Firmata'

ConfigurableFirmata can be installed using the library manager of the Arduino IDE.

Further information can be found at the FRM client devices listed above and the FHEM-Wiki.

Set
• set <name> reinit
  reinitializes the FRM client devices attached to this FRM device


• set <name> reset
  performs a software reset on the Firmata device and disconnects form the Firmata device - after the Firmata device reconnects the attached FRM client devices are reinitialized


• set <name> sendString <message>
  sends a string message to the the Firmata device


Attributes

• resetDeviceOnConnect {0|1}, default: 1
  Reset the Firmata device immediately after connect to force default Firmata startup state: All pins with analog capability are configured as input, all other (digital) pins are configured as output and the input pin reporting, the I2C configuration and the serial port configuration are cancelled and will be reinitialized.


• i2c-config <write-read-delay>, no default
  Configure the Arduino for I2C communication. Definig this attribute will enable I2C on all i2c_pins received by the capability-query issued during initialization of FRM.
  As of Firmata 2.3 you can set a delay-time (in microseconds, max. 32767, default: 0) that will be inserted into I2C protocol when switching from write to read. This may be necessary because Firmata I2C write does not block on the FHEM side so consecutive I2C write/read operations get queued and will be executed on the Firmata device in a different time sequence. Use the maximum operation time required by the connected I2C devices (e.g. 30000 for the BMP180 with triple oversampling, see I2C device manufacturer documentation for details).
  See: Firmata Protocol details about I2C


• sampling-interval <interval>, default: 1000 ms
  Configure the interval Firmata reports analog data to FRM (in milliseconds, max. 32767).
  This interval applies to the operation of FRM_I2C.
  See: Firmata Protocol details about Sampling Interval


• software-serial-config <port>:<rx pin>:<tx pin>, no default
  For using a software serial port (port number 8, 9, 10 or 11) two I/O pins must be specified. The rx pin must have interrupt capability and the tx pin must have digital output capability.
  See: Arduino SoftwareSerial Library


• errorExclude <regexp>, no default
  If set will exclude a string message received from the Firmata device that matches the given regexp from being logged at verbose=3 and will assign the data to the reading stringMessage instead of error. Logging will still be done at verbose=5.


• disable {0|1}, default: 0
  Disables this devices if set to 1.


• ping-interval <interval>, default: disabled
  Configure the interval in milliseconds for FHEM to send the string message ping to the firmata device (e.g. 10000 ms). The default Firmata device implementation will ignore this message on receive.
  This should be enabled when FHEM is not configured to periodically send data to a network connected Firmata device to be able to detect an abnormal device disconnect (e.g. caused by a device power off). For the same reasons you can add Firmata.sendString("ping"); to the sketch of the Firmata device if the Firmata device is not configured to send data periodically to FHEM. Note that this type of disconnect detection will not be immediate but will take several minutes to trigger.


• receiveTimeout <timeout>, default: disabled
  If a network connected Firmata device is expected to periodically send messages (e.g. analog data or ping) this timeout may be set to a none zero number of seconds after which the network connection will be closed. Choose a value high enough to avoid unintended disconnects. Take into account the time it takes to setup the Firmata device and the behaviour of other FHEM devices that may occupy FHEM for several seconds with some operations.
  This can be used to detect a Firmata device malfunction.


• dummy {0|1}, default: 0
  Will be set to 1 if device is set to none. Reserved for internal use, do not set manually!


• global attributes
• readingFnAttributes


Readings

• state
  Possible values are: defined | disabled | error and depending on the connection type:
  serial: opened | connected | Initialized | disconnected
  network: listening | connected | Initialized


• error
  Data of last string message received from Firmata device, typically (but not necessarily) an error of the last operation. Data prefixed with I2C will additionally be assigned to the internal reading I2C_ERROR.


• stringMessage
  Data of last string message received from Firmata device that matches attribute errorExclude.


Internals

• DRIVER_VERSION
  Version of the Perl module Device::Firmata.


• DRIVER_STATUS
  Compatibility info of the Perl module Device::Firmata.


• protocol_version
  Firmata protocol version reported by the Firmata device.


• firmware
  Firmata firmware name reported by the Firmata device (this is typically the Arduino project name).


• firmware_version
  Firmata firmware version reported by the Firmata device.


• xxx_pins | xxx_resolutions | xxx_ports
  Pin capability reported by the Firmata device, where xxx can be one of the following:
  • input | pullup: digital input, see FRM_IN
  • output: digital output, see FRM_OUT
  • analog: analog input with ADC of given resolution, see FRM_AD
  • pwm: digital output with PWM capability with DAC of given resolution, see FRM_PWM
  • servo: analog output with servo capability of given resolution, see FRM_SERVO
  • i2c: I2C compatible pin, FRM can be used as IODev of another FHEM I2C device
  • onewire: OneWire compatible pin, FRM can be used as IODev of OWX
  • stepper: stepper output pin of given resolution, see FRM_STEPPER
  • encoder: rotary encoder input pin of given resolution, see FRM_ROTENC
  • serial: serial rx/tx pin of given port, FRM can be used as serial device of another FHEM device, see notes
  
  Note: A reported capability is a minimum requirement but does not guarantee that this pin function is really available. Some reasons for this are (a) boards with same model name may have different hardware and firmware revisions with different hardwired special functions for specific pins and (b) a pin function may depend on the Arduino platform and specific library version. When something does not work on the fist pin you try and you can rule out a wiring problem try some other pins or try to find manufacturer documentation.


Notes

• Digital Pins
  WARNING: Stock Firmata has a notable default: At the end of the initialization phase of the Firmata device after boot or reset and before a host connection can be established all pins with analog input capability will be configured as analog input and all pins with "only" digial I/O capability are configured as outputs and set to off. ConfigurableFirmata is a little bit more selective in this respect and will only do this if you enable AnalogInputFirmata or DigitalOutputFirmata respectively. If your board has a pin without analog capability and you have wired this pin as a digital input this behaviour might damage your circuit. CPUs typically set input mode for GPIO pins when resetting to prevent this.
  
  You should look for the function "void systemResetCallback()" in your Firmata sketch and change "Firmata.setPinMode(i, OUTPUT);" to "Firmata.setPinMode(i, INPUT);" to get a save initial state or completely customize the default state of each pin according to your needs by replacing the Firmata reset code.


• Serial Ports
  A serial device can be connected to a serial port of a network connected Firmata device instead of being directly connected to your FHEM computer. This way the Firmata device will become a serial over LAN (SOL) adapter. To use such a remote serial port in other FHEM modules you need to set the serial device descriptor to:
  
  FHEM:DEVIO:<FRM device name>:<serial port>@<baud rate>
  
  To use a serial port both the RX and TX pin of this port must be available via Firmata, even if one of the pins will not be used. Depending on the Firmata version the first hardware serial port (port 0) cannot be used even with network connected devices because port 0 is still reserved for the Arduino host communication. On some Arduinos you can use software serial ports (ports 8 to 11). FRM supports a maximum of one software serial port that can be activated using the software-serial-config attribute.
  
  In current Firmata versions serial setup options (data bits, parity, stop bits) cannot be configured but may be compiled into the Firmata Firmware (see function "((HardwareSerial*)serialPort)->begin(baud, options)" in SerialFirmata.cpp of the Firmata library).
  
  Not all FHEM modules for serial devices are compatible with this mode of operation. It will not work if (1) the FHEM module requires hardware handshake or direct IO of serial pin like CTS or DTR or (2) the FHEM module does not support the syntax of serial device descriptor (e.g. the HEATRONIC module works perfectly with a single line patch).

FRM_AD

This module represents a pin of a Firmata device that should be configured as an analog input.

Requires a defined FRM device to work. The pin must be listed in the internal reading "analog_pins"
of the FRM device (after connecting to the Firmata device) to be used as analog input.

Define
define <name> FRM_AD <pin>

Defines the FRM_AD device. <pin> is the arduino-pin to use.

Set

N/A


Get

• reading
  returns the voltage-level equivalent at the arduino-pin. The min value is zero and the max value
  depends on the Firmata device (see internal reading "analog_resolutions" of the FRM device.
  For 10 bits resolution the range is 0 to 1023 (also see analogRead() for details)
  
• alarm-upper-threshold
  returns the current state of 'alarm-upper-threshold'. Values are 'on' and 'off' (Defaults to 'off')
  'alarm-upper-threshold' turns 'on' whenever the 'reading' is higher than the attribute 'upper-threshold'
  it turns 'off' again as soon 'reading' falls below 'alarm-upper-threshold'
• alarm-lower-threshold
  returns the current state of 'alarm-lower-threshold'. Values are 'on' and 'off' (Defaults to 'off')
  'alarm-lower-threshold' turns 'on' whenever the 'reading' is lower than the attribute 'lower-threshold'
  it turns 'off' again as soon 'reading rises above 'alarm-lower-threshold'
• state
  returns the 'state' reading

Attributes

• upper-threshold
  sets the 'upper-threshold'. Whenever the 'reading' exceeds this value 'alarm-upper-threshold' is set to 'on'
  As soon 'reading' falls below the 'upper-threshold' 'alarm-upper-threshold' turns 'off' again
  Defaults to the max pin resolution plus one.
• lower-threshold
  sets the 'lower-threshold'. Whenever the 'reading' falls below this value 'alarm-lower-threshold' is set to 'on'
  As soon 'reading' rises above the 'lower-threshold' 'alarm-lower-threshold' turns 'off' again
  Defaults to -1.
• IODev
  Specify which FRM to use. Only required if there is more than one FRM-device defined.
• global attributes
• readingFnAttributes

Notes

• attribute stateFormat
  In most cases it is a good idea to assign "reading" to the attribute stateFormat. This will show the current value of the pin in the web interface.

FRM_I2C

This module provides read and write capabilities for an I2C device that is wired to a Firmata device. It requires a defined FRM device to work. I2C bus support must be enabled on the FRM device by setting the attribute i2c-config to a valid value.

If periodic reading is enabled the requested bytes will be updated depending on the attribute sampling-interval of the FRM device as soon as the Firmata device is connected.

Define

define <name> FRM_I2C <i2c-address> <register> <bytes-to-read>


• i2c-address is the I2C bus address (decimal) of the I2C device
• register is the I2C register address (decimal) to start reading bytes from
• bytes-to-read is the number of bytes to read periodically from the I2C device, the maximum number of bytes that can be read at the same time is limited by the Firmata firmware, the I2C device capabilities and the sampling-interval attribute of the FRM device, set to zero to disable periodic reading

Get

• register <register> [<bytes-to-read>]
  request single asynchronous read of the specified number of bytes from the I2C register
  bytes-to-read defaults to 1 if not specified, the maximum number of bytes that can be read at the same time is limited by the Firmata firmware and the I2C device capabilities

Set

• register <register> <byte> [<byte> ... <byte>]
  write the space separated list of byte values to the specified I2C register

Attributes

• IODev
  Specify which FRM to use. Only required if there is more than one FRM-device defined.
• global attributes
• readingFnAttributes

Readings

• values
  space separated list of 256 byte register image using decimal values - may be preset to any value, only the requested bytes will be updated

FRM_IN

This module represents a pin of a Firmata device that should be configured as a digital input.

Requires a defined FRM device to work. The pin must be listed in the internal reading "input_pins" or "pullup_pins" of the FRM device (after connecting to the Firmata device) to be used as digital input with or without pullup.

Define
define <name> FRM_IN <pin>
Defines the FRM_IN device. <pin>> is the Firmata pin to use.

Set

• alarm on|off
  set the 'alarm' reading to on or off. Typically used to clear the alarm. The alarm is set to 'on' whenever the count reaches the threshold and doesn't clear itself.
• count
  set the 'count' reading to a specific value. The counter is incremented depending on the attribute 'count-mode'.

Get
• reading
  returns the logical state of the input pin last received from the Firmata device depending on the attribute 'activeLow'. Values are 'on' and 'off'.
  
• count
  returns the current counter value. Contains the number of toggles reported by the Fimata device on this input pin. Depending on the attribute 'count-mode' every rising or falling edge (or both) is counted.
• alarm
  returns the 'alarm' reading. Values are 'on' and 'off' (Defaults to 'off'). The 'alarm' reading doesn't clear itself, it has to be set to 'off' explicitly.
• state
  returns the 'state' reading

Attributes

• activeLow yes|no
  inverts the logical state of the pin reading if set to yes (defaults to 'no').
• count-mode none|rising|falling|both
  Determines whether 'rising' (transitions from 'off' to 'on') of falling (transitions from 'on' to 'off') edges (or 'both') are counted (defaults to 'none').
• count-threshold <number>
  sets the threshold-value for the counter - if defined whenever 'count' exceeds the 'count-threshold' the 'alarm' reading is set to 'on' (defaults to undefined). Use 'set alarm off' to clear the alarm.
• reset-on-threshold-reached yes|no
  if set to 'yes' reset the counter to 0 when the threshold is reached (defaults to 'no').
• internal-pullup on|off
  enables/disables the internal pullup resistor of the Firmata pin (defaults to 'off'). Requires hardware and firmware support.
• IODev
  Specify which FRM to use. Only required if there is more than one FRM-device defined.
• global attributes
• readingFnAttributes

Notes

• attribute stateFormat
  In most cases it is a good idea to assign "reading" to the attribute stateFormat. This will show the state of the pin in the web interface.
• attribute count-mode
  The count-mode does not depended on hardware or firmware of the Firmata device because it is implemented in FHEM. The counter will not be updated while the Firmata device is not connected to FHEM. Any changes of the pin state during this time will be lost.

FRM_OUT

This module represents a pin of a Firmata device that should be configured as a digital output.

Requires a defined FRM device to work. The pin must be listed in the internal reading "output_pins"
of the FRM device (after connecting to the Firmata device) to be used as digital output.

Define
define <name> FRM_OUT <pin>
Defines the FRM_OUT device. <pin>> is the arduino-pin to use.

Set

set <name> on|off


set extensions are supported


Get

N/A

Attributes

• restoreOnStartup <on|off>, default: on
  Set output value in Firmata device on FHEM startup (if device is already connected) and whenever the setstate command is used.
• restoreOnReconnect <on|off>, default: on
  Set output value in Firmata device after IODev is initialized.
• activeLow <yes|no>, default: no
• IODev
  Specify which FRM to use. Only required if there is more than one FRM-device defined.
• valueMode <send|receive|bidirectional>, default: send
  Define how the reading value is updated:
  
  • send - after sending
  • receive - after receiving
  • bidirectional - after sending and receiving
• global attributes
• readingFnAttributes

Notes

• attribute stateFormat
  In most cases it is a good idea to assign "value" to the attribute stateFormat. This will show the state of the pin in the web interface.
• attribute valueMode
  For modes "receive" and "bidirectional" to work the default Firmata application code must be modified in function "setPinModeCallback":
  add " || mode == OUTPUT" to the if condition for "portConfigInputs[pin / 8] |= (1 << (pin & 7));" to enable
  reporting the output state (as if the pin were an input). This is of interest if you have custom code in your Firmata device that my change to pin state.
  the state of an output or you want a feedback from the Firmata device after the output state was changed.

FRM_PWM

This module represents a pin of a Firmata device that should be configured as a pulse width modulated output (PWM).

Requires a defined FRM device to work. The pin must be listed in the internal reading "pwm_pins" of the FRM device (after connecting to the Firmata device) to be used as PWM output.

Define
define <name> FRM_PWM <pin>

Defines the FRM_PWM device. <pin>> is the arduino-pin to use.

Set
• set <name> on
  sets the pulse-width to 100%
  
• set <name> off
  sets the pulse-width to 0%
  
• set extensions are supported
  
• set <name> toggle
  toggles the pulse-width in between to the last value set by 'value' or 'dim' and 0 respectivly 100%
  
• set <name> value <value>
  sets the pulse-width to the value specified
  The min value is zero and the max value depends on the Firmata device (see internal reading
  "pwm_resolutions" of the FRM device). For 8 bits resolution the range is 0 to 255 (also see analogWrite() for details)
  
• set <name> dim <value>
  sets the pulse-width to the value specified in percent
  Range is from 0 to 100
  
• set <name> dimUp
  increases the pulse-width by 10%
  
• set <name> dimDown
  decreases the pulse-width by 10%
  

Get

• get <dim>
  returns current dim setting in percent, see description for set command for more details
  
• get <value>
  returns current dim setting, see description for set command for more details
  

Attributes

• restoreOnStartup <on|off>
• restoreOnReconnect <on|off>
• IODev
  Specify which FRM to use. Only required if there is more than one FRM-device defined.
• global attributes
• readingFnAttributes

Notes

• attribute stateFormat
  In most cases it is a good idea to assign "value" to the attribute stateFormat. This will show the current value of the pin in the web interface.

FRM_RGB

allows to drive LED-controllers and other multichannel-devices that use PWM as input by an Arduino running Firmata
The value set will be output by the specified pins as pulse-width-modulated signals.
Requires a defined FRM-device to work.

Define
define <name> FRM_RGB <pin> <pin> <pin> [pin...]
Defines the FRM_RGB device. <pin>> are the arduino-pin to use.
For rgb-controlled devices first pin drives red, second pin green and third pin blue.

Set

set <name> on
sets the pulse-width of all configured pins to 100%


set <name> off
sets the pulse-width of all configured pins to 0%


set extensions are supported


set <name> toggle
toggles in between the last dimmed value, 0% and 100%. If no dimmed value was set before defaults to pulsewidth 50% on all channels


set <name> rgb <value>
sets the pulse-width of all channels at once. Also sets the value toggle can switch to
Value is encoded as hex-string, 2-digigs per channel (e.g. FFFFFF for reguler rgb)


set <name> pct <value>
dims all channels at once while leving the ratio in between the channels unaltered.
Range is 0-100 ('pct' stands for 'percent')


set <name> dimUp
dims up by 10%


set <name> dimDown
dims down by 10%

Get

get <name> rgb
returns the values set for all channels. Format is hex, 2 nybbles per channel.


get <name> RGB
returns the values set for all channels in normalized format. Format is hex, 2 nybbles per channel. Values are scaled such that the channel with the highest value is set to FF. The real values are calculated by multipying each byte with the value of 'pct'.


get <name> pct
returns the value of the channel with the highest value scaled to the range of 0-100 (percent).

Attributes

• restoreOnStartup <on|off>
• restoreOnReconnect <on|off>
• IODev
  Specify which FRM to use. Only required if there is more than one FRM-device defined.
• global attributes
• readingFnAttributes

FRM_ROTENC

represents a rotary-encoder attached to two pins of an Arduino running Firmata
Requires a defined FRM-device to work.

Define
define <name> FRM_ROTENC <pinA> <pinB> [id]
Defines the FRM_ROTENC device. <pinA>> and <pinA>> are the arduino-pins to use.
[id] is the instance-id of the encoder. Must be a unique number per FRM-device (rages from 0-4 depending on Firmata being used, optional if a single encoder is attached to the arduino).


Set

• reset
  resets to value of 'position' to 0
  
• offset <value>
  set offset value of 'position'
  

Get
• position
  returns the position of the rotary-encoder attached to pinA and pinB of the arduino
  the 'position' is the sum of 'value' and 'offset'
  
• offset
  returns the offset value
  on shutdown of fhem the latest position-value is saved as new offset.
  
• value
  returns the raw position value as it's reported by the rotary-encoder attached to pinA and pinB of the arduino
  this value is reset to 0 whenever Arduino restarts or Firmata is reinitialized
  

Attributes

• IODev
  Specify which FRM to use. Only required if there is more than one FRM-device defined.
• global attributes
• readingFnAttributes

FRM_SERVO

represents a pin of an Arduino running Firmata configured to drive a pwm-controlled servo-motor.
The value set will be drive the shaft of the servo to the specified angle. see Servo.write for values and range
Requires a defined FRM-device to work.

Define
define <name> FRM_SERVO <pin>
Defines the FRM_SERVO device. <pin>> is the arduino-pin to use.

Set

set <name> angle <value>
sets the angle of the servo-motors shaft to the value specified (in degrees).

Get

N/A

Attributes

• IODev
  Specify which FRM to use. Only required if there is more than one FRM-device defined.
• min-pulse
  sets the minimum puls-width to use. Defaults to 544. For most servos this translates into a rotation of 180° counterclockwise.
• max-pulse
  sets the maximum puls-width to use. Defaults to 2400. For most servos this translates into a rotation of 180° clockwise.
• global attributes
• readingFnAttributes

FRM_STEPPER

represents a stepper-motor attached to digital-i/o pins of an Arduino running Firmata
Requires a defined FRM-device to work.

Define
define <name> FRM_STEPPER [DRIVER|TWO_WIRE|FOUR_WIRE] <directionPin> <stepPin> [motorPin3 motorPin4] stepsPerRev [stepper-id]
Defines the FRM_STEPPER device.
• [DRIVER|TWO_WIRE|FOUR_WIRE] defines the control-sequence being used to drive the motor.
  • DRIVER: motor is attached via a smart circuit that is controlled via two lines: 1 line defines the direction to turn, the other triggers one step per impluse.
  • FOUR_WIRE: motor is attached via four wires each driving one coil individually.
  • TWO_WIRE: motor is attached via two wires. This mode makes use of the fact that at any time two of the four motor coils are the inverse of the other two so by using an inverting circuit to drive the motor the number of control connections can be reduced from 4 to 2.
• • The sequence of control signals for 4 control wires is as follows:
    
    Step C0 C1 C2 C3
1 1 0 1 0
2 0 1 1 0
3 0 1 0 1
4 1 0 0 1

  • The sequence of controls signals for 2 control wires is as follows:
    (columns C1 and C2 from above):
    
    Step C0 C1
1 0 1
2 1 1
3 1 0
4 0 0

• If your stepper-motor does not move or does move but only in a single direction you will have to rearrage the pin-numbers to match the control sequence. That can be archived either by rearranging the physical connections, or by mapping the connection to the pin-definitions in FRM_STEPPERS define:
  e.g. the widely used cheap 28byj-48 you can get for few EUR on eBay including a simple ULN2003 driver interface may be defined by
  define stepper FRM_STEPPER FOUR_WIRE 7 5 6 8 64 0
  when being connected to the arduio with:
  
  motor pin1 <-> arduino pin5
motor pin2 <-> arduino pin6
motor pin3 <-> arduino pin7
motor pin4 <-> arduino pin8
motor pin5 <-> ground



Set

set <name> reset
• resets the reading 'position' to 0 without moving the motor

set <name> position <position> [speed] [acceleration] [deceleration]
• moves the motor to the absolute position specified. positive or negative integer
  speed (10 * revolutions per minute, optional), defaults to 30, higher numbers are faster. At 2048 steps per revolution (28byj-48) a speed of 30 results in 3 rev/min
  acceleration and deceleration are optional.
  

set <name> step <stepstomove> [speed] [accel] [decel]
• moves the motor the number of steps specified. positive or negative integer
  speed, accelleration and deceleration are optional.
  

Get

get <position>
• returns the current position value

Attributes

• restoreOnStartup <on|off>
• restoreOnReconnect <on|off>
• IODev
  Specify which FRM to use. Only required if there is more than one FRM-device defined.
• >speed (same meaning as in 'set position')
• acceleration (same meaning as in 'set position')
• deceleration (same meaning as in 'set position')
• global attributes
• readingFnAttributes

FReplacer

This module provides a generic way to modify the contents of a file with Readings of other devices or the result of Perl expressions.
The typical use case is a custom designed SVG graphics template file which contains place holders that will be replaced with actual values.
The resulting SVG file can then optionally be converted to a PNG file which can be used as an online screensaver for Kindle devices for example.

Define

define <name> FReplacer <InputFile> <OutputFile> <Interval>

The module reads the given InputFile every Interval seconds, replaces strings with the results of expressions as defined in attributes and writes the result to the OutputFile

Example:

define fr FReplacer /opt/fhem/www/images/template.svg /opt/fhem/www/images/status.svg 60

Configuration of FReplacer Devices


Specify pairs of attr FxxRegex and attr FxxReading or attr FxxExpr to define which strings / placeholders in the InputFile should be replaced with which redings / expressions

Example:

define fr FReplacer /opt/fhem/www/images/template.svg /opt/fhem/www/images/status.svg 60
attr fr Rep01Regex HeizungStat
attr fr Rep01Reading WP:Status
attr fr Rep01MaxAge 600:Heizung Aus
attr fr Rep02Regex AbluftTemp
attr fr Rep02Reading Lueftung:Temp_Abluft
attr fr Rep02Format "%.1f"
attr fr Rep03Regex AussenTemp
attr fr Rep03Expr sprintf("%.1f", ReadingsVal("Lueftung", "Temp_Aussen", 0))


If you want to convert a resulting SVG file to a PNG e.g. for use as online screen saver on a Kindle device,
you have to specify the external conversion command with the attribute PostCommand, for Example:

attr fr PostCommand convert /opt/fhem/www/images/status.svg -type GrayScale -depth 8 /opt/fhem/www/images/status.png 2>/dev/null &

If you want to convert the replacement text from Readings to UTF8, e.g. to make special characters / umlauts display correctly, specify
attr fr ReplacementEncode UTF-8


Set-Commands

• ReplaceNow
starts a replace without waiting for the interval

Get-Commands

none

Readings

• LastUpdate
Date / Time of the last update of the output file / image. This reading is formatted with strftime and the default format string is "%d.%m.%Y %T".
This can be changed with the attribute LUTimeFormat.

Attributes


• Rep[0-9]+Regex
  defines the regex to be used for finding the right string to be replaced with the corresponding Reading / Expr result
• Rep[0-9]+Reading
  defines a device and reading to be used as replacement value. It is specified as devicename:readingname:default_value.
  The default_value is optional and defaults to 0. If the reading doesn't exist, default_value is used.
• Rep[0-9]+Text
  Use static text as replacement value.
• Rep[0-9]+Tidy
  XML encode special characters in this replacement.
• Rep[0-9]+MaxAge
  this can optionally be used together with RepReading to define a maximum age of the reading. It is specified as seconds:replacement. If the corresponding reading has not been updated for the specified number of seconds, then the replacement is used instead of the reading to do the replacement and further RepExpr or RepFormat attributes will be ignored for this value
  If you specify the replacement as {expr} then it is evaluated as a perl expression instead of a string.
  
• Rep[0-9]+MinValue
  this can optionally be used together with RepReading to define a minimum value of the reading. It is specified as min:replacement. If the corresponding reading is too small, then the replacement string is used instead of the reading to do the replacement and further RepExpr or RepFormat attributes will be ignored for this value
  If you specify the replacement as {expr} then it is evaluated as a perl expression instead of a string.
  
• Rep[0-9]+MaxValue
  this can optionally be used together with RepReading to define a maximum value of the reading. It is specified as max:replacement. If the corresponding reading is too big, then the replacement string is used instead of the reading to do the replacement and further RepExpr or RepFormat attributes will be ignored for this value
  If you specify the replacement as {expr} then it is evaluated as a perl expression instead of a string.
  
• Rep[0-9]+Expr
  defines an optional expression that can be used to compute the replacement value. If RepExpr is used together with RepReading then the expression is evaluated after getting the reading and the value of the reading can be used in the expression as $replacement.
  If only RepExpr is specified then readings can be retrieved with the perl function ReadingsVal() inside the expression.
  If neither RepExpr nor RepReading is specified then the match for the correspondig regex will be replaced with an empty string.
• Rep[0-9]+Format
  defines an optional format string to be used in a sprintf statement to format the replacement before it is applied.
  Can be used with RepReading or RepExpr or both.
• Rep[0-9]+SVG
  defines a SVG Plot be used as replacement. It is specified as the name of a defined fhem SVG.
  In order to include this in a SVG template, include e.g. a group in the template with a rect in it and then replace the rect with the SVG Plot data.
• Rep[0-9]+Comment
  can be used to put comments in the configuration
• LUTimeFormat
  defines a time format string (see Posix strftime format) to be used when creating the reading LastUpdate.
• PostCommand
  Execute an external command after writing the output file, e.g. to convert a resulting SVG file to a PNG file. For an eInk Kindle you need a PNG in 8 bit greyscale format. A simple example to call the convert utility from ImageMagick would be
  attr fr PostCommand convert /opt/fhem/www/images/status.svg -type GrayScale -depth 8 /opt/fhem/www/images/status.png 2>/dev/null &
  a more advanced example that starts inkscape before Imagemagick to make sure that embedded Icons in a SVG file are converted correctly could be
  attr fr PostCommand bash -c 'inkscape /opt/fhem/www/images/status.svg -e=tmp.png;; convert tmp.png -type GrayScale -depth 8 /opt/fhem/www/images/status.png' >/dev/null 2>&1 &
  or even
  attr fr PostCommand bash -c 'inkscape /opt/fhem/www/images/status.svg -e=tmp.png -b=rgb\(255,255,255\) --export-height=1024 --export-width=758;; convert tmp.png -type GrayScale -depth 8 /opt/fhem/www/images/status.png' >/dev/null 2>&1 &
  Inkscape might be needed because ImageMagick seems to have problems convertig SVG files with embedded icons. However a PNG file created by Inkscape is not in 8 bit greyscale so Imagemagick can be run after Inkscape to convert to 8 bit greyscale
• ReplacementEncode
  defines an encoding to apply to the replacement string, e.g. UTF-8
• disable
  disables the update timer
• regexDecode
  defines an encoding to be used in a call to the perl function decode to convert the raw data string from regex attributes before further processing / matching
  If you have trouble matching special characters or if you need to get around a memory leak in Perl regex processing this might help
  
• regexCompile
  defines that regular expressions will be precompiled when they are used for the first time and then stored internally so that subsequent uses of the same regular expression will be faster. This option is turned on by default but setting this attribute to 0 will disable it.

FS10

The FS10 module decrypts and sends FS10 messages, which are processed by the SIGNALduino. The following types are supported at the moment: FS10-ST, FS10-DI, FS10-HD, FS10-SA, FS10-MS, FS10-S4 and FS10-S8.

Define
define <name> FS10 <hauscode>_<button>

<name> is any name that is assigned to the device. For a better overview it is recommended to use a name in the form "FS10_6_12", where "6" is the used house code and "12" is the address of the button.

<hauscode> corresponds to the house code of the remote control or the device to be controlled. The house code is 1-8.

<button> represents the keyboard level or address of the devices used. Address "11" corresponds to the two buttons at the top row of remote control FS10-S8.


Set
set <name> <value> [<anz>]

<value> can be one of the following values::

• dimdown
• dimup
• off
• on
With dimup and dimdown, optionally with <anz> the number of repetitions can be specified in the range from 1 to 9.

The set extensions are supported.


Attribute
• IODev
• do_not_notify
• eventMap
• follow-on-for-timer (enable/disable follow-on-timer)
• follow-on-timer (Number of seconds after the timer of the FS10_SA the state automatically goes back to off.)
• ignore
• model (Model type of the device)
• FS10_ST: Switch socket
• FS10_DI: Socket dimmer
• FS10_HD: Ceiling lighting dimmer
• FS10_SA: Surface-mounted radio switch
• FS10_MS: Awning control
• FS10_S4: Remote control 4 buttons
• FS10_S8: Remote control 8 buttons
• readingFnAttributes
• repetition (Number of repetitions of the send commands)

FS20

The FS20 protocol is used by a wide range of devices, which are either of the sender/sensor category or the receiver/actuator category. The radio (868.35 MHz) messages are either received through an FHZ or an CUL device, so this must be defined first.

Define
define <name> FS20 <housecode> <button> [fg <fgaddr>] [lm <lmaddr>] [gm FF]

The values of housecode, button, fg, lm, and gm can be either defined as hexadecimal value or as ELV-like "quad-decimal" value with digits 1-4. We will reference this ELV-like notation as ELV4 later in this document. You may even mix both hexadecimal and ELV4 notations, because FHEM can detect the used notation automatically by counting the digits.

• <housecode> is a 4 digit hex or 8 digit ELV4 number, corresponding to the housecode address.
• <button> is a 2 digit hex or 4 digit ELV4 number, corresponding to a button of the transmitter.
• The optional <fgaddr> specifies the function group. It is a 2 digit hex or 4 digit ELV address. The first digit of the hex address must be F or the first 2 digits of the ELV4 address must be 44.
• The optional <lmaddr> specifies the local master. It is a 2 digit hex or 4 digit ELV address. The last digit of the hex address must be F or the last 2 digits of the ELV4 address must be 44.
• The optional gm specifies the global master, the address must be FF if defined as hex value or 4444 if defined as ELV4 value.

Examples:
define lamp FS20 7777 00 fg F1 gm F
define roll1 FS20 7777 01
define otherlamp FS20 24242424 1111 fg 4412 gm 4444
define otherroll1 FS20 24242424 1114

Set
set <name> <value> [<time>]

where value is one of:

dim06% dim12% dim18% dim25% dim31% dim37% dim43% dim50%
dim56% dim62% dim68% dim75% dim81% dim87% dim93% dim100%
dimdown
dimup
dimupdown
off
off-for-timer
on # dimmer: set to value before switching it off
on-for-timer # see the note
on-old-for-timer # set to previous (before switching it on)
ramp-on-time # time to reach the desired dim value on dimmers
ramp-off-time # time to reach the off state on dimmers
reset
sendstate
timer
toggle # between off and previous dim val

The set extensions are also supported.

Examples:
set lamp on
set lamp1,lamp2,lamp3 on
set lamp1-lamp3 on
set lamp on-for-timer 12


Notes:
• Use reset with care: the device forgets even the housecode.
• As the FS20 protocol needs about 0.22 seconds to transmit a sequence, a pause of 0.22 seconds is inserted after each command.
• The FS20ST switches on for dim*%, dimup. It does not respond to sendstate.
• If the timer is set (i.e. it is not 0) then on, dim*, and *-for-timer will take it into account (at least by the FS20ST).
• The time argument ranges from 0.25sec to 4 hours and 16 minutes. As the time is encoded in one byte there are only 112 distinct values, the resolution gets coarse with larger values. The program will report the used timeout if the specified one cannot be set exactly. The resolution is 0.25 sec from 0 to 4 sec, 0.5 sec from 4 to 8 sec, 1 sec from 8 to 16 sec and so on. If you need better precision for large values, use at which has a 1 sec resolution.

Get
N/A

Attributes
• IODev
  Set the IO or physical device which should be used for sending signals for this "logical" device. An example for the physical device is an FHZ or a CUL. Note: Upon startup FHEM assigns each logical device (FS20/HMS/KS300/etc) the last physical device which can receive data for this type of device. The attribute IODev needs to be used only if you attached more than one physical device capable of receiving signals for this logical device.


• eventMap
  Replace event names and set arguments. The value of this attribute consists of a list of space separated values, each value is a colon separated pair. The first part specifies the "old" value, the second the new/desired value. If the first character is slash(/) or komma(,) then split not by space but by this character, enabling to embed spaces. Examples:
  attr store eventMap on:open off:closed
attr store eventMap /on-for-timer 10:open/off:closed/
set store open


• dummy
  Set the device attribute dummy to define devices which should not output any radio signals. Associated notifys will be executed if the signal is received. Used e.g. to react to a code from a sender, but it will not emit radio signal if triggered in the web frontend.


• follow-on-for-timer
  schedule a "setstate off;trigger off" for the time specified as argument to the on-for-timer command. Or the same with on, if the command is off-for-timer.


• follow-on-timer
  Like with follow-on-for-timer schedule a "setstate off;trigger off", but this time for the time specified as argument in seconds to this attribute. This is used to follow the pre-programmed timer, which was set previously with the timer command or manually by pressing the button on the device, see your manual for details. Works for on and dim commands.


• model
  The model attribute denotes the model type of the device. The attributes will (currently) not be used by the fhem.pl directly. It can be used by e.g. external programs or web interfaces to distinguish classes of devices and send the appropriate commands (e.g. "on" or "off" to a fs20st, "dim..%" to fs20du etc.). The spelling of the model names are as quoted on the printed documentation which comes which each device. This name is used without blanks in all lower-case letters. Valid characters should be a-z 0-9 and - (dash), other characters should be ommited. Here is a list of "official" devices:
  
  Sender/Sensor: fs20fms fs20hgs fs20irl fs20kse fs20ls fs20pira fs20piri fs20piru fs20s16 fs20s20 fs20s4 fs20s4a fs20s4m fs20s4u fs20s4ub fs20s8 fs20s8m fs20sd fs20sn fs20sr fs20ss fs20str fs20tc1 fs20tc6 fs20tfk fs20tk fs20uts fs20ze fs20bf fs20si3
  
  Dimmer: fs20di fs20di10 fs20du
  
  Receiver/Actor: fs20as1 fs20as4 fs20ms2 fs20rgbsa fs20rst fs20rsu fs20sa fs20sig fs20sm4 fs20sm8 fs20st fs20su fs20sv fs20ue1 fs20usr fs20ws1


• ignore
  Ignore this device, e.g. if it belongs to your neighbour. The device won't trigger any FileLogs/notifys, issued commands will silently ignored (no RF signal will be sent out, just like for the dummy attribute). The device won't appear in the list command (only if it is explicitely asked for it), nor will it appear in commands which use some wildcard/attribute as name specifiers (see devspec). You still get them with the "ignored=1" special devspec.


• do_not_notify
• showtime
• readingFnAttributes
• useSetExtensions
  Setting it to 0 you can disable using the Setextensions. Deffault is 1.



Generated events:
From an FS20 device you can receive one of the following events.
• on
• off
• toggle
• dimdown
• dimup
• dimupdown
• on-for-timer
Which event is sent is device dependent and can sometimes configured on the device.

FTUISRV

Provides a mini HTTP server plugin for FHEMWEB for the specific use with FTUI. It serves files from a given directory and parses them according to specific rules. The goal is to be able to create reusable elements of multiple widgets and surrounding tags on multiple pages and even with different devices or other modifications. Therefore changes to the design have to be done only at one place and not at every occurence of the template (called parts in this doc). FTUISRV is an extension to FHEMWEB and code is based on HTTPSRV. You must install FHEMWEB to use FTUISRV.
FTUISRV is able to handled includes and replacements in files before sending the result back to the client (Browser). Special handling of files is ONLY done if the filenames include the specific pattern ".ftui." in the filename. For example a file named "test.ftui.html" would be handled specifically in FTUISRV.

FTUI files can contain the following elements


• <?ftui-inc="name" varname1="content1" ... varnameN="contentN" ?>
  INCLUDE statement: Including other files that will be embedded in the result at the place of the include statement. Additionally in the embedded files the variables listed as varnamex will be replaced by the content enclosed in double quotes (").
  The quotation marks and the spaces between the variable replacements and before the final ? are significant and can not be ommitted.
  Example: <?ftui-inc="temphum-inline.ftui.part" thdev="sensorWZ" thformat="top-space-2x" thtemp="measured-temp" ?>


• <?ftui-if=( expression ) ?> ... [ <?ftui-else ?> ... ] <?ftui-endif ?>
  IF statement: Allow the inclusion of a block depending on an expression that might again include also variables and expressions in fhem. The else block is optional and can contain a block that is included if the expression is empty or 0 .
  Example: <?ftui-if=( [tempdevice:batteryok] ) ?> ... <?ftui-else ?> ... <?ftui-endif ?>
  Note: The expression is not automatically evaluated in perl, if this is needed there should be the set-logic for perl expressions being used Example: <?ftui-if=( {( ReadingsVal("tempdevice","batteryok","") eq "ok" )} ) ?> ... <?ftui-else ?> ... <?ftui-endif ?>


• <?ftui-loopinc="name" loopvariable=( loop-expression ) varname1="content1" ... varnameN="contentN" ?>
  LOOP-INCLUDE statement: Including other files that will be embedded in the result at the place of the include statement. The include will be executed once for every entry (line) that is returned when evaluating the loop-expression as an fhem command. So the loop expression could be a list command returning multiple devices
  The quotation marks and the spaces between the variable replacements and before the final ? are significant and can not be ommitted.
  Example: <?ftui-loopinc="temphum-inline.ftui.part" thdev=( list TYPE=CUL_TX ) thformat="top-space-2x" thtemp="measured-temp" ?>


• <?ftui-key=varname ?>
  VARIABLE specification: Replacement of variables with given parameters in the include statement (or the include header). The text specified for the corresponding variable will be inserted at the place of the FTUI-Statement in parentheses. There will be no space or other padding added before or after the replacement, the replacement will be done exactly as specified in the definition in the include
  Example: <?ftui-key=measured-temp ?>


• <?ftui-header="include name" varname1[="defaultcontent1"] .. varnameN[="defaultcontentN"] ?>
  HEADER definition: Optional header for included files that can be used also to specify which variables are used in the include file and optionally specify default content for the variables that will be used if no content is specified in the include statement. the header is removed from the output given by FTUISRV. Headers are only required if default values should be specified and are helpful in showing the necessary variable names easy for users. (The name for the include does not need to be matching the file name)
  Example: <?ftui-header="TempHum inline" thdev thformat thtemp="temperature" ?> Headers can also use device readings in for setting default values in the form of [device:reading](according to the syntax and logic used in the set command)
  Example: <?ftui-header="TempHum inline" thdev thformat thbattery=[temphm:batteryok] thtemp="temperature" ?>
  In the special case, where also variable content shall be used in the header part a special escaping for the closing tags for the ftui-key needs to be used. That means for the example above: Example: <?ftui-header="TempHum inline" thdev thformat thbattery=[:batteryok] thtemp="temperature" ?>




Define
define <name> <infix> <directory> <friendlyname>

Defines the HTTP server. <infix> is the portion behind the FHEMWEB base URL (usually http://hostname:8083/fhem), <directory> is the absolute path the files are served from, and <friendlyname> is the name displayed in the side menu of FHEMWEB.




Set
n/a


Attributes


• validateFiles <0,1,2>
  Allows basic validation of HTML/Part files on correct opening/closing tags etc. Here the original files from disk are validated (setting to 1 means validation is done / 2 means also the full parsing is logged (Attention very verbose !)
• validateResult <0,1,2>
  Allows basic validation of HTML content on correct opening/closing tags etc. Here the resulting content provided to the browser (after parsing) are validated (setting to 1 means validation is done / 2 means also the full parsing is logged (Attention very verbose !)
• templateFiles <relative paths separated by :>
  specify specific files / urls to be handled as templates even if not containing the ftui in the filename. Multiple files can be separated by colon.

FULLY

Module for controlling of Fully browser on Android tablets. Requires a Plus license of Fully browser app. Remote device management and remote admin in local network must be enabled in Fully app. Requires Fully app version 1.27 or later.

Define


define <name> FULLY [<Protocol>://]<HostOrIP>[:<Port>] [<password>] [<poll-interval>]

The parameter password is the password set in Fully browser. Parameter Protocol is optional. Valid protocols are 'http' and 'https'. Default protocol is 'http'. Default Port is 2323.
The password is optional. If you don't want the password to appear in the device definition, set the password by using command 'set authentication'.

Set


• set <name> authentication [<password>]
  Set Fully password. This password is used for each Fully opteration. If no password is specified, the current password is deleted.


• set <name> brightness 0-255
  Adjust screen brightness.


• set <name> clearCache
  Clear browser cache.


• set <name> clearCookies
  Clear cookies.


• set <name> clearWebstorage
  Clear web storage.


• set <name> exit
  Terminate Fully.


• set <name> foreground
  Bring fully app to foreground.


• set <name> lockKiosk
  Lock kiosk mode.


• set <name> motionDetection { on | off }
  Turn motion detection by camera on or off.


• set <name> { lock | unlock }
  Lock or unlock display.


• set <name> { on | off }
  Turn tablet display on or off.


• set <name> on-for-timer [{ <Seconds> | forever | off }]
  Set timer for display. Default is forever.


• set <name> overlayMessage { text }
  Show overlay message. Placeholders in format [device:reading] are supported and will be substituted by the corresponding reading value.


• set <name> photo
  Take a picture with device cam. Setting motion detection must be enabled. Picture can be viewed in remote admin interface under device info.


• set <name> playSound <url> [loop]
  Play sound from URL.


• set <name> playVideo <url> [loop] [showControls] [exitOnTouch] [exitOnCompletion]
  Play video from URL.


• set <name> restart
  Restart Fully.


• set <name> screenOffTimer <seconds>
  Turn screen off after some idle seconds, set to 0 to disable timer.


• set <name> screenSaver { start | stop }
  Start or stop screen saver. Screen saver URL can be set with command set screenSaverURL.


• set <name> screenSaverTimer <seconds>
  Show screen saver URL after some idle seconds, set to 0 to disable timer.


• set <name> screenSaverURL <URL>
  Show this URL when screensaver starts, set daydream: for Android daydream or dim: for black.
  


• set <name> setBooleanSetting <Key> <Value>
  Set boolean value in Fully app. Command is ony available if attribute expert is 1. Valid keys can be found in Fully remote admin interface.


• set <name> setStringSetting <Key> <Value>
  Set string value in Fully app. Command is ony available if attribute expert is 1. Valid keys can be found in Fully remote admin interface.


• set <name> speak <text>
  Audio output of text. If text contains blanks it must be enclosed in double quotes. The text can contain device readings in format [device:reading].


• set <name> startApp <PackageName>
  Start an app. App must be installed on the tablet and package name (not appname!) must be specified.


• set <name> startURL <URL>
  Show this URL when FULLY starts.
  


• set <name> stopSound
  Stop playback of sound if playback has been started with option loop.


• set <name> stopVideo
  Stop playback of video if playback has been started with option loop.


• set <name> unlockKiosk
  Unlock kiosk mode.


• set <name> url [<URL>]
  Navigate to URL. If no URL is specified navigate to start URL.


• set <name> volume <level> <stream>
  Set audio volume. Range of parameter level is 0-100, range of parameter stream is 1-10.



Get


• get <name> info
  Display Fully information. This is command blocks FHEM until completion.


• get <name> stats
  Show Fully statistics. Will be implemented later.


• get <name> update
  Update readings.



Attributes


• disable <0 | 1>
  Disable device and automatic polling.


• expert <0 | 1>
  Activate expert mode.


• pingBeforeCmd <Count>
  Send Count ping request to tablet before executing commands. Valid values for Count are 0,1,2. Default is 0 (do not send ping request).


• pollInterval <seconds>
  Set polling interval for FULLY device information. If seconds is 0 polling is turned off. Valid values are from 10 to 86400 seconds.


• repeatCommand <Count>
  Repeat fully command on failure. Valid values for Count are 0,1,2. Default is 0 (do not repeat commands).


• requestTimeout <seconds>
  Set timeout for http requests. Default is 5 seconds. Increase this value if commands are failing with a timeout error.


• updateAfterCommand <0 | 1>
  When set to 1 update readings after a set command. Default is 0.


• waitAfterPing <Seconds>
  Wait specified amount of time after sending ping request to tablet device. Valid values for Seconds are 0,1,2. Default is 0 (do not wait). Only used if attribute pingBeforeCmd is greater than 0.

FhemTestUtils

An instance of this module will be automatically defined, if fhem.pl is called with the -t option. The module will collect all events and Log messages, so a test program is able to check, if an event or log message was generated.
Available functions:
• FhemTestUtils_gotEvent($)
  Return the events matching the regexp argument (with grep).
• FhemTestUtils_gotLog($)
  Return the logs matching the regexp argument (with grep). Note, that loglevel filtering with verbose ist still active.
• FhemTestUtils_getLogTime($)
  Return the timestamp of the first log matching the argument.
• FhemTestUtils_resetEvents()
  Reset the internal event buffer.
• FhemTestUtils_resetLogs()
  Reset the internal log buffer.


Define
define <name> FhemTestUtils

Set
N/A

Get
N/A

Attributes
N/A

FileLog

Define
define <name> FileLog <filename> <regexp> [readonly]

Log events to <filename>. The log format is

YYYY-MM-DD_HH:MM:SS <device> <event>


The regexp will be checked against the device name devicename:event or timestamp:devicename:event combination. The regexp must match the complete string, not just a part of it.
<filename> may contain %-wildcards of the POSIX strftime function of the underlying OS (see your strftime manual). Common used wildcards are:
• %d day of month (01..31)
• %m month (01..12)
• %Y year (1970...)
• %w day of week (0..6); 0 represents Sunday
• %j day of year (001..366)
• %U week number of year with Sunday as first day of week (00..53)
• %W week number of year with Monday as first day of week (00..53)
FHEM also replaces %L by the value of the global logdir attribute.
Before using %V for ISO 8601 week numbers check if it is correctly supported by your system (%V may not be replaced, replaced by an empty string or by an incorrect ISO-8601 week number, especially at the beginning of the year) If you use %V you will also have to use %G instead of %Y for the year!
If readonly is specified, then the file is used only for visualisation, and it is not opened for writing. Examples:
define lamplog FileLog %L/lamp.log lamp
define wzlog FileLog ./log/wz-%Y-%U.log wz:(measured-temp|actuator).*
With ISO 8601 week numbers, if supported:
define wzlog FileLog ./log/wz-%G-%V.log wz:(measured-temp|actuator).*



Set
• reopen
  Reopen a FileLog after making some manual changes to the logfile.
• clear
  Clears and reopens the logfile.
• addRegexpPart <device> <regexp>
  add a regexp part, which is constructed as device:regexp. The parts are separated by |. Note: as the regexp parts are resorted, manually constructed regexps may become invalid.
• removeRegexpPart <re>
  remove a regexp part. Note: as the regexp parts are resorted, manually constructed regexps may become invalid.
  The inconsistency in addRegexpPart/removeRegexPart arguments originates from the reusage of javascript functions.
• absorb secondFileLog
  merge the current and secondFileLog into one file, add the regexp of the secondFileLog to the current one, and delete secondFileLog.
  This command is needed to create combined plots (weblinks).
  Notes:
  • secondFileLog will be deleted (i.e. the FHEM definition).
  • only the current files will be merged.
  • weblinks using secondFilelog will become broken, they have to be adopted to the new logfile or deleted.



Get
get <name> <infile> <outfile> <from> <to> <column_spec>

Read data from the logfile, used by frontends to plot data without direct access to the file.

• <infile>
  Name of the logfile to open. Special case: "-" is the currently active logfile, "CURRENT" opens the file corresponding to the "from" parameter.
• <outfile>
  If it is "-", you get the data back on the current connection, else it is the prefix for the output file. If more than one file is specified, the data is separated by a comment line for "-", else it is written in separate files, numerated from 0.
• <from> <to>
  Used to grep the data. The elements should correspond to the timeformat or be an initial substring of it.
• <column_spec>
  For each column_spec return a set of data in a separate file or separated by a comment line on the current connection.
  Syntax: <col>:<regexp>:<default>:<fn>
  
  • <col> The column number to return, starting at 1 with the date. If the column is enclosed in double quotes, then it is a fix text, not a column number.
  • <regexp> If present, return only lines containing the regexp. Case sensitive.
  • <default>
    If no values were found and the default value is set, then return one line containing the from value and this default. We need this feature as gnuplot aborts if a dataset has no value at all.
  • <fn> One of the following:
    • int
      Extract the integer at the beginning og the string. Used e.g. for constructs like 10%
    • delta-h or delta-d
      Return the delta of the values for a given hour or a given day. Used if the column contains a counter, as is the case for the KS300 rain column.
    • everything else
      The string is evaluated as a perl expression. @fld is the current line splitted by spaces. Note: The string/perl expression cannot contain spaces, as the part after the space will be considered as the next column_spec.


Example:

get outlog out-2008.log - 2008-01-01 2008-01-08 4:IR:int: 9:IR::


Attributes
• addStateEvent



• acceptedRange col1:min:max[:regexp] ...
  This attribute takes a space separated list of ranges. An event wont be logged, if the column of the event (counted from 0) is a number, and it is outside of the specified range. The optional regexp will check the event only, without the usual ^ and $ added to it. Example:
  attr fl acceptedRange 1:5:35:[Tt]emperature 1:-90:-40:RSSI


• addLog
  This attribute takes a comma-separated list of devspec:reading:maxInterval triples. The value for reading is treated as a regular expression. The last value of the reading will be written to the logfile, when after maxInterval seconds no event for this device/reading has arrived.


• archivecmd / archivedir / nrarchive
  When a new FileLog file is opened, the FileLog archiver wil be called. This happens only, if the name of the logfile has changed (due to time-specific wildcards, see the FileLog section), and there is a new entry to be written into the file.
  If the attribute archivecmd is specified, then it will be started as a shell command (no enclosing " is needed), and each % in the command will be replaced with the name of the old logfile.
  If this attribute is not set, but nrarchive is set, then nrarchive old logfiles are kept along the current one while older ones are moved to archivedir (or deleted if archivedir is not set).
  Note: "old" means here the first ones in the alphabetically soreted list.
  Note: setting these attributes for the global instance will effect the FHEM logfile only.


• archiveCompress
  If nrarchive, archivedir and archiveCompress is set, then the files in the archivedir will be compressed.


• createGluedFile
  If set (to 1), and the SVG-Plot requests a time-range wich is stored in multiple files, a temporary file with the content of all files will be created, in order to satisfy the request. Note: this may be slow.


• disable
• disabledForIntervals


• eventOnThreshold
  If set (to a nonzero number), the event linesInTheFile will be generated, if the lines in the file is a multiple of the set number. Note: the counter is only correct for files created after this feature was implemented. A FHEM crash or kill will falsify the counter.


• filelog-event-min-interval
  This attribute takes a comma-separated list of devspec:reading:minInterval triples. You may use regular expressions for reading. The data will only be written, if at least minInterval seconds elapsed since the last event of the matched type. Note: only readings existing at the time the attribute is set will be considered.


• ignoreRegexp
• label
  
• logtype
  Used by FHEMWEB to offer gnuplot/SVG images made from the logs. The string is made up of tokens separated by comma (,), each token specifies a different configuration. The token may contain a colon (:), the part before the colon defines the name of the program, the part after is the string displayed in the web frontend.
  Example:
  attr ks300log1 logtype temp4rain10:Temp/Rain,hum6wind8:Hum/Wind,text:Raw-data
  If the special value "text:linesInTheFile" is used, you will see the number of lines in each Logfile in the corrsponding device overview.
  


• mseclog


• outputFormat <perlCode>
  If set, the result of the evaluated perlCode will be written to the file. Default is "$TIMESTAMP $NAME $EVENT\n".
  Note: only this format ist compatible with the SVG Editor


• reformatFn <perlFunctionName>
  used to convert "foreign" logfiles for the SVG Module, contains the name(!) of a function, which will be called with a "raw" line from the original file, and has to return a line in "FileLog" format.
  E.g. to visualize the NTP loopstats, set reformatFn to ntpLoopstats, and copy the following into your 99_myUtils.pm:

  
        sub            
        ntpLoopstats($)
        {
          my ($d) = @_;
          return $d if($d !~ m/^(\d{5}) (\d+)\.(\d{3}) (.*)$/);
          my ($r, $t) = ($4, FmtDateTime(($1-40587)*86400+$2));
          $t =~ s/ /_/;
          return "$t ntpLoopStats $r";
        }

GAEBUS

The GAEBUS module is the representation of a Ebus connector in FHEM. The GAEBUS module is designed to connect to ebusd (ebus daemon) via a socket connection (default is port 8888)

Define
define <name> GAEBUS <device-addr>[:<port>] [<interval>];

<device-addr>[:<port>] specifies the host:port of the ebusd device. E.g. 192.168.0.244:8888 or servername:8888. When using the standard port, the port can be omitted.

Example:

define ebus1 GAEBUS localhost 300

When initializing the object no device specific commands are known. Please call "get ebusd_find" to read in supported commands from ebusd.
After fresh restart of ebusd it may take a while until all supported devices and their commands are visible.


Set
• reopen
  Will close and open the socket connection.


• [r]_<class> <variable-name>_<comment>
  Will define a attribute with the following syntax:
  [r]_<class>_<variable-name>
  Valid combinations are read from ebusd (using "get ebusd_find") and are selectable.
  Values from the attributes will be used as the name for the reading which are read from ebusd in the interval specified.
  The content of <comment$gt; is dropped and not added to the attribute name.
  


• [w]_<class> <variable-name>_<comment>
  Will define a attribute with the following syntax:
  [w]_<class>_<variable-name>
  They will only appear if the attribute "ebusWritesEnabled" is set to "1"
  Valid combinations are read from ebusd (using "get ebusd_find") and are selectable.
  Values from the attributes will be used for set commands to modify parameters for ebus devices
  Hint: if the values for the attributes are prefixed by "set-" then all possible parameters will be listed in one block
  The content of <comment$gt; is dropped and not added to the attribute name.
  


Get
• ebusd_info
  Execude info command on ebusd and show result.


• ebusd_find
  Execude find command on ebusd. Result will be used to display supported "set" and "get" commands. Refresh the page in your Browser to make results visible.


• ebusd_hex
  Will pass the input value to the "hex" command of ebusd. See "ebusctl help hex" for valid parameters.
  This command is only available if "ebusWritesEnabled" is set to '1'.
  


• reading <reading-name>
  Will read the actual value form ebusd and update the reading.


• [r]_<class> <variable-name>_<comment>
  Will read this variable from the ebusd and show the result as a popup.
  Valid combinations are read from ebusd (using "get ebusd_find") and are selectable.
  



Attributes
• do_not_notify


• disable


• dummy


• showtime


• verbose


• ebusWritesEnabled 0,1
  disable (0) or enable (1) that commands can be send to ebus devices
  See also description for Set and Get
  If Attribute is missing, default value is 0 (disable writes)
  


• mapClass
  used to support "_" in class names. Set by ebusd_find.


• mapVar
  used to support "_" in variable names. Set by ebusd_find.


• Attributes of the format
  [r]_<class>_<variable-name>
  define variables that can be retrieved from the ebusd. They will appear when they are defined by a "set" command as described above.
  The value assigned to an attribute specifies the name of the reading for this variable.
  If ebusd returns a list of semicolon separated values then several semicolon separated readings can be defined.
  "dummy" is a placeholder for a reading that will be ignored. (e.g.: temperature;dummy;pressure).
  The name of the reading can be suffixed by "<:number>" which is a multiplicator for the evaluation within the specified interval. (eg. OutsideTemp:3 will evaluate this reading every 3-th cycle)
  All text followed the reading seperated by a blank is given as an additional parameter to ebusd. This can be used to request a single value if more than one is retrieved from ebus.
  If "+f" is given as an additional parameter this will remove the "-f" option from the ebusd request. This will return the value stored in ebusd instead of requesting it freshly.
  


• Attributes of the format
  [w]_<class>_<variable-name>
  define parameters that can be changed on ebus devices (using the write command from ebusctl) They will appear when they are defined by a "set" command as described above.
  The value assigned to an attribute specifies the name that will be used in set to change a parameter for a ebus device.
  


• valueFormat
  Defines a map to format values within GAEBUS.
  All readings can be formated using syntax of sprinf. Values returned from ebusd are spearated by ";" and split before valueFormat is processed. This means more than one of the return values can be assigned to one reading.
  Example: { "temperature" => "%0.2f"; "from-to" => "%s-%s" }
  

GEOFANCY

• Provides a webhook receiver for geofencing, e.g. via the following apps:
  
  
• Geofency (iOS)
• Locative (iOS)
• EgiGeoZone (Android)
• SMART Geofences (Windows 10, Windows 10 Mobile)

• Note: GEOFANCY is an extension to FHEMWEB. You need to install FHEMWEB to use GEOFANCY.

  Define
  define <name> GEOFANCY <infix>
  
  Defines the webhook server. <infix> is the portion behind the FHEMWEB base URL (usually http://hostname:8083/fhem)
  
  Example:
  define geofancy GEOFANCY geo
  
  
  The webhook will be reachable at http://hostname:8083/fhem/geo in that case.
  
  
  Set
  • clear   readings   can be used to cleanup auto-created readings from deprecated devices.
  
  
  Attributes
  
  
  • devAlias: Mandatory attribute to assign device name alias to an UUID in the format DEVICEUUID:Aliasname (most readings will only be created if devAlias was defined).
    Separate using blank to rename multiple device UUIDs.
    
    Should you be using GEOFANCY together with ROOMMATE or GUEST you might consider using attribute r*_geofenceUUIDs directly at those devices instead.
  
  
  Usage information / Hints on Security
  
  
  Likely your FHEM installation is not reachable directly from the internet (good idea!).
  It is recommended to have a reverse proxy like HAproxy, Pound or Varnish in front of FHEM where you can make sure access is only possible to a specific URI like /fhem/geo. Apache or Nginx might do as well. However, in case you have Apache or Nginx running already you should still consider one of the named reverse proxies in front of it for fine-grain security configuration.
  
  You might also want to think about protecting the access by using HTTP Basic Authentication and encryption via TLS/SSL. Using TLS offloading in the reverse proxy software is highly recommended and software like HAproxy provides high control of data flow for TLS.
  
  Also the definition of a dedicated FHEMWEB instance for that purpose together with allowed might help to restrict FHEM's functionality (e.g. set attributes allowedCommands and allowedDevices to ",". Note that attributes hiddengroup and hiddenroom of FHEMWEB do NOT protect from just guessing/knowing the correct URI but would help tremendously to prevent easy inspection of your FHEM setup.)
  
  To make that reverse proxy available from the internet, just forward the appropriate port via your internet router.
  
  The actual solution on how you can securely make your GEOFANCY webhook available to the internet is not part of this documentation and depends on your own skills.
  
  
  Integration with Home Automation
  
  
  You might want to have a look to the module family of ROOMMATE, GUEST and RESIDENTS for an easy processing of GEOFANCY events.

GFPROBT

GFPROBT is used to control a G.F.Pro Bluetooth Eco Watering irrigation control


Required packages
sudo apt install libio-tty-perl bluez
sudo cpanm Expect DateTime

Note: GFPro LED must blink during define! Please check if gatttool executable is available on your system.

Define
define <name> GFPROBT <mac address>

Example:
Remove battery and insert it again
Check if LED is blinking
define watering GFPROBT 00:33:44:33:22:11


Set
set <name> <command> [<parameter>]
The following commands are defined:


• on   [seconds]   switch on watering, optional for X seconds
• off   -   switch off watering
• addTimer   duration=300 start=8:00 weekdays=Mo,Tu,We,Th,Fr,Sa,Su   add timer with duration in seconds, starttime and weekdays (default all weekdays)
• editTimer   timer=1 duration=300 start=8:00 weekdays=Mo,Fr   update timer 1 to duration, start, weekdays. Parameters not provided will remain unchanged
• deleteTimer   number or all   delete one, more or all timers
• adjust   percentage days   adjust percentage for x days
• devicename   name   set devicename


Get
n/a

GHoma

Connects fhem to an G-Homa adapter plug

preliminary:

• Configure WLAN settings (Firmware <= 1.06):
  bring device in AP mode (press button for more than 3s, repeat this step until the LED is permanently on)
  Now connect with your computer to G-Home network.
  Browse to 10.10.100.254 (username:password = admin:admin)
  In STA Setting insert your WLAN settings
  
• Configure WLAN settings:
  bring device in AP mode (press button for more than 3s, repeat this step until the LED is permanently on)
  Configure WLAN with G-Homa App.
  
• Configure Network Parameters setting (Firmware <= 1.06):
  Other Setting -> Protocol to TCP-Client
  Other Setting -> Port ID (remember value for FHEM settings)
  Other Setting -> Server Address (IP of your FHEM Server)
  
• Configure Network Parameters settings:
  Use set ... ConfigAll from server device to set parameters automaticly.
  
• Optional:
  Block all outgoing connections for G-Homa in your router.
  


Define

define <name> GHoma <port>
Specifies the GHoma server device.
New adapters will be added automaticaly after first connection.
You can also manyally add an adapter:
define <name> GHoma <Id>
where Id is the last 6 numbers of the plug's MAC address
Example: MAC= AC:CF:23:A5:E2:3B -> Id= A5E23B


Set
set <name> <value>

where value is one of:

off
on

The set extensions are also supported.

For server device:
set <name> ConfigAll [IP|hostname|FQDN of FHEM]
Setting all GHoma plugs via UDP broadcast to TCP client of FHEM servers address and port of GHoma server device.
set <name> ConfigSingle <IP of Plug> [IP|hostname|FQDN of FHEM]
Setting an specific GHoma plug via UDP to TCP client of FHEM servers address and port of GHoma server device.

Attributes

For plug devices:
• restoreOnStartup
  Restore switch state after reboot
  Default: last, valid values: last, on, off
  
  
• restoreOnReinit
  Restore switch state after reconnect
  Default: last, valid values: last, on, off
  
  
• blocklocal
  Restore switch state to reading state immideately after local switching
  Default: no, valid values: no, yes
  
  
For server devices:
• allowfrom
  Regexp of allowed ip-addresses or hostnames. If set, only connections from these addresses are allowed.
  
  
• readingFnAttributes

GOOGLECAST

GOOGLECAST is used to control your Google Cast device

Note
Make sure that python3 is installed. Following packages are required:
• sudo apt-get install libwww-perl python-enum34 python-dev libextutils-makemaker-cpanfile-perl python3-pip cpanminus
• sudo pip3 install pychromecast --upgrade
• sudo pip3 install youtube-dl --upgrade
• sudo INLINE_PYTHON_EXECUTABLE=/usr/bin/python3 cpanm Inline::Python


Define
define <name> GOOGLECAST <name>

Example:
define livingroom.chromecast GOOGLECAST livingroom

Wait a few seconds till presence switches to online...

set livingroom.chromecast play https://www.youtube.com/watch?v=YE7VzlLtp-4


Following media types are supported:
Supported media formats
Play with youtube-dl works for following URLs:
Supported youtube-dl sites



Set
set <name> <command> [<parameter>]
The following commands are defined:


• play URL   -   play from URL
• play   -   play, like resume if paused previsously
• playFavorite   -   plays URL from favoriteURL_[1-5]
• stop   -   stop, stops current playback
• pause   -   pause
• quitApp   -   quit current application, like YouTube
• skip   -   skip track and play next
• rewind   -   rewind track and play it again
• displayWebsite   -   displayWebsite on Chromecast Video


Attributes
• favoriteURL_[1-5]   -   save URL to play afterwards with playFavorite [1-5]

Get
n/a

GSI

GSI shows the share of renewable energies in the power grid for any location in Germany at the current time and a forecast for the next 24 hours. At the same time, Co2 emissions for generation are displayed. Co2 values for the regular electricity mix and Co2 values for tariffs with 100% renewable energy are available.

In addition, based on the prediction of the electricity composition, the energy consumption can be planned for periods with a high proportion of renewable energies and thus low Co2 emissions.

The energy forecasts are provided by 'corrently', in cooperation with the network operators, based on the network topology and weather forecasts.

Define
define <name> GSI <zip>

defines the device for the given (german only) zip code.

Set
N/A

Get
N/A

Attributes
• cmdStateIcon
  preset to the function
  • {GSI::devStateIcon($name)}
  and can be advanced to
  • {GSI::devStateIcon($name,'other_valid_svg_icon_name')}
  The icon will be colored based on share of renewable energy (GSI) available:
  • 0..39: black
  • 40..59: orange
  • 60..100: green
• continuous
  if set to 0 readings will be updated on hourly base. Otherwise readings will be continuously updated with interpolated values.

Consumption schedule
The prediction (forecast) can be used to automatically control electrical consumers based in the amount of renewable energy expected:

• define name at {GSI::greenPower('name_of_gsi_device',2,18)} set consumer on-for-timer 720

This example requests the 2 consecutive hours with the highest share of renewable energy within the next 18 hours. This is used for the definition of an 'at' which switches on a consumer for 2 hours (720 seconds) at the best possible time.

GUEST

Define
define <rg_GuestName> GUEST [<device name(s) of resident group(s)>]

Provides a special virtual device to represent a guest of your home.
Based on the current state and other readings, you may trigger other actions within FHEM.

Used by superior module RESIDENTS but may also be used stand-alone.

Use comma separated list of resident device names for multi-membership (see example below).

Example:

# Standalone
define rg_Guest GUEST

# Typical group member
define rg_Guest GUEST rgr_Residents # to be member of resident group rgr_Residents

# Member of multiple groups
define rg_Guest GUEST rgr_Residents,rgr_Guests # to be member of resident group rgr_Residents and rgr_Guests


Set
set <rg_GuestName> <command> [<parameter>]

Currently, the following commands are defined.

• location   -   sets reading 'location'; see attribute rg_locations to adjust list shown in FHEMWEB
• mood   -   sets reading 'mood'; see attribute rg_moods to adjust list shown in FHEMWEB
• state   home,gotosleep,asleep,awoken,absent,none   switch between states; see attribute rg_states to adjust list shown in FHEMWEB
• create
• locationMap   add a pre-configured weblink device using showing a Google Map if readings locationLat+locationLong are present.
• wakeuptimer   add several pre-configurations provided by RESIDENTS Toolkit. See separate section in RESIDENTS module commandref for details.
Note: If you would like to restrict access to admin set-commands (-> create) you may set your FHEMWEB instance's attribute allowedCommands like 'set,set-user'. The string 'set-user' will ensure only non-admin set-commands can be executed when accessing FHEM using this FHEMWEB instance.



Possible states and their meaning


This module differs between 6 states:


• home - individual is present at home and awake
• gotosleep - individual is on it's way to bed
• asleep - individual is currently sleeping
• awoken - individual just woke up from sleep
• absent - individual is not present at home but will be back shortly
• none - guest device is disabled



Presence correlation to location


Under specific circumstances, changing state will automatically change reading 'location' as well.

Whenever presence state changes from 'absent' to 'present', the location is set to 'home'. If attribute rg_locationHome was defined, first location from it will be used as home location.

Whenever presence state changes from 'present' to 'absent', the location is set to 'underway'. If attribute rg_locationUnderway was defined, first location from it will be used as underway location.



Auto Gone


Whenever an individual is set to 'absent', a trigger is started to automatically change state to 'gone' after a specific timeframe.
Default value is 16 hours.

This behaviour can be customized by attribute rg_autoGoneAfter.



Synchronizing presence with other GUEST, PET or ROOMMATE devices


If you always leave or arrive at your house together with other roommates, guests or pets, you may enable a synchronization of your presence state for certain individuals.
By setting attribute rg_passPresenceTo, those individuals will follow your presence state changes to 'home', 'absent' or 'gone' as you do them with your own device.

Please note that individuals with current state 'gone' or 'none' (in case of guests) will not be touched.



Synchronizing state with other GUEST, PET or ROOMMATE devices


To sync each and every status change that is _not_ related to leaving or arriving at your house, you may set attribute rg_passStateTo.

Please note that individuals with current state 'gone' or 'none' (in case of guests) will not be touched.



Location correlation to state


Under specific circumstances, changing location will have an effect on the actual state as well.

Whenever location is set to 'home', the state is set to 'home' if prior presence state was 'absent'. If attribute rg_locationHome was defined, all of those locations will trigger state change to 'home' as well.

Whenever location is set to 'underway', the state is set to 'absent' if prior presence state was 'present'. If attribute rg_locationUnderway was defined, all of those locations will trigger state change to 'absent' as well. Those locations won't appear in reading 'lastLocation'.

Whenever location is set to 'wayhome', the reading 'wayhome' is set to '1' if current presence state is 'absent'. If attribute rg_locationWayhome was defined, LEAVING one of those locations will set reading 'wayhome' to '1' as well. So you actually have implicit and explicit options to trigger wayhome.
Arriving at home will reset the value of 'wayhome' to '0'.

If you are using the GEOFANCY module, you can easily have your location updated with GEOFANCY events by defining a simple NOTIFY-trigger like this:

define n_rg_Guest.location notify geofancy:currLoc_Guest.* set rg_Guest:FILTER=location!=$EVTPART1 location $EVTPART1

By defining geofencing zones called 'home' and 'wayhome' in the iOS app, you automatically get all the features of automatic state changes described above.


Attributes

• rg_autoGoneAfter - hours after which state should be auto-set to 'gone' when current state is 'absent'; defaults to 16 hours
• rg_geofenceUUIDs - comma separated list of device UUIDs updating their location via GEOFANCY. Avoids necessity for additional notify/DOIF/watchdog devices and can make GEOFANCY attribute devAlias obsolete. (using more than one UUID/device might not be a good idea as location my leap)
• rg_lang - overwrite global language setting; helps to set device attributes to translate FHEMWEB display text
• rg_locationHome - locations matching these will be treated as being at home; first entry reflects default value to be used with state correlation; separate entries by space; defaults to 'home'
• rg_locationUnderway - locations matching these will be treated as being underway; first entry reflects default value to be used with state correlation; separate entries by comma or space; defaults to "underway"
• rg_locationWayhome - leaving a location matching these will set reading wayhome to 1; separate entries by space; defaults to "wayhome"
• rg_locations - list of locations to be shown in FHEMWEB; separate entries by comma only and do NOT use spaces
• rg_moodDefault - the mood that should be set after arriving at home or changing state from awoken to home
• rg_moodSleepy - the mood that should be set if state was changed to gotosleep or awoken
• rg_moods - list of moods to be shown in FHEMWEB; separate entries by comma only and do NOT use spaces
• rg_noDuration - may be used to disable continuous, non-event driven duration timer calculation (see readings durTimer*)
• rg_passStateTo - synchronize home state with other GUEST, PET or ROOMMATE devices; separte devices by space
• rg_passPresenceTo - synchronize presence state with other GUEST, PET or ROOMMATE devices; separte devices by space
• rg_presenceDevices - take over presence state from any other FHEM device. Separate more than one device with comma meaning ALL of them need to be either present or absent to trigger update of this GUEST device. You may optionally add a reading name separated by :, otherwise reading name presence and state will be considered.
• rg_realname - whenever GUEST wants to use the realname it uses the value of attribute alias or group; defaults to group
• rg_showAllStates - states 'asleep' and 'awoken' are hidden by default to allow simple gotosleep process via devStateIcon; defaults to 0
• rg_states - list of states to be shown in FHEMWEB; separate entries by comma only and do NOT use spaces; unsupported states will lead to errors though
• rg_wakeupDevice - reference to enslaved DUMMY devices used as a wake-up timer (part of RESIDENTS Toolkit's wakeuptimer)
• subType - specifies a specific class of a guest for the device. This will be considered for home alone status calculation. Defaults to "generic"



Generated Readings/Events:

• durTimerAbsence - timer to show the duration of absence from home in human readable format (hours:minutes:seconds)
• durTimerAbsence_cr - timer to show the duration of absence from home in computer readable format (minutes)
• durTimerPresence - timer to show the duration of presence at home in human readable format (hours:minutes:seconds)
• durTimerPresence_cr - timer to show the duration of presence at home in computer readable format (minutes)
• durTimerSleep - timer to show the duration of sleep in human readable format (hours:minutes:seconds)
• durTimerSleep_cr - timer to show the duration of sleep in computer readable format (minutes)
• lastArrival - timestamp of last arrival at home
• lastAwake - timestamp of last sleep cycle end
• lastDeparture - timestamp of last departure from home
• lastDurAbsence - duration of last absence from home in human readable format (hours:minutes:seconds)
• lastDurAbsence_cr - duration of last absence from home in computer readable format (minutes)
• lastDurPresence - duration of last presence at home in human readable format (hours:minutes:seconds)
• lastDurPresence_cr - duration of last presence at home in computer readable format (minutes)
• lastDurSleep - duration of last sleep in human readable format (hours:minutes:seconds)
• lastDurSleep_cr - duration of last sleep in computer readable format (minutes)
• lastLocation - the prior location
• lastMood - the prior mood
• lastSleep - timestamp of last sleep cycle begin
• lastState - the prior state
• lastWakeup - time of last wake-up timer run
• lastWakeupDev - device name of last wake-up timer
• location - the current location
• mood - the current mood
• nextWakeup - time of next wake-up program run
• nextWakeupDev - device name for next wake-up program run
• presence - reflects the home presence state, depending on value of reading 'state' (can be 'present' or 'absent')
• state - reflects the current state
• wakeup - becomes '1' while a wake-up program of this resident is being executed
• wayhome - depending on current location, it can become '1' if individual is on his/her way back home


The following readings will be set to '-' if state was changed to 'none':
lastArrival, lastDurAbsence, lastLocation, lastMood, location, mood

GardenaSmartBridge

Prerequisite


• In combination with GardenaSmartDevice this FHEM Module controls the communication between the GardenaCloud and connected Devices like Mover, Watering_Computer, Temperature_Sensors
• Installation of the following packages: apt-get install libio-socket-ssl-perl
• The Gardena-Gateway and all connected Devices must be correctly installed in the GardenaAPP

Define

define <name> GardenaSmartBridge

Beispiel:

define Gardena_Bridge GardenaSmartBridge


The GardenaSmartBridge device is created in the room GardenaSmart, then the devices of Your system are recognized automatically and created in FHEM. From now on the devices can be controlled and changes in the GardenaAPP are synchronized with the state and readings of the devices.



Readings
• address - your Adress (Longversion)
• authorized_user_ids -
• city - Zip, City
• devices - Number of Devices in the Cloud (Gateway included)
• lastRequestState - Last Status Result
• latitude - Breitengrad des Grundstücks
• longitude - Längengrad des Grundstücks
• name - Name of your Garden – Default „My Garden“
• state - State of the Bridge
• token - SessionID


set
• getDeviceState - Starts a Datarequest
• getToken - Gets a new Session-ID
• gardenaAccountPassword - Passwort which was used in the GardenaAPP
• deleteAccountPassword - delete the password from store


Attributes
• debugJSON -
• disable - Disables the Bridge
• interval - Interval in seconds (Default=180)
• gardenaAccountEmail - Email Adresse which was used in the GardenaAPP

GardenaSmartDevice

In combination with Fhem device GardenaSmartBridge this Fhem module enables communication between GardenaCloud and fhem.

Once the bridge device is created, the connected Gardena devices will be recognized and created in Fhem automatically.
From now on these devices can be controlled via Fhem. Changes in the Gardena App are synchronized with state and readings of the devices.

So far, known devices are mower, smart water control, irrigation control, smart sensors, power plug and pressure pump. Schedules can be disabled/enabled via fhem, defining or deleting them must be done via Gardena App or its web interface.

Readings (model = mower)

Readings are based on Sileno, other models might have different/additional readings depending on their functions (tbd.)


• battery-charging - Indicator if battery is charged (0/1)
• battery-level - load percentage of battery
• battery-rechargeable_battery_status - healthyness of the battery (out_of_operation/replace_now/low/ok), not all models
• device_info-category - category of device (mower/watering_computer)
• device_info-connection_status - connection status (online/offline/unknown)
• device_info-last_time_online - timestamp of last radio contact
• device_info-manufacturer - manufacturer
• device_info-product - product type
• device_info-serial_number - serial number
• device_info-sgtin - (tbd.)
• device_info-version - firmware version
• firmware-firmware_command - firmware command (idle/firmware_cancel/firmware_upload/unsupported)
• firmware-firmware_status - firmware status
• firmware-firmware_upload_progress - progress indicator of firmware update
• firmware-inclusion_status - inclusion status
• internal_temperature-temperature - internal device temperature, not all models
• mower-error - actual error message
  • no_message
  • outside_working_area
  • no_loop_signal
  • wrong_loop_signal
  • loop_sensor_problem_front
  • loop_sensor_problem_rear
  • trapped
  • upside_down
  • low_battery
  • empty_battery
  • no_drive
  • lifted
  • stuck_in_charging_station
  • charging_station_blocked
  • collision_sensor_problem_rear
  • collision_sensor_problem_front
  • wheel_motor_blocked_right
  • wheel_motor_blocked_left
  • wheel_drive_problem_right
  • wheel_drive_problem_left
  • cutting_system_blocked
  • invalid_sub_device_combination
  • settings_restored
  • electronic_problem
  • charging_system_problem
  • tilt_sensor_problem
  • wheel_motor_overloaded_right
  • wheel_motor_overloaded_left
  • charging_current_too_high
  • temporary_problem
  • guide_1_not_found
  • guide_2_not_found
  • guide_3_not_found
  • difficult_finding_home
  • guide_calibration_accomplished
  • guide_calibration_failed
  • temporary_battery_problem
  • battery_problem
  • alarm_mower_switched_off
  • alarm_mower_stopped
  • alarm_mower_lifted
  • alarm_mower_tilted
  • connection_changed
  • connection_not_changed
  • com_board_not_available
  • slipped
• mower-last_error_code - code of last error
• mower-source_for_next_start - source for the next start
  • no_source
  • mower_charging
  • completed_cutting_autotimer
  • week_timer
  • countdown_timer
  • undefined
• mower-status - mower status (see state reading)
• mower-timestamp_last_error_code - timestamp of last error
• mower-timestamp_next_start - timestamp of next scheduled start
• mower_stats-charging_cycles - number of charging cycles
• mower_stats-collisions - number of collisions
• mower_stats-cutting_time - cutting time in hours
• mower_stats-running_time - running time in hours (including cutting time)
• mower_timer-mower_timer - (tbd.)
• mower_timer-mower_timer_timestamp - (tbd.)
• mower_type-base_software_up_to_date - latest software (0/1)
• mower_type-device_type - device type
• mower_type-device_variant - device variant
• mower_type-mainboard_version - mainboard version
• mower_type-mmi_version - mmi version
• mower_type-serial_number - serial number
• radio-quality - percentage of the radio quality
• radio-state - radio state (bad/poor/good/undefined)
• scheduling-schedules_event_n_end_at - ending time of schedule 1
• scheduling-schedules_event_n_id - ID of schedule 1
• scheduling-schedules_event_n_start_at - starting time of schedule 1
• scheduling-schedules_event_n_weekly - weekdays of schedule 1(comma-separated)
• ...more readings for additional schedules (if defined)
• scheduling-schedules_events_count - number of pre-defined schedules
• startpoint-1-enabled - starpoint 1 enabled (0/1)
• ...more readings for additional startpoints
• state - state of the mower
  • paused
  • ok_cutting
  • ok_searching
  • ok_charging
  • ok_leaving
  • wait_updating
  • wait_power_up
  • parked_timer
  • parked_park_selected
  • off_disabled
  • off_hatch_open
  • unknown
  • error
  • error_at_power_up
  • off_hatch_closed
  • ok_cutting_timer_overridden
  • parked_autotimer
  • parked_daily_limit_reached
  • hibernate - winter mode
• winter_mode - status of winter mode (awake/hibernate)


Readings (model = watering_computer)
• ambient_temperature-temperature - ambient temperature in Celsius
• battery-disposable_battery_status - healthyness of the battery (ok/low/replace_now/out_of_operation/no_battery/unknown)
• battery-level - energy level of battery in percent
• device_info-category - category of device (mower/watering_computer/sensor/etc.)
• device_info-connection_status - connection status (online/offline/unknown)
• device_info-last_time_online - timestamp of last radio contact
• device_info-manufacturer - manufacturer
• device_info-product - product type
• device_info-serial_number - serial number
• device_info-sgtin - (tbd.)
• device_info-version - firmware version
• error-error - error message (tbd.)
• error-valve_error_1_severity - (tbd.)
• error-valve_error_1_type - (tbd.)
• error-valve_error_1_valve_id - id of valve with error
• firmware-firmware_available_version - new available firmware (only if available)
• firmware-firmware_command - firmware command (idle/firmware_cancel/firmware_upload/unsupported)
• firmware-firmware_status - firmware status
• firmware-firmware_upload_progress - progress indicator of firmware update
• firmware-inclusion_status - inclusion status
• manualButtonTime - watering time for manual button on device in minutes
• radio-quality - percentage of the radio quality
• radio-state - radio state (bad/poor/good/undefined)
• scheduling-scheduled_watering_end - next schedule ending time
• scheduling-scheduled_watering_next_start - next schedule starting time
• scheduling-schedules_event_n_valve_1_end_at - ending time of schedule 1
• scheduling-schedules_event_n_valve_1_id - ID of schedule 1
• scheduling-schedules_event_n_valve_1_start_at - starting time of schedule 1
• scheduling-schedules_event_n_valve_1_weekly - weekdays of schedule 1
• scheduling-schedules_events_count - number of pre-defined schedules
• scheduling-schedules_paused_until - date/time until schedule is paused (2038-01-18T00:00:00.000Z is defined as permanently by Gardena cloud)
• state - state of device
  • closed - valve closed, no schedules available
  • closed. schedule permanently paused - valve closed, schedule disabled
  • closed. next watering: YYYY-MM-DD HH:MM - valve closed, next scheduled start at YYYY-MM-DDTHH:MM:00.000Z
  • watering. n minutes left. - watering, n minutes remaining (depending on manual button time or on pre-defined schedule)
  • offline - device is disabled/not connected
  • hibernate - winter mode)
• watering-watering_timer_1_duration - duration of current watering in seconds
• watering-watering_timer_1_irrigation_left - remaining watering time in minutes
• watering-watering_timer_1_state - state of schedule
• watering-watering_timer_1_valve_id - valve id of schedule
• winter_mode - status of winter mode (awake/hibernate)


Readings (model = ic24)
• device_info-category - category of device (mower/watering_computer/sensor/etc.)
• device_info-connection_status - connection status (online/offline/unknown)
• device_info-last_time_online - timestamp of last radio contact
• device_info-manufacturer - manufacturer
• device_info-product - product type
• device_info-serial_number - serial number
• device_info-sgtin - tbd.
• device_info-version - firmware version
• error-error - error message (tbd.)
• error-valve_error_0_severity - (tbd.)
• error-valve_error_0_type - (tbd.)
• error-valve_error_0_valve_id - id of valve with error
• ...more error readings
• firmware-firmware_available_version - new available firmware (only if available)
• firmware-firmware_command - firmware command (idle/firmware_cancel/firmware_upload/unsupported)
• firmware-firmware_status - firmware status
• firmware-firmware_upload_progress - progress indicator of firmware update
• firmware-inclusion_status - inclusion status
• ic24-valves_connected - connected valves (comma separated)
• ic24-valves_master_config - master valve (only if defined in Gardena app)
• radio-quality - percentage of the radio quality
• radio-state - radio state (bad/poor/good/undefined)
• scheduling-scheduled_watering_end - next schedule ending time
• scheduling-scheduled_watering_end_1 - next schedule ending time for valve 1
• ...more readings for valves 2-6
• scheduling-scheduled_watering_next_start - next schedule starting time
• scheduling-scheduled_watering_next_start_1 - next schedule starting time for valve 1
• ...more readings for valves 2-6
• scheduling-schedules_event_n_valve_1_end_at - ending time of schedule 1
• scheduling-schedules_event_n_valve_1_id - ID of schedule 1
• scheduling-schedules_event_n_valve_1_start_at - starting time of schedule 1
• scheduling-schedules_event_n_valve_1_weekly - weekdays of schedule 1
• scheduling-schedules_events_count - number of pre-defined schedules
• ...more readings for further schedules/valves
• scheduling-schedules_paused_until_1 - date/time until schedule is paused (2038-01-18T00:00:00.000Z is defined as permanently by Gardena cloud)
• ...more readings for valves 2-6
• state - state of device
  • closed - valve closed, no schedules available
  • closed. schedule permanently paused - valve closed, all schedules disabled/paused
  • closed. next watering: YYYY-MM-DD HH:MM - valve closed, next scheduled start at YYYY-MM-DDTHH:MM:00.000Z
  • watering. n minutes left. - watering, n minutes remaining. If more than one schedule is active, the longer remaining time is shown.
  • offline - device is disabled/not connected
• valve-valve_name_1 - individual name for valve 1
• ...more readings for valves 2-6 (if installed)
• watering-watering_timer_1_duration - duration of current watering in seconds
• watering-watering_timer_1_irrigation_left - remaining watering time in minutes
• watering-watering_timer_1_state - state of schedule
• watering-watering_timer_1_valve_id - valve id of schedule
• ...more readings for further valves/schedules
• winter_mode - status of winter mode (awake/hibernate)


Readings (model = sensor)
• ambient_temperature-frost_warning - frost warning
• ambient_temperature-temperature - ambient temperature in Celsius
• battery-disposable_battery_status - healthyness of the battery (ok/low/replace_now/out_of_operation/no_battery/unknown)
• battery-level - energy level of battery in percent
• device_info-category - category of device (mower/watering_computer/sensor/etc.)
• device_info-connection_status - connection status (online/offline/unknown)
• device_info-last_time_online - timestamp of last radio contact
• device_info-manufacturer - manufacturer
• device_info-product - product type
• device_info-serial_number - serial number
• device_info-sgtin - tbd.
• device_info-version - firmware version
• firmware-firmware_available_version - new available firmware (only if available)
• firmware-firmware_command - firmware command (idle/firmware_cancel/firmware_upload/unsupported)
• firmware-firmware_status - firmware status
• firmware-firmware_upload_progress - progress indicator of firmware update
• firmware-inclusion_status - inclusion status
• humidity-humidity - humidity in percent
• light-light - brightness in lux
• radio-quality - percentage of the radio quality
• radio-state - radio state (bad/poor/good/undefined)
• soil_temperature-temperature - soil temperature in Celsius
• state - state of sensor (temperature (T:), humidity (H:), brightness/light (L:)|offline|hibernate)
• winter_mode - status of winter mode (awake/hibernate)


Readings (model = sensor2)

"sensor2" does not measure brightness or ambient temperature, and it has another reading for frost warning. Other than that, it seems to be more or less identical to "sensor".


• battery-disposable_battery_status - healthyness of the battery (ok/low/replace_now/out_of_operation/no_battery/unknown)
• battery-level - energy level of battery in percent
• device_info-category - category of device (mower/watering_computer/sensor/etc.)
• device_info-connection_status - connection status (online/offline/unknown)
• device_info-last_time_online - timestamp of last radio contact
• device_info-manufacturer - manufacturer
• device_info-product - product type
• device_info-serial_number - serial number
• device_info-sgtin - tbd.
• device_info-version - firmware version
• firmware-firmware_available_version - new available firmware (only if available)
• firmware-firmware_command - firmware command (idle/firmware_cancel/firmware_upload/unsupported)
• firmware-firmware_status - firmware status
• firmware-firmware_upload_progress - progress indicator of firmware update
• firmware-inclusion_status - inclusion status
• humidity-humidity - humidity in percent
• radio-quality - percentage of the radio quality
• radio-state - radio state (bad/poor/good/undefined)
• soil_model-model_definition - tbd.
• soil_model-model_status - tbd.
• soil_temperature-frost-warning - frost warning
• soil_temperature-temperature - soil temperature in Celsius
• state - state of sensor (temperature (T:), humidity (H:)|offline|hibernate)
• winter_mode - status of winter mode (awake/hibernate)


Readings (model = power)
• (tbd.)


Readings (model = electronic_pressure_pump)
• (tbd.)



Attribute (all models)
• IODev - Name of GardenaSmartBridge device
• model watering_computer|sensor|sensor2|mower|ic24|power|electronic_pressure_pump - model of GardenaSmartDevice
• readingValueLanguage en|de - Reading language enlish or german (default: english, if global language is not set to german)



set (model = mower)
• parkUntilFurtherNotice - park mower and disable schedule
• parkUntilNextTimer - park mower until next schedule
• startOverrideTimer n - manual mowing for n minutes (e.g. 60 = 1h, 1440 = 24h, 4320 = 72h)
• startResumeSchedule - enable schedule
• startPoint enable|disable 1|2|3 - enable or disable pre-defined starting points
• set NAME startpoint enable 1
• set NAME startpoint disable 3 enable 1
• winter_mode hibernate|awake - enable or disable winter mode


set (model = watering_computer)
• cancelOverride - stop (manual) watering
• manualButtonTime n - set watering time for manual button (0 disables button)
• manualOverride n - manual watering for n minutes
• resetValveErrors - reset valve errormessage
• resumeSchedule - enable schedule
• stopSchedule n - disable schedule for n hours (Default: 2038-01-18T00:00:00.000Z, Gardena App reads it as "permanently")
• winter_mode hibernate|awake - enable or disable winter mode


set (model = ic24)
• cancelOverrideValve1 - stop (manual) watering for valve 1
• cancelOverrideValve2 - stop (manual) watering for valve 2
• cancelOverrideValve3 - stop (manual) watering for valve 3
• cancelOverrideValve4 - stop (manual) watering for valve 4
• cancelOverrideValve5 - stop (manual) watering for valve 5
• cancelOverrideValve6 - stop (manual) watering for valve 6
• closeAllValves - close all valves
• manualDurationValve1 n - open valve 1 for n minutes
• manualDurationValve2 n - open valve 2 for n minutes
• manualDurationValve3 n - open valve 3 for n minutes
• manualDurationValve4 n - open valve 4 for n minutes
• manualDurationValve5 n - open valve 5 for n minutes
• manualDurationValve6 n - open valve 6 for n minutes
• resetValveErrors - reset valve errormessage
• resumeScheduleValve n - (re)start irrigation schedule for valve n
• stopScheduleValve n m - stop irrigation schedule for valve n (Default: 2038-01-18T00:00:00.000Z, Gardena App reads it as "permanently")
• winter_mode hibernate|awake - enable or disable winter mode


set (model = sensor)
• refresh temperature|humidity|light - refresh sensor reading for temperature, humidity or daylight
• winter_mode hibernate|awake - enable or disable winter mode


set (model = sensor2)
• refresh temperature|humidity - refresh sensor reading for temperature or humidity
• winter_mode hibernate|awake - enable or disable winter mode


set (model = power)
• (tbd.)


set (model = electronic_pressure_pump)
• (tbd.)

GasCalculator

The GasCalculator Module calculates the gas consumption and costs of one ore more gas counters. It is not a counter module itself but requires a regular expression (regex or regexp) in order to know where to retrieve the continously increasing counter value of one or more mechanical gas counter. As soon the module has been defined within the fhem.cfg, the module reacts on every event of the specified counter like myOWDEVICE:counter.* etc. The GasCalculator module provides several current, historical, statistical predictable values around with respect to one or more gas-counter and creates respective readings. To avoid waiting for max. 12 months to have realistic values, the readings <DestinationDevice>_<SourceCounterReading>_Vol1stDay, <DestinationDevice>_<SourceCounterReading>_Vol1stMonth, <DestinationDevice>_<SourceCounterReading>_Vol1stYear and <DestinationDevice>_<SourceCounterReading>_Vol1stMeter must be corrected with real values by using the setreading - command. These real values may be found on the last gas bill. Otherwise it will take 24h for the daily, 30days for the monthly and up to 12 month for the yearly values to become realistic.




Define
define <name> GasCalculator <regex>
<name> :	The name of the calculation device. Recommendation: "myGasCalculator".
<regex> :	A valid regular expression (also known as regex or regexp) of the event where the counter can be found.
Example: define myGasCalculator GasCalculator myGasCounter:countersA.*




Set

The set - function sets individual values for example to correct values after power loss etc. The set - function works for readings which have been stored in the CalculatorDevice and to update the Offset. The Readings being stored in the Counter - Device need to be changed individially with the set - command. The command "SyncCounter" will calculate and update the Offset. Just enter the value of your mechanical Reader.




Get

The get - function just returns the individual value of the reading. The get - function works only for readings which have been stored in the CalculatorDevice. The Readings being stored in the Counter - Device need to be read individially with get - command.




Attributes

If the below mentioned attributes have not been pre-defined completly beforehand, the program will create the GasCalculator specific attributes with default values. In addition the global attributes e.g. room can be used.

BasicPricePerAnnum : A valid float number for basic annual fee in the chosen currency for the gas supply to the home. The value is provided by your local gas provider is shown on your gas bill. For UK users it may known under "Standing Charge". Please make sure it is based on one year The default value is 0.00

Currency : One of the pre-defined list of currency symbols [€,£,$]. The default value is €

disable : Disables the current module. The module will not react on any events described in the regular expression. The default value is 0 = enabled.

GasCounterOffset : A valid float number of the volume difference = offset (not the difference of the counter ticks!) between the value shown on the mechanic meter for the gas volume and the calculated volume of this device. The value for this offset will be calculated as follows VOffset = VMechanical - VModule The default value is 0.00

GasCubicPerCounts : A valid float number of the ammount of volume per ticks. The value is given by the mechanical trigger of the mechanical gas meter. E.g. GasCubicPerCounts = 0.01 means each count is a hundredth of the volume basis unit. The default value is 0.01

GasNominalHeatingValue : A valid float number for the gas heating value in [kWh/ chosen Volume]. The value is provided by your local gas provider is shown on your gas bill. The default value is 10.00

GaszValue : A valid float number for the gas condition based on the local installation of the mechanical gas meter in relation of the gas providers main supply station. The value is provided by your local gas provider is shown on your gas bill. The default value is 1.00

GasPricePerKWh : A valid float number for gas price in the chosen currency per kWh for the gas. The value is provided by your local gas provider is shown on your gas bill. The default value is 0.0654

MonthlyPayment : A valid float number for monthly advance payments in the chosen currency towards the gas supplier. The default value is 0.00

MonthOfAnnualReading : A valid integer number for the month when the mechanical gas meter reading is performed every year. The default value is 5 (May)

ReadingDestination : One of the pre-defined list for the destination of the calculated readings: [CalculatorDevice,CounterDevice]. The CalculatorDevice is the device which has been created with this module. The CounterDevice is the Device which is reading the mechanical gas-meter. The default value is CalculatorDevice - Therefore the readings will be written into this device.

Volume : One of the pre-defined list of volume symbols [m³,ft³]. The default value is m³




Readings

As soon the device has been able to read at least 2 times the counter, it automatically will create a set readings: The placeholder <DestinationDevice> is the device which has been chosen in the attribute ReadingDestination above. This will not appear if CalculatorDevice has been chosen. The placeholder <SourceCounterReading> is the reading based on the defined regular expression.

<DestinationDevice>_<SourceCounterReading>_EnergyCostDayLast	: Energy costs of the last day.
<DestinationDevice>_<SourceCounterReading>_EnergyCostMeter	: Energy costs in the chosen currency since the beginning of the month of where the last gas-meter reading has been performed by the gas supplier.
<DestinationDevice>_<SourceCounterReading>_EnergyCostMeterLast	: Energy costs in the chosen currency of the last gas-meter period.
<DestinationDevice>_<SourceCounterReading>_EnergyCostMonth	: Energy costs in the chosen currency since the beginning of the current month.
<DestinationDevice>_<SourceCounterReading>_EnergyCostMonthLast	: Energy costs in the chosen currency of the last month.
<DestinationDevice>_<SourceCounterReading>_EnergyCostYear	: Energy costs in the chosen currency since the beginning of the current year.
<DestinationDevice>_<SourceCounterReading>_EnergyCostYearLast	: Energy costs of the last calendar year.
<DestinationDevice>_<SourceCounterReading>_EnergyDay	: Energy consumption in kWh since the beginning of the current day (midnight).
<DestinationDevice>_<SourceCounterReading>_EnergyDayLast	: Total Energy consumption in kWh of the last day.
<DestinationDevice>_<SourceCounterReading>_EnergyMeter	: Energy consumption in kWh since the beginning of the month of where the last gas-meter reading has been performed by the gas supplier.
<DestinationDevice>_<SourceCounterReading>_EnergyMeterLast	: Total Energy consumption in kWh of the last gas-meter reading period.
<DestinationDevice>_<SourceCounterReading>_EnergyMonth	: Energy consumption in kWh since the beginning of the current month (midnight of the first).
<DestinationDevice>_<SourceCounterReading>_EnergyMonthLast	: Total Energy consumption in kWh of the last month.
<DestinationDevice>_<SourceCounterReading>_EnergyYear	: Energy consumption in kWh since the beginning of the current year (midnight of the first).
<DestinationDevice>_<SourceCounterReading>_EnergyYearLast	: Total Energy consumption in kWh of the last calendar year.
<DestinationDevice>_<SourceCounterReading>_FinanceReserve	: Financial Reserver based on the advanced payments done on the first of every month towards the gas supplier. With negative values, an additional payment is to be excpected.
<DestinationDevice>_<SourceCounterReading>_MonthMeterReading	: Number of month since last meter reading. The month when the reading occured is the first month = 1.
<DestinationDevice>_<SourceCounterReading>_Meter	: Current indicated total volume consumption on mechanical gas meter. Correct Offset-attribute if not identical.
<DestinationDevice>_<SourceCounterReading>_PowerCurrent	: Current heating Power. (Average between current and previous measurement.)
<DestinationDevice>_<SourceCounterReading>_PowerDayAver	: Average heating Power since midnight.
<DestinationDevice>_<SourceCounterReading>_PowerDayMax	: Maximum power peak since midnight.
<DestinationDevice>_<SourceCounterReading>_PowerDayMin	: Minimum power peak since midnight.
<DestinationDevice>_<SourceCounterReading>_Vol1stDay	: First volume reading of the current day.
<DestinationDevice>_<SourceCounterReading>_VolLastDay	: Volume reading of the previous day.
<DestinationDevice>_<SourceCounterReading>_Vol1stMonth	: First volume reading of the current month.
<DestinationDevice>_<SourceCounterReading>_VolLastMonth	: Volume reading of the previous month.
<DestinationDevice>_<SourceCounterReading>_Vol1stYear	: First volume reading of the current year.
<DestinationDevice>_<SourceCounterReading>_VolLastYear	: Volume reading of the previous year.
<DestinationDevice>_<SourceCounterReading>_Vol1stMeter	: First volume reading of the first day of the month of the current meter reading period.
<DestinationDevice>_<SourceCounterReading>_VolLastMeter	: Volume reading of the first day of the month of the last meter reading period.

GoogleAuth

GoogleAuthenticator provides two-factor-authentication using one-time-passwords (token).
These tokens are generated using the mobile app „Google Authenticator“ for example on a smartphone.
See https://en.wikipedia.org/wiki/Google_Authenticator for more informations.


Prerequesits


• The fhem implementation of the Google Authenticator is credited to the following publication:
  https://blog.darkpan.com/article/6/Perl-and-Google-Authenticator.html


• Module uses following additional Perl modules:
  
  
  Convert::Base32 Authen::OATH Crypt::URandom
  
  If not already installed in your environment, please install them using appropriate commands from your environment.
  
  Package installation in debian environments:
  
  
  apt-get install libconvert-base32-perl libauthen-oath-perl libcrypt-urandom-perl


Define


define <name> GoogleAuth

Example:


define googleAuth GoogleAuth



Set Commands


• set <name> new
  
  Generates a new secret key and displays the corresponding QR image.
  Using the photo function of the Google Authenticator app,
  this QR image can be used to transfer the secret key to the app.


• set <name> revoke
  
  Remove existing key.
  You can not create a new key before an existing key was deleted.
  


Get Commands


• get <name> check <token>
  
  Check the validity of a given token; return value is 1 for a valid token, otherwise -1.
  
  • Token always consists of six numerical digits and will change every 30 seconds.
  • Token is valid if it matches one of three tokens calculated by FHEM
    using three timestamps: -30 seconds, now and +30 seconds.
    This behavior can be changed by attribute ga_strictCheck.


Attributes


• ga_labelName - define a Name to identify PassCode inside the app.
  Do not use any special characters, except SPACE, in this attribute!
• ga_qrSize - select image size of qr code
• ga_showKey - show key for manual use if set to 1
• ga_showLink - show link to qr code if set to 1
• ga_showQR - show qr code if set to 1
• ga_strictCheck
       AttrVal = 1 : check given token against one token
       AttrVal = 0 : check given token against three tokens(default)


Generated Readings/Events


• lastResult - contains result from last token check
• state - "active" if a key is set, otherwise "defined"


Integration with gAuth()


• gAuth(<name>,<token>)
  
  For easy use in your own scenarios you can call function gAuth(),
  which will return same result codes as the "get" command.


• Usage of gAuth() for login to FHEM
  
  A device of TYPE=allowed can be used to secure login to FHEM via basicAuth.
  attr <deviceName> basicAuth { "$user" eq "xxx" && gAuth("GoogleAuth","$password","<deviceName>") == 1 }
  
  In both cases <deviceName> has to be the name of the allowed-TYPE device.
  The authenticated login will be cached for this device for a maximum period of 86400 seconds.
  Do not use basicAuthExpiry in this scenario!
  The cache will be lost after FHEM restart or after any invalid token checked by the named allowed-TYPE device.
  

HCS

Defines a virtual device for monitoring thermostats (FHT, HM-CC-TC, MAX, Z-Wave, PID20) to control a central heating unit.

Define
define <name> HCS <device>


• <device> the name of a predefined device to switch.

The HCS (heating control system) device monitors the state of all detected thermostats in a free definable interval (by default: 10 min).

Regulation for heating requirement or suppression of the request can be controlled by valve position or measured temperature (default) using also free definable thresholds. In doing so, the HCS device also includes the hysteresis between two states.

Example for monitoring measured temperature:
Threshold temperature for heating requirement: 0.5 (default)
Threshold temperature for idle: 0.5 (default)

Heating is required when the measured temperature of a thermostat is lower than 0.5° Celsius as the desired temperature. HCS then activates the defined device until the measured temperature of the thermostat is 0.5° Celsius higher as the desired temperature (threshold for idle). In this example, both tresholds are equal.

Example for monitoring valve position:
Threshold valve position for heating requirement: 40% (default)
Threshold valve position for idle: 35% (default)

Heating is required when the "open" position of a valve is more than 40%. HCS then activates the defined device until the "open" position of the valve has lowered to 35% or less (threshold for idle).

The HCS device supports an optional eco mode. The threshold oriented regulation by measured temperature or valve position can be overridden by setting economic thresholds.

Example:
Threshold temperature economic mode on: 16° Celsius
Threshold temperature economic mode off: 17° Celsius

HCS activates the defined device until the measured temperature of one ore more thermostats is lower or equal than 16° Celsius. If a measured temperature of one or more thermostats is higher or equal than 17° Celsius, HCS switch of the defined device (if none of the measured temperatures of all thermostats is lower or equal as 16° Celsius).

In addition, the HCS device supports an optional temp-sensor. The threshold and economic oriented regulation can be overriden by the reading of the temp-sensor (overdrive mode).

Example:
Threshold temperature reading for heating requirement: 10° Celsius
Threshold temperature reading for idle: 18° Celsius

Is a measured temperature ore valve position reaching or exceeding the threshold for heating requirement, but the temperature reading is more than 18° Celcius, the selected device will stay deactivated. The measured temperature or valve-position oriented regulation has been overridden by the temperature reading in this example.

The HCS device automatically detects devices which are ignored. Furthermore, certain devices can also be excluded of the monitoring manually.

To reduce the transmission load, use the attribute event-on-change-reading, e.g. attr <name> event-on-change-reading state,devicestate,eco,overdrive

To avoid frequent switching "on" and "off" of the device, a timeout (in minutes) can be set using the attribute idleperiod.

Get
• values
  returns the actual values of each device

Set
• eco <on>|<off>
  enable (on) or disable (off) the economic mode.
• interval <value>
value modifies the interval of reading the actual valve positions. The unit is minutes.
• mode <thermostat>|<valve>
  changes the operational mode:
  thermostat controls the heating demand by defined temperature thresholds.
  valve controls the heating demand by defined valve position thresholds.
• on
  restarts the monitoring after shutdown by off switch.
  HCS device starts up automatically upon FHEM start or after new device implementation!
• off
  shutdown of monitoring, can be restarted by using the on command.

Attributes
• deviceCmdOn (mandatory)
  command to activate the device, e.g. on. Default value: on
• deviceCmdOff (mandatory)
  command to deactivate the device, e.g. off. Default value: off
• ecoTemperatureOn (Required by eco mode)
  defines threshold for measured temperature upon which device is allways switched on
• ecoTemperatureOff (Required by eco mode)
  defines threshold for measured temperature upon which device is switched off
• exclude (optional)
  space or comma separated list of devices (FHT or HM-CC-TC) for excluding from monitoring
• idleperiod (mandatory)
  locks the device to be switched for the specified period. The unit is minutes. Default value: 10
• mode (mandatory)
  defines the operational mode:
  thermostat controls the heating demand by defined temperature thresholds.
  valve controls the heating demand by defined valve position thresholds.
  Default value: thermostat
• sensor (optional)
  device name of the temp-sensor
• sensorThresholdOn (Required by sensor)
  threshold for temperature reading activating the defined device Must be set if sensor has been defined
• sensorThresholdOff (Required by sensor)
  threshold for temperature reading deactivating the defined device. Must be set if sensor has been defined
• sensorReading (Required by sensor)
  name which is used for saving the "reading" of the defined temp-sensor.
• thermostatThresholdOn (Required by operational mode thermostat)
  defines delta threshold between desired and measured temperature upon which device is switched on (heating required).
  Default value: 0.5
• thermostatThresholdOff (Required by operational mode thermostat)
  defines delta threshold between desired and measured temperature upon which device is switched off (idle).
  Default value: 0.5
• valveThresholdOn (Required by operational mode valve)
  defines threshold of valve-position upon which device is switched on (heating required).
  Default value: 40
• valveThresholdOff (Required by operational mode valve)
  defines threshold of valve-position upon which device is switched off (idle).
  Default value: 35
• disable
• do_not_notify
• event-on-change-reading
  default value: state,devicestate,eco,overdrive
• event-on-update-reading
• verbose
  verbose 4 (or lower) shows a complete statistic of scanned devices (FHT or HM-CC-TC).
  verbose 3 shows a short summary of scanned devices.
  verbose 2 suppressed the above messages.

HEATRONIC

The HEATRONIC module interprets messages received from the HT-Bus of a Junkers Boiler.
Possible Adapters are described in http://www.mikrocontroller.net/topic/317004 (only in german).

Define:

define <name> HEATRONIC <serial-device | <proxy-server IP-address:port> Example for serial-device:

define Boiler HEATRONIC /dev/ttyUSB0@9600

Example for proxy-server:

define Boiler HEATRONIC 192.168.2.11:8088

Set:
set <name> <param> <value>

(only possible with ht_pitiny- or ht_piduino-adapters)

where param is one of:
• hc1_Trequired <temp>
  sets the 'heating' temperature-niveau for heating circuit 1 (permanent)
  0.5 celsius resolution - temperature between 10 and 30 celsius
• hc1_mode [ auto | comfort | eco | frost ]
  sets the working mode for heating circuit 1
  
  • auto : the timer program is active and the summer configuration is in effect
  • comfort: manual by 'comfort' working mode, no timer program is in effect
  • eco : manual by 'eco' working mode, no timer program is in effect
  • frost : manual by 'frost' working mode, no timer program is in effect

Examples:
set Boiler hc1_Trequired 22.5
set Boiler hc1_mode eco



Attributes:
• interval_ch_time, interval_ch_Tflow_measured, interval_dhw_Tmeasured, interval_dhw_Tcylinder
  interval (in seconds) to update the corresponding values


• minDiff_ch_Tflow_measured
  minimal difference (in degrees, e.g. 0.2) to update the corresponding values


Readings:
• ch_Tflow_desired
  required flow temperature (in domestic hot water mode value of max vessel temperature)
  


• ch_Tflow_measured
  current measured flow temperature


• ch_Treturn
  current measured return temperature


• ch_Tmixer
  current measured mixer temperature


• ch_mode
  current operation mode (0=off, 1=heating, 2=domestic hot water)


• ch_code
  current operation code or extended error code (see manual of boiler)


• ch_code
  error code (see manual of boiler)


• ch_burner_fan
  status of burner fan (0=off, 1=running)


• ch_burner_operation
  burner status (0=off, 1=on)


• ch_pump_heating
  status of the heating pump(0=off, 1=running)


• ch_pump_cylinder
  status of cylinder loading pump (0=off, 1=running)


• ch_pump_circulation
  status of circulation pump (0=off, 1=running)


• ch_burner_power
  burner power in percent


• ch_pump_heating_power
  power of heating power in percent


• ch_Toutside
  outside temperature


• ch_runtime_total
  runtime of burner in minutes (heating and domestic hot water)


• ch_runtime_ch
  runtime of burner in minutes (heating only)


• ch_runtime_dhw
  runtime of burner in minutes (domestic hot water only)


• ch_starts_tot
  count of burner operations (heating and domestic hot water)


• ch_starts_ch
  count of burner operations (heating only)


• ch_starts_dhw
  count of burner operations (domestic hot water only)


• ch_time
  system time of boiler


• hc1_Tdesired .. hc4_Tdesired
  required room temperature for heating circuit 1-4


• hc1_Tmeasured .. hc4_Tmeasured
  current measured room temperature for heating circuit 1-4


• hc1_Tmode .. hc4_Tmode
  operating mode for heating circuit 1-4


• dhw_Tdesired
  required domestic hot water temperature


• dhw_Tmeasured
  current measured domestic hot water temperature


• dhw_Tcylinder
  current measured domestic hot water temperature at the top of the cylinder


• sol_Tcollector
  temperature of collector groupp 1


• sol_Tcylinder_bottom
  temperature at the bottom of solar cylinder


• sol_yield_last_hour
  yield of collector in the last hour


• sol_yield_2
  This value is unkown at the moment. The name can be changed later.


• sol_pump
  status of solar circuit pump (0=off, 1=running)


• sol_runtime
  runtime of solar pump in minutes

HEOSGroup

HEOSGroup

In combination with HEOSMaster and HEOSPlayer this FHEM Module controls the Denon multiroom soundsystem using a telnet socket connection and the HEOS Command Line Interface (CLI).

Once the master device is created, the players and groups of Your system are automatically recognized and created in FHEM. From now on the players and groups can be controlled and changes in the HEOS app or at the Receiver are synchronized with the state and media readings of the players and groups.

Groups can be created from a player with "groupWithMember".

Example:

set living groupWithMember kitchen


... creates a group named "living+kitchen" with player "living" as leader and player "kitchen" as member.



Readings
• channel - nr of now playing favorite
• currentAlbum - name of now playing album
• currentArtist - name of now playing artist
• currentImageUrl - URL of cover art, station logo, etc.
• currentMedia - type of now playing media (song|station|genre|artist|album|container)
• currentMid - media ID
• currentQid - queue ID
• currentSid - source ID
• currentStation - name of now playing station
• currentTitle - name of now playing title
• error - last error
• gid - group ID
• leader - leader of the group
• member - member(s) of the group
• mute - player mute state (on|off)
• name - name of player (received from app)
• playStatus - state of player (play|pause|stop)
• repeat - player repeat state (on_all|on_one|off)
• shuffle - player shuffle state (on|off)
• state - state of player connection (on|off)
• volume - player volume level (0-100)
• volumeDown - player volume step level (1-10, default 5)
• volumeUp - player volume step level (1-10, default 5)


set
• channel <nr> - plays favorite <nr> created with app
• channelUp - switches to next favorite
• channelDown- switches to previous favorite
• clearGroup - dissolves the group (sets state to off)
• getGroupInfo - get media info of the group
• mute on|off - set mute state on|off
• next - play next title in queue
• pause - set state of player to "pause"
• play - set state of player to "play"
• playPlaylist <myList> - play playlist <myList>
• prev - play previous title in queue
• repeat - set player repeat state (on_all|on_one|off)
• shuffle - set player shuffle state on|off
• stop - set state of player to "stop"
• volume - set volume 0..100
• volumeDown - reduce volume by <volumeDown>
• volumeUp - increase volume by <volumeUp>


state
• state of group (on|off)

HEOSMaster

HEOSMaster

In combination with HEOSPlayer and HEOSGroup this FHEM Module controls the Denon multiroom soundsystem using a telnet socket connection and the HEOS Command Line Interface (CLI).

Prerequisite
• Installation of the following packages: apt-get install libjson-perl libnet-telnet-perl libencode-perl

Define

define <name> HEOSMaster <IP address>

Example:

define MyMasterBox HEOSMaster 192.168.178.67


<IP address> is the IP address of Your HEOS receiver or HEOS box. The master device is created in the room HEOS, then the players of Your system are recognized automatically and created in FHEM. From now on the players can be controlled and changes in the HEOS app or at the Receiver are synchronized with the state and media readings of the players.

Readings
• enableChangeEvents - state of the event reproduction at CLI master (on|off)
• heosAccount - signed_out | signed_in as <HEOSAccount>
• lastCommand - last executed command
• lastPlayerId - player id of the device, which executed the last command
• lastPlayerName - player name of the device, which executed the last command
• lastResult - result of the last executed command
• state - state of the HEOSMaster


set
• checkAccount - checks Your HEOS account
• enableChangeEvents - activates the event reproduction at the CLI master
• getGroups - get a list of all groups and creates the devices, if not done already
• getPlayers - get a list of all players and creates the devices, if not yet existing
• password - set the password of Your HEOS account
• reboot - reboot of the CLI interface at HEOSMaster
• reopen - tries to establish a new socket connection with CLI master
• signAccount In|Out - sign in|out Your HEOS account (attr MyMasterBox heosUsername <username>)


get
• ShowAccount - shows Your HEOS account


state
• connected - the HEOSmaster is connected to the CLI Master
• not connected - the HEOSmaster is not connected to the CLI Master


attributes
• heosUsername - username of Your HEOS account

HEOSPlayer

HEOSPlayer

In combination with HEOSMaster and HEOSGroup this FHEM Module controls the Denon multiroom soundsystem using a telnet socket connection and the HEOS Command Line Interface (CLI).

Once the master device is created, the players and groups of Your system are automatically recognized and created in FHEM. From now on the players and groups can be controlled and changes in the HEOS app or at the Receiver are synchronized with the state and media readings of the players and groups.

Readings
• channel - nr of now playing favorite
• currentAlbum - name of now playing album
• currentArtist - name of now playing artist
• currentImageUrl - URL of cover art, station logo, etc.
• currentMedia - type of now playing media (song|station|genre|artist|album|container)
• currentMid - media ID
• currentQid - queue ID
• currentSid - source ID
• currentStation - name of now playing station
• currentTitle - name of now playing title
• error - last error
• gid - ID of group, in which player is member
• ip-address - ip address of the player
• lineout - lineout level type (variable|Fixed)
• model - model of HEOS speaker (e.g. HEOS 1)
• mute - player mute state (on|off)
• name - name of player (received from app)
• network - network connection type (wired|wifi)
• playStatus - state of player (play|pause|stop)
• repeat - player repeat state (on_all|on_one|off)
• shuffle - player shuffle state (on|off)
• state - state of player connection (on|off)
• version - software version of HEOS speaker
• volume - player volume level (0-100)
• volumeDown - player volume step level (1-10, default 5)
• volumeUp - player volume step level (1-10, default 5)


set
• aux - uses source at aux-input of player
• channel <nr> - plays favorite <nr> created with app
• channelUp - switches to next favorite
• channelDown- switches to previous favorite
• clear queue - clears the queue
• deletePlaylist <myList> - clears playlist <myList>
• set <hp1> groupWithMember <hp2> - creates group with hp1 as leader and hp2 as member
• input sid[,cid][,mid] - set input source-id[,container-id][,media-id]
Example: set kitchen input 1027,1772574848,inputs/tvaudio
starts "tv audio" on player "kitchen"
• mute on|off - set mute state on|off
• next - play next title in queue
• pause - set state of player to "pause"
• play - set state of player to "play"
• playPlaylist <myList> - play playlist <myList>
• playQueueItem <nr> - play title <nr> in queue
• prev - play previous title in queue
• repeat - set player repeat state (on_all|on_one|off)
• saveQueue <myList> - save queue as <myList>
• shuffle - set player shuffle state on|off
• stop - set state of player to "stop"
• volume - set volume 0..100
• volumeDown - reduce volume by <volumeDown>
• volumeUp - increase volume by <volumeUp>


get
• ls - list music sources (input, playlists, favorites, music services, ...)
• channelscount - number of favorites


state
• state of player connection (on|off)


attributes
• channelring - when reaching the last favorite ChannelUp/Down switches in circle, i.e. to the first/last favorite again
• mute2play - if mute switch on speaker is pressed, the stream stops

HMCCU

The module provides an interface between FHEM and a Homematic CCU. HMCCU is the I/O device for the client devices HMCCUDEV and HMCCUCHN. The module requires the additional Perl modules IO::File, RPC::XML::Client, RPC::XML::Server.

Define


define <name> HMCCU [<Protocol>://]<HostOrIP> [<ccu-number>] [nosync] [waitforccu=<timeout>] [ccudelay=<delay>] [delayedinit=<delay>]

Example:
define myccu HMCCU https://192.168.1.10 nosync ccudelay=180

The parameter HostOrIP is the hostname or IP address of a Homematic CCU. Optionally the protocol 'http' or 'https' can be specified. Default protocol is 'http'.
If you have more than one CCU you can specifiy a unique CCU number with parameter ccu-number. If there's only one CCU, the default ccu-number is 1. Note: The ports used for the RPC servers depend on the ccu-number. See attribute rpcserverport for more information.
The optionnosync prevents reading CCU config during interactive device definition. This option is ignored during FHEM start.
With option waitforccu HMCCU will wait for the specified time if CCU is not reachable. Parameter timeout should be a multiple of 20 in seconds. Warning: This option will block the start of FHEM for a maximum of timeout seconds. The default value is 1.
The option ccudelay specifies the time for delayed initialization of CCU environment if the CCU is not reachable during FHEM startup (i.e. in case of a power failure). The default value for delay is 180 seconds. Increase this value if your CCU needs more time to start up after a power failure. This option will not block the start of FHEM.
With option delayedinit the CCU ennvironment will be initialized after the specified time, no matter if CCU is reachable or not. As long as CCU environment is not initialized all client devices of type HMCCUCHN or HMCCUDEV are in state 'pending' and all commands are disabled.

For automatic update of Homematic device datapoints and FHEM readings one have to:


• Define used RPC interfaces with attribute 'rpcinterfaces'
• Start RPC servers with command 'set on'
• Optionally enable automatic start of RPC servers by setting attribute 'rpcserver' to 'on'.

When RPC servers are started for the first time, HMCCU will create a HMCCURPCPROC device for each interface defined in attribut 'rpcinterfaces'. These devices are assigned xto the same room as I/O device.
After I/O device has been defined, start with the definition of client devices using modules HMCCUDEV (CCU devices) and HMCCUCHN (CCU channels) or with commands 'get createDev' or 'get create'.


Set


• set <name> ackmessages
  Acknowledge "device was unreachable" messages in CCU.


• set <name> authentication ['json'] [<username> <password>]
  Set credentials for CCU authentication. With option 'json' the CCU JSON interface is used for syncing the CCU configuration.
  When executing this command without username and password, the credentials are deleted.


• set <name> clear [<reading-exp>]
  Delete readings matching specified reading name expression. Default expression is '.*'. Readings 'state' and 'control' are not deleted.


• set <name> cleardefaults
  Clear default attributes imported from file.


• set <name> datapoint <FHEM-DevSpec> [<channel-number>].<datapoint>=<value>
  Set datapoint values on multiple devices. If FHEM-Device is of type HMCCUDEV a channel-number must be specified. The channel number is ignored for devices of type HMCCUCHN.


• set <name> delete <ccuobject> [<objecttype>]
  Delete object in CCU. Default object type is OT_VARDP. Valid object types are
  OT_DEVICE=device, OT_VARDP=variable.


• set <name> execute <program>
  Execute a CCU program.
  
  Example:
  set d_ccu execute PR-TEST


• set <name> hmscript {<script-file>|'!'<function>|'['<code>']'} [dump] [<parname>=<value> [...]]
  Execute Homematic script on CCU. If script code contains parameters in format $parname they are substituted by corresponding command line parameters parname.
  If output of script contains lines in format Object=Value readings in existing corresponding FHEM devices will be set. Object can be the name of a CCU system variable or a valid channel and datapoint specification. Readings for system variables are set in the I/O device. Datapoint related readings are set in client devices. If option 'dump' is specified the result of script execution is displayed in FHEM web interface. Execute command without parameters will list available script functions.


• set <name> importdefaults <filename>
  Import default attributes from file.


• set <name> initialize
  Initialize I/O device if state of CCU is unreachable.


• set <name> off
  Stop RPC server(s). See also 'set on' command.


• set <name> on
  Start RPC server(s). This command will fork a RPC server process for each RPC interface defined in attribute 'rpcinterfaces'. Until operation is completed only a few set/get commands are available and you may get the error message 'CCU busy'.


• set <name> prgActivate <program>
  Activate a CCU program.


• set <name> prgDeactivate <program>
  Deactivate a CCU program.


• set <name> rpcregister [{all | <interface>}]
  Register RPC servers at CCU.


• set <name> var <variable> <Value>
  Set CCU system variable value. Special characters \_ in value are substituted by blanks.

Get


• get <name> aggregation {<rule>|all}
  Process aggregation rule defined with attribute ccuaggregate.


• get <name> ccuConfig
  Read configuration of CCU (devices, channels, programs). This command is executed automatically after the definition of an I/O device. It must be executed manually after module HMCCU is reloaded or after devices have changed in CCU (added, removed or renamed).
  If a RPC server is running HMCCU will raise events "count devices added in CCU" or "count devices deleted in CCU". It's recommended to set up a notification which reacts with execution of command 'get ccuConfig' on these events.


• get <name> ccuDevices
  Show table of CCU devices including channel roles supported by HMCCU auto detection.


• get <name> ccumsg {service|alarm}
  Query active service or alarm messages from CCU. Generate FHEM event for each message.


• get <name> create <devexp> [p=<prefix>] [s=<suffix>] [f=<format>] [noDefaults] [save] [<attr>=<value> [...]]
  Create client devices for all CCU devices and channels matching specified regular expression. Parameter devexp is a regular expression for CCU device or channel names. HMCCU automatically creates the appropriate client device (HMCCUCHN or HMCCUDEV)
  With options 'p' and 's' a prefix and/or a suffix for the FHEM device name can be specified. The option 'f' with parameter format defines a template for the FHEM device names. Prefix, suffix and format can contain format identifiers which are substituted by corresponding values of the CCU device or channel:
  %n = CCU object name (channel or device)
  %a = CCU address
  In addition a list of default attributes for the created client devices can be specified. If option 'noDefaults' is specified, HMCCU does not set default attributes for a device. Option 'save' will save FHEM config after device definition.


• get <name> createDev <devname>
  Simplified version of 'get create'. Doesn't accept a regular expression for device name.


• get <name> detectDev <devname>
  Diagnostics command. Try to auto-detect device and display the result. Add this information to your post in FHEM forum, if a device is not created as expected.


• get <name> defaults
  List device types and channels with default attributes available.


• get <name> deviceinfo <device-name-or-address> [extended]
  List device channels, datapoints and the device description.


• get <name> dutycycle
  Read CCU interface and gateway information. For each interface/gateway the following information is stored in readings:
  iface_addr_n = interface address
  iface_type_n = interface type
  iface_conn_n = interface connection state (1=connected, 0=disconnected)
  iface_ducy_n = duty cycle of interface (0-100)


• get <name> exportdefaults <filename> [all]
  Export default attributes into file. If option all is specified, also defaults imported by customer will be exported.


• get <name> internal <parameter>
  Show internal values. Valid parameters are:
  
  • interfaces - RPC interfaces
  • groups - Virtual CCU device groups
  • versions - Versions of HMCCU modules


• get <name> paramsetDesc {<device>|<channel>}
  Get parameter set description of CCU device or channel.


• get <name> rpcstate
  Check if RPC server process is running.


• get <name> update [<devexp> [{State | Value}]]
  Update all datapoints / readings of client devices with FHEM device name(!) matching devexp. With option 'State' all CCU devices are queried directly. This can be time consuming.


• get <name> vars <regexp>
  Get CCU system variables matching regexp and store them as readings. Use attribute ccuGetVars to fetch variables periodically.

Attributes


• ccuAdminURLs {ccu|cuxd}=<url> [...]
  Define admin URLs for CCU and CUxD web interface. URls must be in format: Protocol://Host[:Port]. Page or html files will be added automatically. Example:
  attr myIODev ccuAdminURLs ccu=https://192.168.1.2 cuxd=https://192.168.1.2:3000
• ccuaggregate <rule>[;...]
  Define aggregation rules for client device readings. With an aggregation rule it's easy to detect if some or all client device readings are set to a specific value, i.e. detect all devices with low battery or detect all open windows.
  Aggregation rules are automatically executed as a reaction on reading events of HMCCU client devices. An aggregation rule consists of several parameters separated by comma:
  
  
  • name:<rule-name>
    Name of aggregation rule
  • filter:{name|alias|group|room|type}=<incl-expr>[!<excl-expr>]
    Filter criteria, i.e. "type=^HM-Sec-SC.*"
  • read:<read-expr>
    Expression for reading names, i.e. "STATE"
  • if:{any|all|min|max|sum|avg|lt|gt|le|ge}=<value>
    Condition, i.e. "any=open" or initial value, i.e. max=0
  • else:<value>
    Complementary value, i.e. "closed"
  • prefix:{<text>|RULE}
    Prefix for reading names with aggregation results
  • coll:{<attribute>|NAME}[!<default-text>]
    Attribute of matching devices stored in aggregation results. Default text in case of no matching devices found is optional.
  • html:<template-file>
    Create HTML code with matching devices.
  
  Aggregation results will be stored in readings prefixcount, prefixlist, prefixmatch, prefixstate and prefixtable.
  
  Format of a line in template-file is <keyword>:<html-code>. See FHEM Wiki for an example. Valid keywords are:
  
  
  • begin-html: Start of html code.
  • begin-table: Start of table (i.e. the table header)
  • row-odd: HTML code for odd lines. A tag <reading/> is replaced by a matching device.
  • row-even: HTML code for event lines.
  • end-table: End of table.
  • default: HTML code for no matches.
  • end-html: End of html code.
  
  Example: Find open windows
  name=lock,filter:type=^HM-Sec-SC.*,read:STATE,if:any=open,else:closed,prefix:lock_,coll:NAME!All windows closed
  
  Example: Find devices with low batteries. Generate reading in HTML format.
  name=battery,filter:name=.*,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix:batt_,coll:NAME!All batteries OK,html:/home/battery.cfg
  


• ccudef-attributes <attrName>=<attrValue>[;...]
  Define attributes which are assigned to newly defined HMCCUDEV or HMCCUCHN devices. By default no attributes will be assigned. To assign every new device to room Homematic, set this attribute to 'room=Homematic'.


• ccudef-hmstatevals <subst-rule[;...]>
  Set global rules for calculation of reading hmstate.


• ccudef-readingformat {name | address | datapoint | namelc | addresslc | datapointlc}
  Set global reading format. This format is the default for all readings except readings of virtual device groups.


• ccudef-stripnumber [<datapoint-expr>!]{0|1|2|-n|%fmt}[;...]
  Set global formatting rules for numeric datapoint or config parameter values. Default value is 2 (strip trailing zeroes).
  For details see description of attribute stripnumber in HMCCUCHN.
• ccudef-substitute <subst-rule>[;...]
  Set global substitution rules for datapoint value. These rules are added to the rules specified by client device attribute 'substitute'.


• ccudefaults <filename>
  Load default attributes for HMCCUCHN and HMCCUDEV devices from specified file. Best practice for creating a custom default attribute file is by exporting predefined default attributes from HMCCU with command 'get exportdefaults'.


• ccuflags {<flags>}
  Control behaviour of several HMCCU functions. Parameter flags is a comma seperated list of the following strings:
  ackState - Acknowledge command execution by setting STATE to error or success.
  dptnocheck - Do not check within set or get commands if datapoint is valid
  intrpc - No longer supported.
  extrpc - No longer supported.
  logCommand - Write all set and get commands of all devices to log file with verbose level 3.
  logEnhanced - Messages in FHEM logfile will contain line number and process ID.
  logEvents - Write events from CCU into FHEM logfile
  logPong - Write log message when receiving pong event if verbose level is at least 3.
  noAutoSubstitute - Do not substitute reading values by names. This global flag affects all devices. Set this flag in client devices to turn off substitutions in single devices
  noEvents - Ignore events / device updates sent by CCU. No readings will be updated!
  noInitialUpdate - Do not update datapoints of devices after RPC server start. Overrides settings in RPC devices.
  noAutoDetect - Do not detect any device (only for development and testing)
  nonBlocking - Use non blocking (asynchronous) CCU requests
  noReadings - Do not create or update readings
  procrpc - Use external RPC server provided by module HMCCPRPCPROC. During first RPC server start HMCCU will create a HMCCURPCPROC device for each interface confiugured in attribute 'rpcinterface'
  reconnect - Automatically reconnect to CCU when events timeout occurred.


• ccuget {State | Value}
  Set read access method for CCU channel datapoints. Method 'State' is slower than 'Value' because each request is sent to the device. With method 'Value' only CCU is queried. Default is 'Value'. Method for write access to datapoints is always 'State'.


• ccuGetVars <interval>:[<pattern>]
  Read CCU system variables periodically and update readings. If pattern is specified only variables matching this expression are stored as readings. Delete attribute or set interval to 0 to deactivate the polling of system variables.


• ccuReqTimeout <Seconds>
  Set timeout for CCU request. Default is 4 seconds. This timeout affects several set and get commands, i.e. "set datapoint" or "set var". If a command runs into a timeout FHEM will block for Seconds. To prevent blocking set flag 'nonBlocking' in attribute ccuflags.


• ccureadings {0 | 1}
  Deprecated. Readings are written by default. To deactivate readings set flag noReadings in attribute ccuflags.


• createDeviceGroup <pattern>
  The commands "get create" and "get createDev" will automatically set the group attribute for newly created devices to the specified pattern if multiple FHEM devices were created for a single CCU device. This will happen i.e. for remote controls with mutliple keys or HmIP-Wired multi-switches.
  The parameter pattern supports the following placeholders:
  %n - replaced by CCU device name
  %a - replaced by CCU device address
  %t - replaced by CCU device type
  Example: A remote with 4 channels named 'Light_Control' should be created in FHEM. Using command "get createDev" will define one HMCCUCHN device per channel. Our naming scheme for automatically assigned groups should be "ccuDeviceType ccuDeviceName".
  

  		attr myIODev createDeviceGroup "%t %n" 
  		get myIODev createDev Light_Control
  		



• rpcinterfaces <interface>[,...]
  Specify list of CCU RPC interfaces. HMCCU will register a RPC server for each interface. Either interface BidCos-RF or HmIP-RF (HmIP only) is default. Valid interfaces are:
  
  
  • BidCos-Wired (Port 2000)
  • BidCos-RF (Port 2001)
  • Homegear (Port 2003)
  • HmIP-RF (Port 2010)
  • HVL (Port 7000)
  • CUxD (Port 8701)
  • VirtualDevice (Port 9292)


• rpcPingCCU <interval>
  Send RPC ping request to CCU every interval seconds. If interval is 0 ping requests are disabled. Default value is 300 seconds. If attribut ccuflags is set to logPong a log message with level 3 is created when receiving a pong event.


• rpcserver {on | off}
  Specify if RPC server is automatically started on FHEM startup.


• rpcserveraddr <ip-or-name>
  Specify network interface by IP address or DNS name where RPC server should listen on. By default HMCCU automatically detects the IP address. This attribute should be used if the FHEM server has more than one network interface.


• rpcserverport <base-port>
  Specify base port for RPC server. The real listening port of an RPC server is calculated by the formula: base-port + rpc-port + (10 * ccu-number). Default value for base-port is 5400.
  The value ccu-number is only relevant if more than one CCU is connected to FHEM. Example: If base-port is 5000, protocol is BidCos (rpc-port 2001) and only one CCU is connected the resulting RPC server port is 5000+2001+(10*1) = 7010.


• substitute <subst-rule>:<substext>[,...]
  Define substitions for datapoint values. Syntax of subst-rule is
  
  [[<channelno.>]<datapoint>[,...]!]<{#n1-m1|regexp1}>:<text1>[,...]


• stripchar <character>
  Strip the specified character from variable or device name in set commands. This is useful if a variable should be set in CCU using the reading with trailing colon.

HMCCUCHN

The module implements Homematic CCU channels as client devices for HMCCU. A HMCCU I/O device must exist before a client device can be defined. If a CCU channel is not found, execute command 'get ccuConfig' in I/O device. This will synchronize devices and channels between CCU and HMCCU.

Define


define <name> HMCCUCHN {<channel-name> | <channel-address>} [readonly] [defaults|noDefaults] [iodev=<iodev-name>]

If option 'readonly' is specified no set command will be available. With option 'noDefaults' no default attributes will be set during interactive device definition.
The define command accepts a CCU channel name or channel address as parameter.

Examples:
define window_living HMCCUCHN WIN-LIV-1 readonly
define temp_control HMCCUCHN BidCos-RF.LEQ1234567:1

The interface part of a channel address is optional. Channel addresses can be found with command 'get deviceinfo <CCU-DeviceName>' executed in I/O device.

Internals:

• ccuaddr: Address of channel in CCU
• ccudevstate: State of device in CCU (active/inactive/dead)
• ccuif: Interface of device
• ccuname: Name of channel in CCU
• ccurole: Role of channel
• ccusubtype: Homematic subtype of device (different from ccutype for HmIP devices)
• ccutype: Homematic type of device
• readonly: Indicates whether FHEM device is writeable
• receiver: List of peered devices with role 'receiver'. If no FHEM device exists for a receiver, the name of the CCU device is displayed preceeded by 'ccu:'
• sender: List of peered devices with role 'sender'. If no FHEM device exists for a sender, the name of the CCU device is displayed preceeded by 'ccu:'

Set


• set <name> armState {DISARMED|EXTSENS_ARMED|ALLSENS_ARMED|ALARM_BLOCKED}
  [alarm siren] Set arm state.


• set <name> auto
  [thermostat] Turn auto mode on.


• set <name> boost {on|off}
  [thermostat] Turn boost mode on or off


• set <name> calibrate {START|STOP}
  [blind] Run calibration.


• set <name> clear [<reading-exp>|reset]
  Delete readings matching specified reading name expression. Default expression is '.*'. Readings 'state' and 'control' are not deleted. With option 'reset' all readings and all internally stored device parameter values are deleted.


• set <name> close
  [blind,door] Set level of a shutter or blind to 0%.


• set <name> color <color-name>
  [light] Set color of LED light.


• set <name> config [device|<receiver>] <parameter>=<value>[:<type>] [...]
  Set multiple config (parameter set MASTER) or link (parameter set LINKS) parameters. If neither 'device' nor receiver is specified, configuration parameters of current channel are set. With option 'device' configuration parameters of the device are set.
  If a receiver is specified, parameters will be set for the specified link. Parameter receiver is the name of a FHEM device of type HMCCUDEV or HMCCUCHN or a channel address or a CCU channel name. For FHEM devices of type HMCCUDEV the number of the linked channel must be specified.
  Parameter parameter must be a valid configuration parameter. If type is not specified, it's taken from parameter set definition. If type cannot be determined, the default type STRING is used. Valid types are STRING, BOOL, INTEGER, FLOAT, DOUBLE.
  If unit of parameter is 'minutes' (i.e. endtime in a week profile), value/time can be specified in minutes after midnight or in format hh:mm (hh=hours, mm=minutes).
  
  Example 1: Set device parameter AES
  set myDev config device AES=1
  Example 2: Set channel parameters MIN and MAX with type definition
  set myDev config MIN=0.5:FLOAT MAX=10.0:FLOAT
  Example 3: Set link parameter. DEV_PARTNER is a HMCCUDEV device, so channel number (3) is required
  set myDev config DEV_PARTNER:3 MYPARAM=1


• set <name> control <value>
  Set value of control datapoint. This command is available only on command line for compatibility reasons. It should not be used any more.


• set <name> datapoint [<no>:][<channel>.]<datapoint> <{value|'oldval'}> | [<no>:][<channel>.]<datapoint>=<value> [...]
  Set datapoint values of a CCU channel. If value contains blank characters it must be enclosed in double quotes. This command is only available, if channel contains a writeable datapoint.
  By using parameter no one can specify the order in which datapoints are set (see 3rd example below).
  When using syntax datapoint=value with multiple datapoints always specify a no to ensure that datapoints are set in the desired order.
  The special value 'oldval' will set the datapoint to its previous value. This can be used to realize a toggle function for each datapoint. Note: the previous value of a datapoint is not available at the first 'set datapoint' command after FHEM start.
  
  Examples:
  set temp_control datapoint SET_TEMPERATURE 21
set temp_control datapoint AUTO_MODE 1 SET_TEMPERATURE=21
set temp_control datapoint 2:AUTO_MODE=0 1:SET_TEMPERATURE=21


• set <name> defaults ['reset'|'forceReset'|'old'|'update']
  Set default attributes for CCU device type. Default attributes are only available for some device types and for some channels of a device type. With option 'reset' obsolete attributes are deleted if they are matching the default attributes of HMCCU 4.3. Attributes modified by the user will be kept.
  With option 'forceReset' all obsolete attributes will be deleted. The following attributes are obsolete in HMCCU 5.x: 'ccureadingname', 'ccuscaleval', 'eventMap', 'substexcl', 'webCmd', 'widgetOverride'. In addition 'statedatapoint', 'statechannel', 'controldatapoint' and 'controlchannel' are removed if HMCCU is able to detect these values automatically.
  During update to version 5.x it's recommended to use option 'reset' or 'forceReset'. With option 'old' the attributes are set according to HMCCU 4.3 defaults mechanism.


• set <name> down [<value>]
  [dimmer, blind] Decrement value of datapoint LEVEL. This command is only available if channel contains a datapoint LEVEL. Default for value is 20.


• set <name> manu [<temperature>]
  [thermostat] Set manual mode. Default temperature is 20.


• set <name> off
  [switch,thermostat,dimmer] Turn device off.


• set <name> oldLevel
  [dimmer, blind, jalousie, shutter] Set level to previous value.


• set <name> on
  [switch,thermostat,dimmer] Turn device on.


• set <name> on-for-timer <ontime>
  [switch] Switch device on for specified number of seconds. This command is only available if channel contains a datapoint ON_TIME. Parameter ontime can be specified in seconds or in format HH:MM:SS
  
  Example: Turn switch on for 300 seconds
  set myswitch on-for-timer 300


• set <name> on-till <timestamp>
  [switch,dimmer] Switch device on until timestamp. Parameter timestamp can be a time in format HH:MM or HH:MM:SS. This command is only available if channel contains a datapoint ON_TIME.


• set <name> open
  [blind,door] Set level of a shutter or blind to 100%.


• set <name> party <temperature> <start-time> <end-time>
  [thermostat] Turn party mode on. Timestamps must be in format "YYYY_MM_DD HH:MM".


• set <name> pct <value> [<ontime> [<ramptime>]]
  [dimmer,blind] Set datapoint LEVEL of a channel to the specified value. Optionally a ontime and a ramptime (both in seconds) can be specified. This command is only available if channel contains at least a datapoint LEVEL and optionally datapoints ON_TIME and RAMP_TIME. The parameter ontime can be specified in seconds or as timestamp in format HH:MM or HH:MM:SS. If ontime is 0 it's ignored. This syntax can be used to modify the ramp time only.
  
  Example: Turn dimmer on for 600 second. Increase light to 100% over 10 seconds
  set myswitch pct 100 600 10


• set <name> pctSlats <value>
  [blind] Like command 'set pct', but changes the level of slats (if available).


• set <name> press
  [key] Submit a short key press.


• set <name> pressLong
  [key] Submit a long key press.


• set <name> readingFilter <datapoint-list>
  Set attribute ccureadingfilter by selecting a list of datapoints. Parameter datapoint-list is a comma seperated list of datapoints.


• set <name> stop
  [blind,door] Set datapoint STOP of a channel to true. This command is only available, if the channel contains a datapoint STOP.


• set <name> toggle
  [switch,dimmer,blind] Toggle state between values on/off or open/close.


• set <name> up [<value>]
  [blind,dimmer] Increment value of datapoint LEVEL. This command is only available if channel contains a datapoint LEVEL. Default for value is 20.


• set <name> values <parameter>=<value>[:<type>] [...]
  Set multiple datapoint values (parameter set VALUES). Parameter parameter must be a valid datapoint name. If type is not specified, it's taken from parameter set definition. The default type is STRING. Valid types are STRING, BOOL, INTEGER, FLOAT, DOUBLE.


• set <name> ventilate
  [garage door] Set door position to ventilation.

Get


• get <name> config [<filter-expr>]
  Get configuration parameters of device and channel. If filter-expr is specified, only parameters matching the expression are stored as readings.
  Values related to configuration or link parameters are stored as readings beginning with "R-" for MASTER parameter set and "L-" for LINK parameter set. Prefixes "R-" and "L-" can be modified with attribute 'ccuReadingPrefix'. Whether parameters are stored as readings or not, can be controlled by setting the following flags in attribute ccuflags:
  
  • noReadings: Do not store any reading.
  • showMasterReadings: Store configuration readings of parameter set 'MASTER' of current channel.
  • showDeviceReadings: Store configuration readings of device and value readings of channel 0.
  • showLinkReadings: Store readings of links.
  If non of the flags is set, only readings belonging to parameter set VALUES (datapoints) are stored.


• get <name> datapoint <datapoint>
  Get value of a CCU channel datapoint. Format of datapoint is ChannelNo.DatapointName. For HMCCUCHN devices the ChannelNo is not needed. This command is only available if a readable datapoint exists.


• get <name> defaults
  This command has been removed in version 4.4. The default attributes are included in the output of command 'get deviceInfo'.


• get <name> deviceInfo ['extended']
  Display information about device type and channels:
  
  • all channels and datapoints of device with datapoint values and types
  • statedatapoint and controldatapoint
  • device and channel description
  • default attributes (if device is not supported by built in functionality)
  The output of this command is helpful to gather information about new / not yet supported devices. Please add this information to your post in the FHEM forum, if you have a question about the integration of a new device. See also command 'get paramsetDesc'.


• get <name> extValues [<filter-expr>]
  Update all readings for all parameters of parameter set VALUES (datapoints) and connected system variables by using CCU Rega (Homematic script). This command will also update system variables bound to the device. If filter-expr is specified, only datapoints matching the expression are stored as readings.


• get <name> metaData [<filter-expr>]
  Read meta data for device or channel. If filter-expr is specified only meta data IDs matching the specified regular expression are stored as readings.
  Example: get myDev metaData energy.*


• get <name> paramsetDesc
  Display description of parameter sets of channel and device. The output of this command is helpful to gather information about new / not yet supported devices. Please add this information to your post in the FHEM forum, if you have a question about the integration of a new device. See also command 'get deviceInfo'.


• get <name> update [<filter-expr>]
  Update all readings for all parameters of all parameter sets (MASTER, LINK, VALUES). If filter-expr is specified, only parameters matching the expression are stored as readings.


• get <name> values [<filter-expr>]
  Update all readings for all parameters of parameter set VALUES (datapoints). Hint: This command won't update system variables bound to the device. These variables can be read by using command 'get extValues'. If filter-expr is specified, only parameters matching the expression are stored as readings.


• get <name> week-program [<program-number>|all]
  Display week programs. This command is only available if a device supports week programs.

Attributes


To reduce the amount of events it's recommended to set attribute 'event-on-change-reading' to '.*'.


• ccucalculate <value-type>:<reading>[:<dp-list>[;...]
  Calculate special values like dewpoint based on datapoints specified in dp-list. The result is stored in reading.
  The following value-types are supported:
  dewpoint = calculate dewpoint, dp-list = <temperature>,<humidity>
  abshumidity = calculate absolute humidity, dp-list = <temperature>,<humidity>
  equ = compare datapoint values. Result is "n/a" if values are not equal.
  inc = increment datapoint value considering reset of datapoint, dp-list = <counter-datapoint>
  min = calculate minimum continuously, dp-list = <datapoint>
  max = calculate maximum continuously, dp-list = <datapoint>
  sum = calculate sum continuously, dp-list = <datapoint>
  avg = calculate average continuously, dp-list = <datapoint>
  Example:
  dewpoint:taupunkt:1.TEMPERATURE,1.HUMIDITY


• ccuflags {ackState, logCommand, noBoundsChecking, noReadings, hideStdReadings, replaceStdReadings, showDeviceReadings, showLinkReadings, showConfigReadings, trace}
  Control behaviour of device:
  ackState: Acknowledge command execution by setting STATE to error or success.
  hideStdReadings: Do not show standard readings like 'measured-temp'
  replaceStdReadings: Replace original readings like 'ACTUAL_TEMPERATURE' by standard readings like 'measured-temp' instead of adding standard readings
  logCommand: Write get and set commands to FHEM log with verbose level 3.
  noBoundsChecking: Datapoint values are not checked for min/max boundaries
  noAutoSubstitute - Do not substitute reading values by names. This local flag affects only the current device. You can turn off all substitutes by setting this flag in I/O device.
  noReadings: Do not update readings
  simulate: Do not execute set datapoint commands. Use this flag together with 'trace'
  showDeviceReadings: Show readings of device and channel 0.
  showLinkReadings: Show link readings.
  showMasterReadings: Show configuration readings.
  trace: Write log file information for operations related to this device.


• ccuget {State | Value}
  Set read access method for CCU channel datapoints. Method 'State' is slower than 'Value' because each request is sent to the device. With method 'Value' only CCU is queried. Default is 'Value'.


• ccureadingfilter <filter-rule[;...]>
  Only datapoints matching specified expression RegExp are stored as readings.
  Syntax for filter-rule is either:
  [N:]{<channel-name-expr>}!RegExp> or:
  [N:][<channel-number>[,<channel-number>].]<RegExp>
  If channel-name-expr or channel-number is specified the following rule applies only to the specified or matching channel(s).
  If a rule starts with 'N:' the filter is negated which means that a reading is stored if rule doesn't match.
  If you like to suppress the standard device readings like 'battery', a negated filter rule for the corresponding datapoint must be specified (see example for LOW_BAT/battery below)
  
  Examples:
  # Show readings for all datapoints
attr mydev ccureadingfilter .*
# Show readings for matching datapoints of channel 1 and matching datapoints of all channels (2nd rule)
attr mydev ccureadingfilter 1.(^ACTUAL|CONTROL|^SET_TEMP);(^WINDOW_OPEN|^VALVE)
# Show reading datapoint LEVEL of channel MyBlindChannel
attr mydev ccureadingfilter MyBlindChannel!^LEVEL$
# Show every reading except LEVEL attr mydev ccureadingfilter N:LEVEL



• ccureadingformat {address[lc] | name[lc] | datapoint[lc] | <format-string>}
  Set format of reading names. Default for virtual device groups and HMCCUCHN devices is 'name'. The default for HMCCUDEV is 'datapoint'. If set to 'address' format of reading names is channel-address.datapoint. If set to 'name' format of reading names is channel-name.datapoint. If set to 'datapoint' format is channel-number.datapoint. For HMCCUCHN devices the channel part is ignored. With suffix 'lc' reading names are converted to lowercase. The reading format can also contain format specifiers %a (address), %n (name) and %c (channel). Use %A, %N, %C for conversion to upper case. The readings will be refreshed automatically if this attribute is changed. The default value for this attribute can be defined by setting attribute ccudef-readingformat in the I/O device.
  
  Example:
  attr mydev ccureadingformat HM_%c_%N


• ccureadingname <old-readingname-expr>:[[+]<new-readingname>[,...]][;...]
  Set alternative or additional reading names or group readings. Only part of old reading name matching old-readingname-expr is substituted by new-readingname. If no new-readingname is specified, default readings like battery can be suppressed. If new-readingname is preceded by '+' an additional reading is created. If old-readingname-expr matches more than one reading the values of these readings are stored in one reading. This makes sense only in some cases, i.e. if a device has several pressed_short datapoints and a reading should contain a value if any button is pressed.
  
  Examples:
  # Rename readings 0.LOWBAT and 0.LOW_BAT as battery
attr mydev ccureadingname 0.(LOWBAT|LOW_BAT):battery
# Suppress battery reading (no new reading specified after ':')
attr mydev ccureadingname battery:
# Add reading battery as a copy of readings LOWBAT and LOW_BAT (HMCCU does this by default).
# Rename reading 4.SET_TEMPERATURE as desired-temp
attr mydev ccureadingname 1.SET_TEMPERATURE:desired-temp
# Store values of readings n.PRESS_SHORT in new reading pressed.
# Value of pressed is 1/true if any button is pressed
attr mydev ccureadingname [1-4].PRESSED_SHORT:+pressed


• ccuReadingPrefix <paramset>[:<prefix>][,...]
  Set reading name prefix for parameter sets. Default values for parameter sets are:
  VALUES (state values): No prefix
  MASTER (configuration parameters): 'R-'
  LINK (links parameters): 'L-'
  PEER (peering parameters): 'P-'
  To hide prefix do not specify prefix.


• ccuscaleval <[channelno.]datapoint>:<factor>[,...]
  ccuscaleval <[!][channelno.]datapoint>:<min>:<max>:<minn>:<maxn>[,...]
  Scale, spread, shift and optionally reverse values before executing set datapoint commands or after executing get datapoint commands / before storing values in readings.
  If first syntax is used during get the value read from CCU is devided by factor. During set the value is multiplied by factor.
  With second syntax one must specify the interval in CCU (min,max) and the interval in FHEM (minn, maxn). The scaling factor is calculated automatically. If parameter datapoint starts with a '!' the resulting value is reversed.
  
  Example: Scale values of datapoint LEVEL for blind actor and reverse values
  attr myblind ccuscale !LEVEL:0:1:0:100


• ccuSetOnChange <expression>
  Check if datapoint value will be changed by set command before changing datapoint value. This attribute can reduce the traffic between CCU and devices. It presumes that datapoint state in CCU is current.


• ccuverify {0 | 1 | 2}
  If set to 1 a datapoint is read for verification after set operation. If set to 2 the corresponding reading will be set to the new value directly after setting a datapoint in CCU without any verification.


• controldatapoint <datapoint>
  Set datapoint for device control by commands 'set control' and 'set toggle'. This attribute must be set if control datapoint cannot be detected automatically.


• devStateFlags <datapoint>:<value-regexp>:<flag> [...]
  Define flags depending on datapoint values which should appear in reading 'devstate'. All specified datapoints must be readable or updated by CCU events.
  Example: Add a flag 'unreachable' representing datapoint 0.UNREACH to reading 'devstate' (this will override the default setting for '0.UNREACH'):
  attr myDev devStateFlags 0.UNREACH:0|true:unreachable
  By default the following flags exists:
  0.CONFIG_PENDING:cfgPending
  0.DEVICE_IN_BOOTLOADER:boot
  0.UNREACH:unreach
  0.STICKY_UNREACH:stickyUnreach
  0.UPDATE_PENDING:updPending
  0.SABOTAGE:sabotage
  0.ERROR_SABOTAGE:sabotage
  


• disable {0 | 1}
  Disable client device.


• hmstatevals <subst-rule>[;...]
  Define building rules and substitutions for reading hmstate. Syntax of subst-rule is
  [=<reading>;]<datapoint-expr>!<{#n1-m1|regexp}>:<text>[,...]
  
  The syntax is almost the same as of attribute 'substitute', except there's no channel specification possible for datapoint and parameter datapoint-expr is a regular expression.
  The value of the I/O device attribute 'ccudef-hmstatevals' is appended to the value of this attribute. The default value of 'ccudef-hmstatevals' is '^UNREACH!(1|true):unreachable;LOW_?BAT!(1|true):warn_battery'. Normally one should not specify a substitution rule for the "good" value of an error datapoint (i.e. 0 for UNREACH). If none of the rules is matching, reading 'hmstate' is set to value of reading 'state'.
  Parameter text can contain variables in format ${varname}. The variable $value is substituted by the original datapoint value. All other variables must match with a valid datapoint name or a combination of channel number and datapoint name seperated by a '.'.
  Optionally the name of the HomeMatic state reading can be specified at the beginning of the attribute in format =<reading>;. The default reading name is 'hmstate'.


• statedatapoint <datapoint>
  Set datapoint used for displaying device state. This attribute must be set, if state datapoint cannot be detected automatically.


• statevals <new-command>:<control-datapoint-value>[,...]
  Define set commands for control datapoint. This attribute should only be used if the device type is not recognized by HMCCU. Using this attribute for automatically detected devices could lead to problems!
  
  Example: controldatapoint of a device is STATE. Device is not recognized by HMCCU:
  # Define 2 new commands on and off representing the possible states of STATE:
attr my_switch statevals on:true,off:false
# After attr the commands on and off are available:
set my_switch on
set my_switch off


• stripnumber [<datapoint-expr>!]{0|1|2|-n|%fmt}[;...]
  Remove trailing digits or zeroes from floating point numbers, round or format numbers. If attribute is negative (-0 is valid) floating point values are rounded to the specified number of digits before they are stored in readings. The meaning of values 0,1,2 is:
  0 = Floating point numbers are stored as integer.
  1 = Trailing zeros are stripped from floating point numbers except one digit.
  2 = All trailing zeros are stripped from floating point numbers.
  With %fmt one can specify any valid sprintf() format string.
  If datapoint-expr is specified the formatting applies only to datapoints matching the regular expression.
  Example:
  attr myDev stripnumber TEMPERATURE!%.2f degree


• substexcl <reading-expr>
  Exclude values of readings matching reading-expr from substitution. This is helpful for reading 'control' if the reading is used for a slider widget and the corresponding datapoint is assigned to attribute statedatapoint and controldatapoint.


• substitute <subst-rule>[;...]
  Define substitutions for datapoint/reading values. This attribute is helpful / necessary if a device is not automatically detected by HMCCU.
  Syntax of subst-rule is
  
  [[<type>:][<channelno>.]<datapoint>[,...]!]<{#n1-m1|regexp}>:<text>[,...]
  
  Parameter type is a valid channel type/role, i.e. "SHUTTER_CONTACT". Parameter text can contain variables in format ${varname}. The variable ${value} is substituted by the original datapoint value. All other variables must match with a valid datapoint name or a combination of channel number and datapoint name seperated by a '.'.
  
  Example: Substitute the value of datapoint TEMPERATURE by the string 'T=val deg' and append current value of datapoint 1.HUMIDITY
  attr my_weather substitute TEMPERATURE!.+:T=${value} deg H=${1.HUMIDITY}%
  
  If rule expression starts with a hash sign a numeric datapoint value is substituted if it fits in the number range n <= value <= m.
  
  Example: Interpret LEVEL values 100 and 0 of dimmer as "on" and "off"
  attr my_dim substitute LEVEL!#0-0:off,#1-100:on


• traceFilter <filter-expr>
  Trace only function calls which are maching filter-expr.

HMCCUDEV

The module implements Homematic CCU devices as client devices for HMCCU. A HMCCU I/O device must exist before a client device can be defined. If a CCU channel is not found execute command 'get devicelist' in I/O device.
This reference contains only commands and attributes which differ from module HMCCUCHN.

Define


define <name> HMCCUDEV <device> [<controlchannel>] [readonly] [defaults|noDefaults] [forceDev] [iodev=<iodev-name>]

If option 'readonly' is specified no set command will be available. With option 'defaults' some default attributes depending on CCU device type will be set. Default attributes are only available for some device types. The option is ignored during FHEM start. Option 'forceDev' must be specified to define a HMCCUDEV device even if the preferred and recommended type is HMCCUCHN.
Parameter controlchannel corresponds to attribute 'controlchannel'. If a device has several identical channels, some commands need to know the channel number for controlling the device.

Examples:
# Simple device by using CCU device name
define window_living HMCCUDEV WIN-LIV-1
# Simple device by using CCU device address and with state channel
define temp_control HMCCUDEV BidCos-RF.LEQ1234567 1
# Simple read only device by using CCU device address and with default attributes
define temp_sensor HMCCUDEV BidCos-RF.LEQ2345678 1 readonly defaults

Internals:

• ccuaddr: Address of device in CCU
• ccudevstate: State of device in CCU (active/inactive/dead)
• ccuif: Interface of device
• ccuname: Name of device in CCU
• ccurole: Role of device
• ccusubtype: Homematic subtype of device (different from ccutype for HmIP devices)
• ccutype: Homematic type of device
• readonly: Indicates whether FHEM device is writeable
• receiver: List of peered devices with role 'receiver'. If no FHEM device exists for a receiver, the name of the CCU device is displayed preceeded by 'ccu:'
• sender: List of peered devices with role 'sender'. If no FHEM device exists for a sender, the name of the CCU device is displayed preceeded by 'ccu:'

Set


• set <name> clear [<reading-exp>]
  see HMCCUCHN


• set <name> config [<channel-number>] <parameter>=<value> [...]
  Set configuration parameter of CCU device or channel. Valid parameters can be listed by using command 'get configdesc'.


• set <name> control <value>
  Set value of control datapoint. This command is available for compatibility reasons. It should not be used any more.


• set <name> datapoint [<channel-number>.]<datapoint> <value> [...]
  Set datapoint values of a CCU device channel. If channel number is not specified state channel is used. String \_ is substituted by blank.
  
  Example:
  set temp_control datapoint 2.SET_TEMPERATURE 21
set temp_control datapoint 2.AUTO_MODE 1 2.SET_TEMPERATURE 21


• set <name> defaults ['reset'|'old'|'update']
  Set default attributes for CCU device type. Default attributes are only available for some device types and for some channels of a device type. If option 'reset' is specified, the following attributes are deleted before the new attributes are set: 'ccureadingname', 'ccuscaleval', 'eventMap', 'substexcl', 'webCmd', 'widgetOverride'. During update to version 4.4 it's recommended to use option 'reset'. With option 'old' the attributes are set according to HMCCU 4.3 defaults mechanism.


• set <name> down [<value>]
  see HMCCUCHN


• set <name> on-for-timer <ontime>
  see HMCCUCHN


• set <name> on-till <timestamp>
  see HMCCUCHN


• set <name> pct <value;> [<ontime> [<ramptime>]]
  see HMCCUCHN


• set <name> readingFilter <datapoint-list>
  Set attribute ccureadingfilter by selecting a list of datapoints. Parameter datapoint-list is a comma seperated list of datapoints. The datapoints must be specifed in format "channel-number.datapoint-name".


• set <name> <statevalue>
  State datapoint of a CCU device channel is set to 'statevalue'. State channel and state datapoint must be defined as attribute 'statedatapoint'. Values for statevalue are defined by setting attribute 'statevals'.
  
  Example:
  attr myswitch statedatapoint 1.STATE
attr myswitch statevals on:true,off:false
set myswitch on


• set <name> toggle
  see HMCCUCHN


• set <name> up [<value>]
  see HMCCUCHN


• ePaper Display
  
  This display has 5 text lines. The lines 1,2 and 4,5 are accessible via config parameters TEXTLINE_1 and TEXTLINE_2 in channels 1 and 2.
  Example:
  
  define HM_EPDISP HMCCUDEV CCU_EPDISP
set HM_EPDISP config 2 TEXTLINE_1=Line1 # Set line 1 to "Line1"
set HM_EPDISP config 2 TEXTLINE_2=Line2 # Set line 2 to "Line2"
set HM_EPDISP config 1 TEXTLINE_1=Line4 # Set line 4 to "Line4"
set HM_EPDISP config 1 TEXTLINE_2=Line5 # Set line 5 to "Line5"

  The lines 2,3 and 4 of the display can be modified by setting the datapoint SUBMIT of the display to a string containing command tokens in format 'parameter:value'. The following commands are allowed:
  
  
  • text1-3:Text - Content of display line 2-4
  • icon1-3:IconCode - Icons of display line 2-4
  • sound:SoundCode - Sound
  • signal:SignalCode - Optical signal
  • pause:Seconds - Pause between signals (1-160)
  • repeat:Count - Repeat count for sound (0-15)
  
  IconCode := ico_off, ico_on, ico_open, ico_closed, ico_error, ico_ok, ico_info, ico_newmsg, ico_svcmsg
  SignalCode := sig_off, sig_red, sig_green, sig_orange
  SoundCode := snd_off, snd_longlong, snd_longshort, snd_long2short, snd_short, snd_shortshort, snd_long
  
  Example:
  set HM_EPDISP datapoint 3.SUBMIT text1:Line2,text2:Has Blank,text3:10:05:21,sound:snd_short,signal:sig_red

Get


• get <name> config [<filter-expr>]
  Get configuration parameters of CCU device and all its channels. If ccuflag noReadings is set parameters are displayed in browser window (no readings set). Parameters can be filtered by filter-expr.


• get <name> datapoint [<channel-number>.]<datapoint>
  Get value of a CCU device datapoint. If channel-number is not specified state channel is used.


• get <name> defaults
  see HMCCUCHN


• get <name> deviceinfo ['extended']
  Display information about device and channels:
  
  • all channels and datapoints of device with datapoint values and types
  • statedatapoint and controldatapoint
  • device and channel description


• get <name> extValues [<filter-expr>]
  see HMCCUCHN


• get <name> metaData [<filter-expr>]
  see HMCCUCHN


• get <name> update [{State | Value}]
  see HMCCUCHN


• get <name> weekProgram [<program-number>|all]
  Display week programs. This command is only available if a device supports week programs.

Attributes


To reduce the amount of events it's recommended to set attribute 'event-on-change-reading' to '.*'.


• ccucalculate <value-type>:<reading>[:<dp-list>[;...]
  see HMCCUCHN


• ccuflags {nochn0, trace}
  see HMCCUCHN


• ccuget {State | Value}
  see HMCCUCHN


• ccureadingfilter <filter-rule[,...]>
  see HMCCUCHN


• ccureadingformat {address[lc] | name[lc] | datapoint[lc]}
  see HMCCUCHN


• ccureadingname <old-readingname-expr>:<new-readingname>[,...]
  see HMCCUCHN


• ccuscaleval <datapoint>:<factor>[,...]
  ccuscaleval <[!]datapoint>:<min>:<max>:<minn>:<maxn>[,...]
  see HMCCUCHN


• ccuSetOnChange <expression>
  see HMCCUCHN


• ccuverify {0 | 1 | 2}
  see HMCCUCHN


• controlchannel <channel-number>
  Channel used for setting device states.


• controldatapoint <channel-number.datapoint>
  Set channel number and datapoint for device control. see HMCCUCHN


• devStateFlags <datapoint>:<value-expr>:<flag>
  Define flags for datapoint values which should appear in reading 'devstate'. see HMCCUCHN


• disable {0 | 1}
  see HMCCUCHN


• hmstatevals <subst-rule>[;...]
  see HMCCUCHN


• statechannel <channel-number>
  Channel for getting device state. Deprecated, use attribute 'statedatapoint' instead.


• statedatapoint [<channel-number>.]<datapoint>
  Set state channel and state datapoint. Default is STATE. If 'statedatapoint' is not defined at least attribute 'statechannel' must be set.


• statevals <text>:<text>[,...]
  see HMCCUCHN


• stripnumber {0 | 1 | 2 | -n}
  see HMCCUCHN


• substexcl <reading-expr>
  see HMCCUCHN


• substitute <subst-rule>[;...]
  see HMCCUCHN


• traceFilter <filter-expr>
  see HMCCUCHN

HMCCURPCPROC

The module provides a subprocess based RPC server for receiving events from HomeMatic CCU2. A HMCCURPCPROC device acts as a client device for a HMCCU I/O device. Normally RPC servers of type HMCCURPCPROC are started or stopped from HMCCU I/O device via command 'set rpcserver on,off'. HMCCURPCPROC devices will be created automatically by I/O device when RPC server is started. There should be no need for creating HMCCURPCPROC devices manually.

Define


define <name> HMCCURPCPROC {<HostOrIP>|iodev=<DeviceName>} {<port>|<interface>}

Examples:
define myccurpc HMCCURPCPROC 192.168.1.10 2001
define myccurpc HMCCURPCPROC iodev=myccudev BidCos-RF


The parameter HostOrIP is the hostname or IP address of a Homematic CCU2. The I/O device can also be specified with parameter iodev. If more than one CCU exist it's highly recommended to specify IO device with option iodev. Supported interfaces or ports are:

Port	Interface
2000	BidCos-Wired
2001	BidCos-RF
2010	HmIP-RF
7000	HVL
8701	CUxD
9292	Virtual


Set


• set <name> deregister
  Deregister RPC server at CCU.


• set <name> register
  Register RPC server at CCU. RPC server must be running. Helpful when CCU lost connection to FHEM and events timed out.


• set <name> rpcrequest <method> [{<value[:type]>|<parameter>=<value[:type]>|'!STRUCT'} ...]
  Send RPC request to CCU. The result is displayed in FHEM browser window. See EQ-3 RPC XML documentation for mor information about valid methods and requests.
  If type is not speicifed, it's detected automatically. Valid types are:
  INTEGER, BOOL, FLOAT, DOUBLE, BASE64, STRING (defaul)
  The command also supports passing a parameter structure. All parameters in format Name=Value[:Type] are treated as members of a structure. This structure will be appended to the list of the other parameters. If you like to insert the structure at a speicifc position in the parameter list, use '!STRUCT' as a placeholder.
  Example:
  set myRPCDev rpcrequest putParamset 123456 VALUES SET_POINT_TEMPERATURE=20:FLOAT SET_POINT_MODE=1
  Parameters SET_POINT_TEMPERATURE and SET_POINT_MODE will be converted to a structure. This structure is passed as the last parameter to the request.


• set <name> rpcserver { on | off }
  Start or stop RPC server. This command is only available if expert mode is activated.


Get


• get <name> devicedesc [<fhem-device>|<address>]
  Read device and paramset descriptions for current RPC interface from CCU and store the information in I/O device. The device description is always read from CCU. The paramset description is only read if it doesn't exist in IO device. If a HMCCUCHN device or a channel address is specified, the description of the corresponding device address with all channels is read.


• get <name> rpcevent
  Show RPC server events statistics. If attribute ccuflags contains flag 'statistics' the 3 devices which sent most events are listed.


• get <name> rpcstate
  Show RPC process state.


Attributes


• ccuflags { flag-list }
  Set flags for controlling device behaviour. Meaning of flags is:
  ccuInit - RPC server initialization depends on ListDevice RPC call issued by CCU. This flag is not supported by interfaces CUxD and HVL.
  expert - Activate expert mode
  logEvents - Events are written into FHEM logfile if verbose is 4
  noEvents - Ignore events from CCU, do not update client device readings.
  noInitalUpdate - Do not update devices after RPC server started.
  noMulticalls - Do not execute RPC requests as multicalls (only BidCos-RF)
  queueEvents - Always write events into queue and send them asynchronously to FHEM. Frequency of event transmission to FHEM depends on attribute rpcConnTimeout.
  statistics - Count events per device sent by CCU
  


• rpcAcceptTimeout <seconds>
  Specify timeout for accepting incoming connections. Default is 1 second. Increase this value by 1 or 2 seconds on slow systems.


• rpcConnTimeout <seconds>
  Specify timeout of incoming CCU connections. Default is 1 second. Value must be greater than 0.


• rpcEventTimeout <seconds>
  Specify timeout for CCU events. Default is 0, timeout is ignored. If timeout occurs an event is triggered. If ccuflag reconnect is set in I/O device the RPC device tries to establish a new connection to the CCU.


• rpcMaxEvents <count>
  Specify maximum number of events read by FHEM during one I/O loop. If FHEM performance slows down decrease this value and increase attribute rpcQueueSize. Default value is 100. Value must be greater than 0.


• rpcMaxIOErrors <count>
  Specifiy maximum number of I/O errors allowed when sending events to FHEM before a message is written into FHEM log file. Default value is 100. Set this attribute to 0 to disable error counting.


• rpcPingCCU <interval>
  Ignored. Should be set in I/O device.


• rpcQueueSend <events>
  Maximum number of events sent to FHEM per accept loop. Default is 70. If set to 0 all events in queue are sent to FHEM. Transmission is stopped when an I/O error occurrs or specified number of events has been sent.


• rpcQueueSize <count>
  Specify maximum size of event queue. When this limit is reached no more CCU events are forwarded to FHEM. In this case increase this value or increase attribute rpcMaxEvents. Default value is 500.


• rpcReadTimeout <seconds>
  Wait the specified time for socket to become readable. Default value is 0.005 seconds. When using a CCU2 and parameter set definitions cannot be read (timeout), increase this value, i.e. to 0.01. Drawback: This could slow down the FHEM start time.


• rpcRetryRequest <retries>
  Number of times, failed RPC requests are repeated. Default is 1. Parameter retries must be in range 0-2.


• rpcServerAddr <ip-address>
  Set local IP address of RPC servers on FHEM system. If attribute is missing the corresponding attribute of I/O device (HMCCU device) is used or IP address is detected automatically. This attribute should be set if FHEM is running on a system with multiple network interfaces.


• rpcServerPort <port>
  Specify TCP port number used for calculation of real RPC server ports. If attribute is missing the corresponding attribute of I/O device (HMCCU device) is used. Default value is 5400.


• rpcStatistics <count>
  Specify amount of events after which statistic data is sent to FHEM. Default value is 500.


• rpcWriteTimeout <seconds>
  Wait the specified time for socket to become writeable. Default value is 0.001 seconds.

HMLAN

The HMLAN is the fhem module for the eQ-3 HomeMatic LAN Configurator.
A description on how to use hmCfgUsb can be found follwing the link.

The fhem module will emulate a CUL device, so the CUL_HM module can be used to define HomeMatic devices.

In order to use it with fhem you must disable the encryption first with the "HomeMatic Lan Interface Configurator"
(which is part of the supplied Windows software), by selecting the device, "Change IP Settings", and deselect "AES Encrypt Lan Communication".

This device can be used in parallel with a CCU and (readonly) with fhem. To do this:
• start the fhem/contrib/tcptee.pl program
• redirect the CCU to the local host
• disable the LAN-Encryption on the CCU for the Lan configurator
• set the dummy attribute for the HMLAN device in fhem




Define

define <name> HMLAN <ip-address>[:port]

port is 1000 by default.
If the ip-address is called none, then no device will be opened, so you can experiment without hardware attached.




Set

• hmPairForSec
• hmPairSerial
• reopen reconnect the device
• restart Restart the device
• reassignIDs
  Syncs the IDs between HMLAN and the FHEM list. Usually this is done automatically and only is recomended if there is a difference in counts.




Get

Get
• assignIDs
  Gibt eine Liste aller diesem IO zugewiesenen IOs aus.




Attributes

• addvaltrigger
• do_not_notify
• dummy
• logIDs
  enables selective logging of HMLAN messages. A list of HMIds or names can be entered, comma separated, which shall be logged.
  The attribute only allows device-IDs, not channel IDs. Channel-IDs will be modified to device-IDs automatically. all will log raw messages for all HMIds
  sys will log system related messages like keep-alive
  in order to enable all messages set "all,sys"
  
• loadLevel
  loadlevel will be mapped to reading vaues.
  0:low,30:mid,40:batchLevel,90:high,99:suspended
  the batchLevel value will be set to 40 if not entered. This is the level at which background message generation e.g. for autoReadReg will be stopped
  
• hmId
• hmKey / hmKey2-5
  AES keys for the HMLAN adapter.
  The key is converted to a hash. If a hash is given directly it is not converted but taken directly. Therefore the original key cannot be converted back
  
• hmProtocolEvents


• respTime
  Define max response time of the HMLAN adapter in seconds. Default is 1 sec.
  Longer times may be used as workaround in slow/instable systems or LAN configurations.
• wdTimer
  Time in sec to trigger HMLAN. Values between 5 and 25 are allowed, 25 is default.
  It is not recommended to change this timer. If problems are detected with
  HLMLAN disconnection it is advisable to resolve the root-cause of the problem and not symptoms.
• hmLanQlen
  defines queuelength of HMLAN interface. This is therefore the number of simultanously send messages. increasing values may cause higher transmission speed. It may also cause retransmissions up to data loss.
  Effects can be observed by watching protocol events
  1 - is a conservatibe value, and is default
  5 - is critical length, likely cause message loss



parameter

• assignedIDsCnt
  number of IDs that are assigned to HMLAN by FHEM. If the number reported by HMLAN differ it will be reported as 'reported'.
  It is recommended to resync HMLAN using the command 'assignIDs'.
• msgKeepAlive
  performance of keep-alive messages.
  dlyMax: maximum delay of sheduled message-time to actual message send.
  bufferMin: minimal buffer left to before HMLAN would likely disconnect due to missing keepAlive message. bufferMin will be reset to 30sec if attribut wdTimer is changed.
  if dlyMax is high (several seconds) or bufferMin goes to "0" (normal is 4) the system suffers on internal delays. Reasons for the delay might be explored. As a quick solution wdTimer could be decreased to trigger HMLAN faster.
• msgLoadCurrent
  Current transmit load of HMLAN. When capacity reaches 100% HMLAN stops sending and waits for reduction. See also: loadLevel
  
• msgLoadHistoryAbs
  Historical transmition load of IO.
• msgParseDly
  calculates the delay of messages in ms from send in HMLAN until processing in FHEM. It therefore gives an indication about FHEM system performance.



parameter and readings

• prot_disconnect
  recent HMLAN disconnect
• prot_init
  recent HMLAN init
• prot_keepAlive
  HMLAN disconnect likely do to slow keep-alive sending
• prot_ok
  recent HMLAN ok condition
• prot_timeout
  recent HMLAN timeout
• prot_Warning-HighLoad
  high load condition entered - HMLAN has about 10% performance left
• prot_ERROR-Overload
  overload condition - HMLAN will receive bu tno longer transmitt messages
• prot_Overload-released
  overload condition released - normal operation possible

HMS

Define
define <name> HMS <housecode>

<housecode> is a four digit hex number, corresponding to the address of the HMS device.
Examples:
define temp HMS 1234

Notes:

• Currently supported devices are the HMS100-T HMS100-TF HMS100-WD HMS100-MG HMS100-TFK HMS100-CO HMS100-FIT RM100-2 RM100-3
• The housecode of the HMS devices may change if the battery is renewed. In order to make life easier, you can define a "wildcard" device for each type of HMS device. First the real device-id will be checked, then the wildcard device id. The wildcards are:
  • 1000 for the HMS100-TF
  • 1001 for the HMS100-T
  • 1002 for the HMS100-WD
  • 1003 for the RM100-2
  • 1004 for the HMS100-TFK
  • 1006 for the HMS100-MG
  • 1008 for the HMS100-CO
  • 100e for the HMS100-FIT
• Some battery low notifications are not yet implemented (RM100, HMS100WD).
• Please test your installation before relying on the functionality.



Set
N/A

Get
N/A

Attributes
• ignore
• do_not_notify
• showtime
• IODev
• eventMap
• model (hms100-t hms100-tf hms100-wd hms100-mg hms100-co hms100-tfk hms100-fit rm100-2)
• readingFnAttributes

HMUARTLGW

HMUARTLGW provides support for the eQ-3 HomeMatic Wireless LAN Gateway (HM-LGW-O-TW-W-EU) and the eQ-3 HomeMatic UART module (HM-MOD-UART), which is part of the HomeMatic wireless module for the Raspberry Pi (HM-MOD-RPI-PCB).


Define
define <name> HMUARTLGW <device>

The <device>-parameter depends on the device-type:
• HM-MOD-UART: <device> specifies the serial port to communicate with. The baud-rate is fixed at 115200 and does not need to be specified.
  If the HM-MOD-UART is connected to the network by a serial bridge, the connection has to be defined in an URL-like format (uart://ip:port).
• HM-LGW-O-TW-W-EU: <device> specifies the IP address or hostname of the gateway, optionally followed by : and the port number of the BidCoS-port (default when not specified: 2000).


Examples:

• Local HM-MOD-UART at /dev/ttyAMA0:
  define myHmUART HMUARTLGW /dev/ttyAMA0
   
• LAN Gateway at 192.168.42.23:
  define myHmLGW HMUARTLGW 192.168.42.23
   
• Remote HM-MOD-UART using socat on a Raspberry Pi:
  define myRemoteHmUART HMUARTLGW uart://192.168.42.23:12345
  
  Remote Raspberry Pi:
  $ socat TCP4-LISTEN:12345,fork,reuseaddr /dev/ttyAMA0,raw,echo=0,b115200



Set

• close
  Closes the connection to the device.
• hmPairForSec
• hmPairSerial
• open
  Opens the connection to the device and initializes it.
• reopen
  Reopens the connection to the device and reinitializes it.
• restart
  Reboots the device.
• updateCoPro </path/to/firmware.eq3>
  Update the coprocessor-firmware (reading D-firmware) from the supplied file. Source for firmware-images (version 1.4.1, official eQ-3 repository):
  
  • HM-MOD-UART: coprocessor_update.eq3 (version 1.4.1)
  • HM-LGW-O-TW-W-EU: coprocessor_update_hm_only.eq3 (version 1.4.1)
    Please also make sure that D-LANfirmware is at least at version 1.1.5. To update to this version, use the eQ-3 CLI tools (see wiki) or use the eQ-3 netfinder with this firmware image: hm-lgw-o-tw-w-eu_update.eq3
    Do not flash hm-lgw-o-tw-w-eu_update.eq3 with updateCoPro!



Get

• assignIDs
  Returns the HomeMatic devices currently assigned to this IO-device.

Attributes
• csmaCa
  Enable or disable CSMA/CA (Carrier sense multiple access with collision avoidance), also known as listen-before-talk.
  Default: 0 (disabled)
• dummy
  Do not interact with the device at all, only define it.
  Default: not set
• dutyCycle
  Enable or disable the duty-cycle check (1% rule) performed by the wireless module.
  Disabling this might be illegal in your country, please check with local regulations!
  Default: 1 (enabled)
• hmId
• hmKey
• hmKey2
• hmKey3
• lgwPw
  AES password for the eQ-3 HomeMatic Wireless LAN Gateway. The default password is printed on the back of the device (but can be changed by the user). If AES communication is enabled on the LAN Gateway (default), this attribute has to be set to the correct value or communication will not be possible. In addition, the perl-module Crypt::Rijndael (which provides the AES cipher) must be installed.
• loadEvents
  Enables logging of the wireless load (in percent of the allowed maximum sending-time) of the interface. Default: 0 (disabled)
• logIDs
  Enables selective logging of HMUARTLGW messages. A list of comma separated HMIds or HM device names/channel names can be entered which shall be logged.
  
  • all: will log raw messages for all HMIds
  • sys: will log system related messages like keep-alive
  In order to enable all messages set: all,sys
• qLen
  Maximum number of commands in the internal queue of the HMUARTLGW module. New commands when the queue is full are dropped. Each command has a maximum lifetime of 3s when active, so the worst-case delay of a command is qLen * 3s (3 minutes with default settings).
  Default: 60

HMinfo

HMinfo is a module to support getting an overview of eQ-3 HomeMatic devices as defines in CUL_HM.

Status information and counter
HMinfo gives an overview on the CUL_HM installed base including current conditions. Readings and counter will not be updated automatically due to performance issues.
Command update must be used to refresh the values.

set hm update


Webview of HMinfo providee details, basically counter about how many CUL_HM entities experience exceptional conditions. It contains
• Action Detector status
• CUL_HM related IO devices and condition
• Device protocol events which are related to communication errors
• count of certain readings (e.g. battery) and conditions - attribut controlled
• count of error condition in readings (e.g. overheat, motorErr) - attribut controlled

It also allows some HM wide commands such as store all collected register settings.

Commands are executed on all HM entities. If applicable and evident execution is restricted to related entities. e.g. rssi is executed on devices only since channels do not support rssi values.

Filter
can be applied as following:

set <name> <cmd> <filter> [<param>]
whereby filter has two segments, typefilter and name filter
[-dcasev] [-f <filter>]

filter for types

• d - device :include devices
• c - channels :include channels
• v - virtual :supress fhem virtual
• p - physical :supress physical
• a - aktor :supress actor
• s - sensor :supress sensor
• e - empty :include results even if requested fields are empty
• 2 - alias :display second name alias
and/or filter for names:

• -f <filter> :regexp to filter entity names
Example:

set hm param -d -f dim state # display param 'state' for all devices whos name contains dim
set hm param -c -f ^dimUG$ peerList # display param 'peerList' for all channels whos name is dimUG
set hm param -dcv expert # get attribut expert for all channels,devices or virtuals




Define

define <name> HMinfo
Just one entity needs to be defined without any parameter.




Get

• models
  list all HM models that are supported in FHEM
• param [filter] <name> <name>...
  returns a table of parameter values (attribute, readings,...) for all entities as a table
• register [filter]
  provides a tableview of register of an entity
• regCheck [filter]
  performs a consistency check on register readings for completeness
• peerCheck [filter]
  performs a consistency check on peers. If a peer is set in a channel it will check wether the peer also exist on the opposit side.
• peerUsg [filter]
  provides a cross-reference on peerings and assigned template information
• peerXref [filter]
  provides a cross-reference on peerings, a kind of who-with-who summary over HM
• configCheck [filter]
  performs a consistency check of HM settings. It includes regCheck and peerCheck
• configChkResult
  returns the results of a previous executed configCheck
• templateList [<name>]
  list defined templates. If no name is given all templates will be listed
  
• configInfo [<name>]
  information to getConfig results
  
• templateUsg <template> [sortPeer|sortTemplate]
  templare usage
  template filters the output
  templateUsgG (for all devices)
• msgStat [filter]
  statistic about message transferes over a week
  
• protoEvents [filter]
  important view about pending commands and failed executions for all devices in a single table.
  Consider to clear this statistic use clear msgEvents.
  
• rssi [filter]
  statistic over rssi data for HM entities.
  
• templateChk [filter] <template> <peer:[long|short]> [<param1> ...]
  verifies if the register-readings comply to the template
  Parameter are identical to templateSet
  The procedure will check if the register values match the ones provided by the template
  If no peer is necessary use none to skip this entry
  Example to verify settings
  
  set hm templateChk -f RolloNord BlStopUpLg none 1 2 # RolloNord, no peer, parameter 1 and 2 given
set hm templateChk -f RolloNord BlStopUpLg peerName:long # RolloNord peerName, long only
set hm templateChk -f RolloNord BlStopUpLg peerName # RolloNord peerName, long and short
set hm templateChk -f RolloNord BlStopUpLg peerName:all # RolloNord peerName, long and short
set hm templateChk -f RolloNord BlStopUpLg all:long # RolloNord any peer, long only
set hm templateChk -f RolloNord BlStopUpLg all # RolloNord any peer,long and short
set hm templateChk -f Rollo.* BlStopUpLg all # each Rollo* any peer,long and short
set hm templateChk BlStopUpLg # each entities
set hm templateChk # all assigned templates
set hm templateChk sortTemplate # all assigned templates sortiert nach Template
set hm templateChk sortPeer # all assigned templates sortiert nach Peer

• showTimer
  show all timer currently running at this point in time.
  

Set

Even though the commands are a get funktion they are implemented as set to allow simple web interface usage

• update
  updates HM status counter.
• autoReadReg [filter]
  schedules a read of the configuration for the CUL_HM devices with attribut autoReadReg set to 1 or higher.
• cmdRequestG
  issues a status request to update the system and performs access check to devices
  ping: for one channel per CUL_HM device
  status: for all channels that suport statusRequest
  Ping will generate a message to the device. If not answered the device is unaccessible. Check protState for errors in case.
• clear [filter] [msgEvents|readings|msgStat|register|rssi]
  executes a set clear ... on all HM entities
  
  • protocol relates to set clear msgEvents
  • set clear msgEvents for all device with protocol errors
  • readings relates to set clear readings
  • rssi clears all rssi counters
  • msgStat clear HM general message statistics
  • register clears all register-entries in readings
  clearG (for all devices)
• saveConfig [filter] [<file>]
  performs a save for all HM register setting and peers. See CUL_HM saveConfig.
  purgeConfig will be executed automatically if the stored filesize exceeds 1MByte.
  
• archConfig [filter] [<file>]
  performs saveConfig for entities that appeare to have achanged configuration. It is more conservative that saveConfig since incomplete sets are not stored.
  Option -a force an archieve for all devices that have a complete set of data
  
• loadConfig [filter] [<file>]
  loads register and peers from a file saved by saveConfig.
  It should be used carefully since it will add data to FHEM which cannot be verified. No readings will be replaced, only missing readings will be added. The command is mainly meant to be fill in readings and register that are hard to get. Those from devices which only react to config may not easily be read.
  Therefore it is strictly up to the user to fill valid data. User should consider using autoReadReg for devices that can be read.
  The command will update FHEM readings and attributes. It will not reprogramm any device.
• purgeConfig [filter] [<file>]
  purge (reduce) the saved config file. Due to the cumulative storage of the register setting purge will use the latest stored readings and remove older one. See CUL_HM saveConfig.
• verifyConfig [filter] [<file>]
  Compare date in config file to the currentactive data and report differences. Possibly usable with a known-good configuration that was saved before. It may make sense to purge the config file before. See CUL_HM purgeConfig.


• tempList [filter] [save|restore|verify|status|genPlot] [<file>]
  this function supports handling of tempList for thermstates. It allows templists to be saved in a separate file, verify settings against the file and write the templist of the file to the devices.
  
  • save saves tempList readings of the system to the file.
    Note that templist as available in FHEM is put to the file. It is up to the user to make sure the data is actual
    Storage is not cumulative - former content of the file will be removed
  • restore available templist as defined in the file are written directly to the device
  • verify file data is compared to readings as present in FHEM. It does not verify data in the device - user needs to ensure actuallity of present readings
  • status gives an overview of templates being used by any CUL_HM thermostat. It alls showes templates being defined in the relevant files.
    
  • genPlot generates a set of records to display templates graphicaly.
    Out of the given template-file it generates a .log extended file which contains log-formated template data. timestamps are set to begin Year 2000.
    A prepared .gplot file will be added to gplot directory.
    Logfile-entity _Log will be added if not already present. It is necessary for plotting.
    SVG-entity _SVG will be generated if not already present. It will display the graph.
    
    
  • file name of the file to be used. Default: tempList.cfg
  
  
  • filename is the name of the file to be used. Default ist tempList.cfg
  File example
  
  entities:HK1_Climate,HK2_Clima
tempListFri>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 14.0
tempListMon>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
tempListSun>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
tempListThu>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
tempListTue>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 15.0
tempListWed>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
entities:hk3_Climate
tempListFri>06:00 17.0 12:00 21.0 23:00 20.0 24:00 19.5
tempListMon>06:00 17.0 12:00 21.0 23:00 20.0 24:00 17.0
tempListSat>06:00 17.0 12:00 21.0 23:00 20.0 24:00 17.0
tempListSun>06:00 17.0 12:00 21.0 23:00 20.0 24:00 17.0
tempListThu>06:00 17.0 12:00 21.0 23:00 20.0 24:00 17.0
tempListTue>06:00 17.0 12:00 21.0 23:00 20.0 24:00 17.0
tempListWed>06:00 17.0 12:00 21.0 23:00 20.0 24:00 17.0

  File keywords
  
  • entities comma separated list of entities which refers to the temp lists following. The actual entity holding the templist must be given - which is channel 04 for RTs or channel 02 for TCs
  • tempList... time and temp couples as used in the set tempList commands
  • simDev -model- simulate a device
  tempListG (for all devices)
  


• cpRegs <src:peer> <dst:peer>
  allows to copy register, setting and behavior of a channel to another or for peers from the same or different channels. Copy therefore is allowed intra/inter device and intra/inter channel.
  src:peer is the source entity. Peer needs to be given if a peer behabior beeds to be copied
  dst:peer is the destination entity.
  Example
  
  set hm cpRegs blindR blindL # will copy all general register (list 1)for this channel from the blindR to the blindL entity. This includes items like drive times. It does not include peers related register (list 3/4)
set hm cpRegs blindR:Btn1 blindL:Btn2 # copy behavior of Btn1/blindR relation to Btn2/blindL
set hm cpRegs blindR:Btn1 blindR:Btn2 # copy behavior of Btn1/blindR relation to Btn2/blindR, i.e. inside the same Actor

  
  Restrictions:
  
  cpRegs will not add any peers or read from the devices. It is up to the user to read register in advance
  cpRegs is only allowed between identical models
  cpRegs expets that all readings are up-to-date. It is up to the user to ensure data consistency.
  
• templateDef <name> <param> <desc> <reg1:val1> [<reg2:val2>] ...
  define a template.
  param gives the names of parameter necesary to execute the template. It is template dependant and may be onTime or brightnesslevel. A list of parameter needs to be separated with colon
  param1:param2:param3
  if del is given as parameter the template is removed
  desc shall give a description of the template
  reg:val is the registername to be written and the value it needs to be set to.
  In case the register is from link set and can destinguist between long and short it is necessary to leave the leading sh or lg off.
  if parameter are used it is necessary to enter p. as value with p0 first, p1 second parameter
  Example
  
  set hm templateDef SwOnCond level:cond "my description" CtValLo:p0 CtDlyOn:p1 CtOn:geLo
set hm templateDef SwOnCond del # delete a template
set hm templateDef SwOnCond fromMaster <masterChannel> <peer:[long|short]># define a template with register as of the example
set hm templateDef SwOnCond fromMaster myChannel peerChannel:long #

• templateSet <entity> <template> <peer:[long|short]> [<param1> ...]
  sets a bunch of register accroding to a given template. Parameter may be added depending on the template setup.
  templateSet will collect and accumulate all changes. Finally the results are written streamlined.
  entity: peer is the source entity. Peer needs to be given if a peer behabior beeds to be copied
  template: one of the programmed template
  peer: [long|short]:if necessary a peer needs to be given. If no peer is used enter '0'. with a peer it should be given whether it is for long or short keypress
  param: number and meaning of parameter depends on the given template
  Example could be (templates not provided, just theoretical)
  
  set hm templateSet Licht1 staircase FB1:short 20
set hm templateSet Licht1 staircase FB1:long 100

  Restrictions:
  
  User must ensure to read configuration prior to execution.
  templateSet may not setup a complete register block but only a part if it. This is up to template design.
  
  
• templateDel <entity> <template> <peer:[long|short]> ]
  remove a template installed by templateSet
  
• templateExe <template>
  executes the register write once again if necessary (e.g. a device had a reset)
  
• x-deviceReplace <oldDevice> <newDevice>
  replacement of an old or broken device with a replacement. The replacement needs to be compatible - FHEM will check this partly. It is up to the user to use it carefully.
  The command needs to be executed twice for safety reasons. The first call will return with CAUTION remark. Once issued a second time the old device will be renamed, the new one will be named as the old one. Then all peerings, register and templates are corrected as best as posible.
  NOTE: once the command is executed devices will be reconfigured. This cannot be reverted automatically.
  Replay of teh old confg-files will NOT restore the former configurations since also registers changed! Exception: proper and complete usage of templates!
  In case the device is configured using templates with respect to registers a verification of the procedure is very much secure. Otherwise it is up to the user to supervice message flow for transmission failures.
  





Attributes

• sumStatus
  Warnings: list of readings that shall be screend and counted based on current presence. I.e. counter is the number of entities with this reading and the same value. Readings to be searched are separated by comma.
  Example:
  
  attr hm sumStatus battery,sabotageError

  will cause a reading like
  W_sum_battery ok:5 low:3
  W_sum_sabotageError on:1
  
  Note: counter with '0' value will not be reported. HMinfo will find all present values autonomously
  Setting is meant to give user a fast overview of parameter that are expected to be system critical
  
• sumERROR
  Similar to sumStatus but with a focus on error conditions in the system. Here user can add readingvalues that are not displayed. I.e. the value is the good-condition that will not be counted.
  This way user must not know all error values but it is sufficient to supress known non-ciritical ones.
  Example:
  
  attr hm sumERROR battery:ok,sabotageError:off,overheat:off,Activity:alive:unknown

  will cause a reading like
  
  ERR_battery low:3
ERR_sabotageError on:1
ERR_overheat on:3
ERR_Activity dead:5

• autoUpdate
  retriggers the command update periodically.
  Example:
  
  attr hm autoUpdate 00:10

  will trigger the update every 10 min
  
• autoArchive
  if set fhem will update the configFile each time the new data is available. The update will happen with autoUpdate. It will not work it autoUpdate is not used.
  see also archConfig
  
• hmAutoReadScan
  defines the time in seconds CUL_HM tries to schedule the next autoRead from the queue. Despite this timer FHEM will take care that only one device from the queue will be handled at one point in time. With this timer user can stretch timing even further - to up to 300sec min delay between execution.
  Setting to 1 still obeys the "only one at a time" prinzip.
  Note that compressing will increase message load while stretch will extent waiting time.
  
• hmIoMaxDly
  max time in seconds CUL_HM stacks messages if the IO device is not ready to send. If the IO device will not reappear in time all command will be deleted and IOErr will be reported.
  Note: commands will be executed after the IO device reappears - which could lead to unexpected activity long after command issue.
  default is 60sec. max value is 3600sec
  
• configDir
  default directory where to store and load configuration files from. This path is used as long as the path is not given in a filename of a given command.
  It is used by commands like tempList or saveConfig
  
• configFilename
  default filename used by saveConfig, purgeConfig, loadConfig
  verifyConfig
  
• configTempFile<;configTempFile2><;configTempFile3>
  Liste of Templfiles (weekplan) which are considered in HMInfo and CUL_HM
  Files are comma separated. The first file is default. Its name may be skipped when setting a tempalte.
  
• hmManualOper
  set to 1 will prevent any automatic operation, update or default settings in CUL_HM.
  
• hmDefaults
  set default params for HM devices. Multiple attributes are possible, comma separated.
  example:
  attr hm hmDefaults hmProtocolEvents:0_off,rssiLog:0
  
• verbCULHM
  set verbose logging for a special action for any CUL_HM entity.
  allSet: all set commands to be executed.
  allGet: all get requests to be executed.
  
• autoLoadArchive
  if set the register config will be loaded after reboot automatically. See loadConfig for details
  

Variables
• I_autoReadPend: Info:list of entities which are queued to retrieve config and status. This is typically scheduled thru autoReadReg
• ERR___rssiCrit: Error:list of devices with RSSI reading n min level
• W_unConfRegs: Warning:list of entities with unconfirmed register changes. Execute getConfig to clear this.
• I_rssiMinLevel: Info:counts of rssi min readings per device, clustered in blocks
• ERR__protocol: Error:count of non-recoverable protocol events per device. Those events are NACK, IOerr, ResendFail, CmdDel, CmdPend.
  Counted are the number of device with those events, not the number of events!
• ERR__protoNames: Error:name-list of devices with non-recoverable protocol events
• I_HM_IOdevices: Info:list of IO devices used by CUL_HM entities
• I_actTotal: Info:action detector state, count of devices with ceratin states
• ERRactNames: Error:names of devices that are not alive according to ActionDetector
• C_sumDefined: Count:defined entities in CUL_HM. Entites might be count as device AND channel if channel funtion is covered by the device itself. Similar to virtual
• ERR_<reading>: Error:count of readings as defined in attribut sumERROR that do not match the good-content.
• ERR_names: Error:name-list of entities that are counted in any ERR_<reading> W_sum_<reading>: count of readings as defined in attribut sumStatus.
Example:

ERR___rssiCrit LightKittchen,WindowDoor,Remote12
ERR__protocol NACK:2 ResendFail:5 CmdDel:2 CmdPend:1
ERR__protoNames LightKittchen,WindowDoor,Remote12,Ligth1,Light5
ERR_battery: low:2;
ERR_names: remote1,buttonClara,
I_rssiMinLevel 99>:3 80<:0 60<:7 59<:4
W_sum_battery: ok:5;low:2;
W_sum_overheat: off:7;
C_sumDefined: entities:23 device:11 channel:16 virtual:5;


HMtemplate

Edit templates for HM entities. Programming register of HM devices can be bundled to templates and then being assigned to the devices. The editor might be instantiated ony once. Templates will be organized, handled and loaded in HMinfo.
The editor allowes to define, edit, copy and assign and delete templates.
Required: HMinfo needs to be instantiated. Set
following commands are available:
• defTmpl <name>
  Define a new template. Procedure is given in internals once the command is issued.
  
• tpl_typechoose whether the template will be:
  • basic not peer related register only
  • peer-both only peer related register, setting short and long press reaction in one template
  • peer-Short only peer related register, will define one short or long press behavior
  • peer-Long only peer related register, will define one short or long press behavior
• tpl_sourceselect the entity which will be used as master for the template
• tpl_peerselect the peer of the entity which will be used as master for the template. This is only necessary for types that require peers.
• tpl_paramsif the template shall have parameter those need to be defined next.
  parameter will allow to use one template with selected registers to be defined upon appling to the entity.
• tpl_descriptionenter a free text to describe what the entity is about
• tpl_Rega list of attributes will be available after all attribtes above are set. Not edit them. Delete registers which are not used for the template, edit the values as desired.
• savesave the template. After that the template is defined. saveas will allow to define the template with a different name.
• delete <name>
  Delete an existing template
  
• edit <name>
  Edit an existing template. Change register, parameter and description by change the attributes. See also defTmpl
  saveAs can be used to create a copy of the template.
  
• select <name>
  Apply an existing template to a entity
  Once the command is issued it is necessary to select the entity, peer and short/long which the entity shall be applied to.
  If the template has parameter the value needs to be set.
  Finally assign the template to teh entity.
• dismiss
  reset HMtemplate and come back to init status
• assign
  assign a template to an entity
• unassign <entity> <peer>
  unassign an entity from an entity
• save, saveAs
  save a template once it is defined

HOMBOT

HOMBOT - LG Homebot robotic vacuum cleaner
After successfully hacking (WiFi-Mod) your Hombot, this Modul enables you to integrate your Hombot to FHEM. The Connection-Interface between FHEM and Hombot is served by Luigi HTTP Server. With this Module, the following is possible:
• Readings about the Status will be saved.
• Choice of cleaning mode
• Start cleaning
• Stop cleaning
• Return to Homebase
• Assign Nickname
• Schedule Weekprogram
• Activate 'Repeat' and 'Turbo'

You need to set up the device for the Hombot like this.

Define

define <name> HOMBOT <IP-ADRESS>

Example:

define Roberta HOMBOT 192.168.0.23


This command creates a HOMBOT-Device in room HOMBOT. The parameter <IP-ADRESS> determines the IP-Address of your Hombot.
The standard query interval is 180 seconds. You can change it with attribute interval. The interval is dynamic in dependency of the workstatus. For example, the status WORKING is 30 seconds.



The first Readings should already appear after setting up the Device entity.


Readings
• at_* - Reading for the week schedule. Start time for respective day.
• batteryPercent - Battery status in percent %
• cleanMode - Current cleanmode
• cpu_* - Information about CPU load
• currentBumping - Count of collisions with obstacles
• firmware - current installed firmware version
• hombotState - Status of Hombot
• lastClean - Date and Time of last cleaning
• lastSetCommandError - last error message from set command
• lastSetCommandState - last status from set command. Command (un)successfully send
• lastStatusRequestError - last error message from statusRequest command
• lastStatusRequestState - last status from statusRequest command. Command (un)successfully send
• luigiSrvVersion - Version of Luigi HTTP Servers of Hombot
• nickname - Name of Hombot
• num* - Previous started and ended cleanings in corresponding modes
• repeat - Cleaning will repeated Yes/No
• state - Module status
• turbo - Turbo active Yes/No


Set
• cleanMode - set cleaning mode (ZZ-ZigZag / SB-Cell by Cell / SPOT-Spiralcleaning
• cleanStart - Start cleaning
• homing - Stop cleaning and move Hombot back to Base
• nickname - Sets HomBot's Nickname. Not visible in Reading until restart of Luigi-Server or HomBot itself.
• pause - Will pause the cleaning process
• repeat - Repeat cleaning? (true/false)
• schedule - Set of Week schedule. For example, set Roberta schedule Mo=13:30 Di= Mi=14:00,ZZ Do=15:20 Fr= Sa=11:20 So= therefore you can also add modes!
• statusRequest - Requests new Statusreport from Device
• turbo - Activation of Turbomode (true/false)

HOMEMODE

HOMEMODE is designed to represent the overall home state(s) in one device.
It uses the attribute userattr extensively.
It has been optimized for usage with homebridge as GUI.
You can also configure CMDs to be executed on specific events.
There is no need to create notify(s) or DOIF(s) to achieve common tasks depending on the home state(s).
It's also possible to control ROOMMATE/GUEST/PET devices states depending on their associated presence device.
If the RESIDENTS device is on state home, the HOMEMODE device can automatically change its mode depending on the local time (morning,day,afternoon,evening,night)
There is also a daytime reading and associated HomeCMD attributes that will execute the HOMEMODE state CMDs independend of the presence of any RESIDENT.
A lot of placeholders are available for usage within the HomeCMD or HomeText attributes (see Placeholders).
All your energy and power measuring sensors can be added and calculated total readings for energy and power will be created.
You can also add your local outside temperature and humidity sensors and you'll get ice warning e.g.
If you also add your Weather device you'll also get short and long weather informations and weather forecast.
You can monitor added contact and motion sensors and execute CMDs depending on their state.
A simple alarm system is included, so your contact and motion sensors can trigger alarms depending on the current alarm mode.
A lot of customizations are possible, e.g. special event (holiday) calendars and locations.


General information:

• The HOMEMODE device is refreshing itselfs every 5 seconds by calling HOMEMODE_GetUpdate and subfunctions.
  This is the reason why some automations (e.g. daytime or season) are delayed up to 4 seconds.
  All automations triggered by external events (other devices monitored by HOMEMODE) and the execution of the HomeCMD attributes will not be delayed.
• Each created timer will be created as at device and its name will start with 'atTmp_' and end with '_<name of your HOMEMODE device>'. You may list them with 'list TYPE=at:FILTER=NAME=atTmp_.*_<name of your HOMEMODE device>'.
• Seasons can also be adjusted (date and text) in attribute HomeSeasons
• There's a special function, which you may use, which is converting given minutes (up to 5999.99) to a timestamp that can be used for creating at devices.
  This function is called HOMEMODE_hourMaker and the only value you need to pass is the number in minutes with max. two decimal places.
• Each set command and each updated reading of the HOMEMODE device will create an event within FHEM, so you're able to create additional notify or DOIF devices if needed.



A german Wiki page is also available at https://wiki.fhem.de/wiki/Modul_HOMEMODE. There you can find lots of example code.




define [optional]

define <name> HOMEMODE

define <name> HOMEMODE [RESIDENTS-MASTER-DEVICE]




set <required> [optional]

• anyoneElseAtHome <on/off>
  turn this on if anyone else is alone at home who is not a registered resident
  e.g. an animal or unregistered guest
  if turned on the alarm mode will be set to armhome instead of armaway while leaving, if turned on after leaving the alarm mode will change from armaway to armhome, e.g. to disable motion sensors alerts
  placeholder %AEAH% is available in all HomeCMD attributes
• deviceDisable <DEVICE>
  disable HOMEMODE integration for given device
  placeholder %DISABLED% is available in all HomeCMD attributes
  placeholders %DEVICE% and %ALIAS% are available in HomeCMDdeviceDisable attribute
• deviceEnable <DEVICE>
  enable HOMEMODE integration for given device
  placeholder %DISABLED% is available in all HomeCMD attributes
  placeholders %DEVICE% and %ALIAS% are available in HomeCMDdeviceEnable attribute
• dnd <on/off>
  turn 'do not disturb' mode on or off
  e.g. to disable notification or alarms or, or, or...
  placeholder %DND% is available in all HomeCMD attributes
• dnd-for-minutes <MINUTES>
  turn 'do not disturb' mode on for given minutes
  will return to the current (daytime) mode
• location <arrival/home/bed/underway/wayhome>
  switch to given location manually
  placeholder %LOCATION% is available in all HomeCMD attributes
• mode <morning/day/afternoon/evening/night/gotosleep/asleep/absent/gone/home>
  switch to given mode manually
  placeholder %MODE% is available in all HomeCMD attributes
• modeAlarm <armaway/armhome/armnight/confirm/disarm>
  switch to given alarm mode manually
  placeholder %MODEALARM% is available in all HomeCMD attributes
• modeAlarm-for-minutes <armaway/armhome/armnight/disarm> <MINUTES>
  switch to given alarm mode for given minutes
  will return to the previous alarm mode
• panic <on/off>
  turn panic mode on or off
  placeholder %PANIC% is available in all HomeCMD attributes
• updateHomebridgeMapping
  will update the attribute homebridgeMapping of the HOMEMODE device depending on the available informations
• updateInternalsForce
  will force update all internals of the HOMEMODE device
  use this if you just reload this module after an update or if you made changes on any HOMEMODE monitored device, e.g. after adding residents/guest or after adding new sensors with the same devspec as before



get <required> [optional]

• contactsOpen <all/doorsinside/doorsoutside/doorsmain/outside/windows>
  get a list of all/doorsinside/doorsoutside/doorsmain/outside/windows open contacts
  placeholders %OPEN% (open contacts outside) and %OPENCT% (open contacts outside count) are available in all HomeCMD attributes
• devicesDisabled
  get new line separated list of currently disabled devices
  placeholder %DISABLED% is available in all HomeCMD attributes
• mode
  get current mode
  placeholder %MODE% is available in all HomeCMD attributes
• modeAlarm
  get current modeAlarm
  placeholder %MODEALARM% is available in all HomeCMD attributes
• publicIP
  get the public IP address
  placeholder %IP% is available in all HomeCMD attributes
• sensorsTampered
  get a list of all tampered sensors
  placeholder %TAMPERED% is available in all HomeCMD attributes
• weather <long/short>
  get weather information in given format
  please specify the outputs in attributes HomeTextWeatherLong and HomeTextWeatherShort
  placeholders %WEATHER% and %WEATHERLONG% are available in all HomeCMD attributes
• weatherForecast [DAY]
  get weather forecast for given day
  if DAY is omitted the forecast for tomorrow (2) will be returned
  please specify the outputs in attributes HomeTextWeatherForecastToday, HomeTextWeatherForecastTomorrow and HomeTextWeatherForecastInSpecDays
  placeholders %FORECAST% (tomorrow) and %FORECASTTODAY% (today) are available in all HomeCMD attributes



Attributes

• HomeAdvancedDetails
  show more details depending on the monitored devices
  value detail will only show advanced details in detail view, value both will show advanced details also in room view, room will show advanced details only in room view
  values: none, detail, both, room
  default: none
• HomeAdvancedUserAttr
  more HomeCMD userattr will be provided
  additional attributes for each resident and each calendar event
  values: 0 or 1
  default: 0
• HomeAtTmpRoom
  add this room to temporary at(s) (generated by HOMEMODE)
  default:
• HomeAutoAlarmModes
  set modeAlarm automatically depending on mode
  if mode is set to 'home', modeAlarm will be set to 'disarm'
  if mode is set to 'absent', modeAlarm will be set to 'armaway'
  if mode is set to 'asleep', modeAlarm will be set to 'armnight'
  modeAlarm 'home' can only be set manually
  values 0 or 1, value 0 disables automatically set modeAlarm
  default: 1
• HomeAutoArrival
  set resident's location to arrival (on arrival) and after given minutes to home
  values from 0 to 5999.9 in minutes, value 0 disables automatically set arrival
  default: 0
• HomeAutoAsleep
  set user from gotosleep to asleep after given minutes
  values from 0 to 5999.9 in minutes, value 0 disables automatically set asleep
  default: 0
• HomeAutoAwoken
  force set resident from asleep to awoken, even if changing from alseep to home
  after given minutes awoken will change to home
  values from 0 to 5999.9 in minutes, value 0 disables automatically set awoken after asleep
  default: 0
• HomeAutoDaytime
  daytime depending home mode
  values 0 or 1, value 0 disables automatically set daytime
  default: 1
• HomeAutoPresence
  automatically change the state of residents between home and absent depending on their associated presence device
  values 0 or 1, value 0 disables auto presence
  default: 0
• HomeAutoPresenceSuppressState
  suppress state(s) for HomeAutoPresence (p.e. gotosleep|asleep)
  if set this/these state(s) of a resident will not affect the residents to change to absent by its presence device
  p.e. for misteriously disappearing presence devices in the middle of the night
  default:
• HomeCMDalarmSmoke
  cmds to execute on any smoke alarm state
• HomeCMDalarmSmoke-<on/off>
  cmds to execute on smoke alarm state on/off
• HomeCMDalarmTampered
  cmds to execute on any tamper alarm state
• HomeCMDalarmTampered-<on/off>
  cmds to execute on tamper alarm state on/off
• HomeCMDalarmTriggered
  cmds to execute on any alarm state
• HomeCMDalarmTriggered-<on/off>
  cmds to execute on alarm state on/off
• HomeCMDanyoneElseAtHome
  cmds to execute on any anyoneElseAtHome state
• HomeCMDanyoneElseAtHome-<on/off>
  cmds to execute on anyoneElseAtHome state on/off
• HomeCMDcontact
  cmds to execute if any contact has been triggered (open/tilted/closed)
• HomeCMDbattery
  cmds to execute on any battery change of a battery sensor
• HomeCMDbatteryLow
  cmds to execute if any battery sensor has low battery
• HomeCMDbatteryNormal
  cmds to execute if any battery sensor returns to normal battery
• HomeCMDcontactClosed
  cmds to execute if any contact has been closed
• HomeCMDcontactOpen
  cmds to execute if any contact has been opened
• HomeCMDcontactDoormain
  cmds to execute if any contact of type doormain has been triggered (open/tilted/closed)
• HomeCMDcontactDoormainClosed
  cmds to execute if any contact of type doormain has been closed
• HomeCMDcontactDoormainOpen
  cmds to execute if any contact of type doormain has been opened
• HomeCMDcontactOpenWarning1
  cmds to execute on first contact open warning
• HomeCMDcontactOpenWarning2
  cmds to execute on second (and more) contact open warning
• HomeCMDcontactOpenWarningLast
  cmds to execute on last contact open warning
• HomeCMDdaytime
  cmds to execute on any daytime change
• HomeCMDdaytime-<%DAYTIME%>
  cmds to execute on specific day time change
• HomeCMDdeviceDisable
  cmds to execute on set HOMEMODE deviceDisable
• HomeCMDdeviceEnable
  cmds to execute on set HOMEMODE deviceEnable
• HomeCMDdnd
  cmds to execute on any dnd state
• HomeCMDdnd-<on/off>
  cmds to execute on dnd state on/off
• HomeCMDevent
  cmds to execute on each calendar event
• HomeCMDevent-<%CALENDAR%>-each
  cmds to execute on each event of the calendar
• HomeCMDevent-<%CALENDAR%>-<%EVENT%>-begin
  cmds to execute on start of a specific calendar event
• HomeCMDevent-<%CALENDAR%>-<%EVENT%>-end
  cmds to execute on end of a specific calendar event
• HomeCMDfhemDEFINED
  cmds to execute on any defined device
• HomeCMDfhemINITIALIZED
  cmds to execute on fhem start
• HomeCMDfhemSAVE
  cmds to execute on fhem save
• HomeCMDfhemUPDATE
  cmds to execute on fhem update
• HomeCMDicewarning
  cmds to execute on any ice warning state
• HomeCMDicewarning-<on/off>
  cmds to execute on ice warning state on/off
• HomeCMDlocation
  cmds to execute on any location change of the HOMEMODE device
• HomeCMDlocation-<%LOCATION%>
  cmds to execute on specific location change of the HOMEMODE device
• HomeCMDlocation-resident
  cmds to execute on any location change of any RESIDENT/GUEST/PET device
• HomeCMDlocation-<%LOCATIONR%>-resident
  cmds to execute on specific location change of any RESIDENT/GUEST/PET device
• HomeCMDlocation-<%LOCATIONR%>-<%RESIDENT%>
  cmds to execute on specific location change of a specific RESIDENT/GUEST/PET device
• HomeCMDmode
  cmds to execute on any mode change of the HOMEMODE device
• HomeCMDmode-absent-belated
  cmds to execute belated to absent
  belated time can be adjusted with attribute 'HomeModeAbsentBelatedTime'
• HomeCMDmode-<%MODE%>
  cmds to execute on specific mode change of the HOMEMODE device
• HomeCMDmode-<%MODE%>-resident
  cmds to execute on specific mode change of the HOMEMODE device triggered by any resident
• HomeCMDmode-<%MODE%>-<%RESIDENT%>
  cmds to execute on specific mode change of the HOMEMODE device triggered by a specific resident
• HomeCMDmodeAlarm
  cmds to execute on any alarm mode change
• HomeCMDmodeAlarm-<armaway/armhome/armnight/confirm/disarm>
  cmds to execute on specific alarm mode change
• HomeCMDmotion
  cmds to execute on any recognized motion of any motion sensor
• HomeCMDmotion-<on/off>
  cmds to execute if any recognized motion of any motion sensor ends/starts
• HomeCMDpanic
  cmds to execute on any panic state
• HomeCMDpanic-<on/off>
  cmds to execute on if panic is turned on/off
• HomeCMDpresence-<absent/present>
  cmds to execute on specific presence change of the HOMEMODE device
• HomeCMDpresence-<absent/present>-device
  cmds to execute on specific presence change of any presence device
• HomeCMDpresence-<absent/present>-resident
  cmds to execute on specific presence change of a specific resident
• HomeCMDpresence-<absent/present>-<%RESIDENT%>
  cmds to execute on specific presence change of a specific resident
• HomeCMDpresence-<absent/present>-<%RESIDENT%>-<%DEVICE%>
  cmds to execute on specific presence change of a specific resident's presence device
  only available if more than one presence device is available for a resident
• HomeCMDpublic-ip-change
  cmds to execute on any detected public IP change
• HomeCMDseason
  cmds to execute on any season change
• HomeCMDseason-<%SEASON%>
  cmds to execute on specific season change
• HomeCMDtwilight
  cmds to execute on any twilight event
• HomeCMDtwilight-<EVENT>
  cmds to execute on a specific twilight event
• HomeCMDuwz-warn
  cmds to execute on any UWZ warning state
• HomeCMDuwz-warn-<begin/end>
  cmds to execute on UWZ warning state begin/end
• HomeDaytimes
  space separated list of time|text pairs for possible daytimes starting with the first event of the day (lowest time)
  default: 05:00|morning 10:00|day 14:00|afternoon 18:00|evening 23:00|night
• HomeEventsHolidayDevices
  devspec of Calendar/holiday calendars
• HomeEventsCalendarDevices
  devspec of Calendar/holiday calendars
• HomeIcewarningOnOffTemps
  2 space separated temperatures for ice warning on and off
  default: 2 3
• HomeLanguage
  overwrite language from gloabl device
  default: EN (language setting from global device)
• HomeModeAbsentBelatedTime
  time in minutes after changing to absent to execute 'HomeCMDmode-absent-belated'
  if mode changes back (to home e.g.) in this time frame 'HomeCMDmode-absent-belated' will not be executed
  default:
• HomeModeAlarmArmDelay
  time in seconds for delaying modeAlarm arm... commands
  must be a single number (valid for all modeAlarm arm... commands) or 3 space separated numbers for each modeAlarm arm... command individually (order: armaway armnight armhome)
  values from 0 to 99999
  default: 0
• HomePresenceDeviceAbsentCount-<ROOMMATE/GUEST/PET>
  number of resident associated presence device to turn resident to absent
  default: maximum number of available presence device for each resident
• HomePresenceDevicePresentCount-<ROOMMATE/GUEST/PET>
  number of resident associated presence device to turn resident to home
  default: 1
• HomePresenceDeviceType
  comma separated list of presence device types
  default: PRESENCE
• HomePublicIpCheckInterval
  numbers from 1-99999 for interval in minutes for public IP check
  default: 0 (disabled)
• HomeResidentCmdDelay
  time in seconds to delay the execution of specific residents commands after the change of the residents master device
  normally the resident events occur before the HOMEMODE events, to restore this behavior set this value to 0
  default: 1 (second)
• HomeSeasons
  space separated list of date|text pairs for possible seasons starting with the first season of the year (lowest date)
  default: 01.01|spring 06.01|summer 09.01|autumn 12.01|winter
• HomeSensorAirpressure
  main outside airpressure sensor
• HomeSensorWindspeed
  main outside wind speed sensor
• HomeSensorsBattery
  devspec of battery sensors with a battery reading
  all sensors with a percentage battery value or a ok/low/nok battery value are applicable
• HomeSensorsBatteryLowPercentage
  percentage to recognize a sensors battery as low (only percentage based sensors)
  default: 50
• HomeSensorsBatteryReading
  a single word for the battery reading
  this is only here available as global setting for all devices
  default: battery
• HomeSensorsContact
  devspec of contact sensors
  each applied contact sensor will get the following attributes, attributes will be removed after removing the contact sensors from the HOMEMODE device.
  
  • HomeContactType
    specify each contacts sensor's type, choose one of: doorinside, dooroutside, doormain, window
    while applying contact sensors to the HOMEMODE device, the value of this attribute will be guessed by device name or device alias
  • HomeModeAlarmActive
    specify the alarm mode(s) by regex in which the contact sensor should trigger open/tilted as alerts
    while applying contact sensors to the HOMEMODE device, the value of this attribute will be set to armaway by default
    choose one or a combination of: armaway|armhome|armnight
    default: armaway
  • HomeOpenDontTriggerModes
    specify the HOMEMODE mode(s)/state(s) by regex in which the contact sensor should not trigger open warnings
    choose one or a combination of all available modes of the HOMEMODE device
    if you don't want open warnings while sleeping a good choice would be: gotosleep|asleep
    default:
  • HomeOpenDontTriggerModesResidents
    comma separated list of residents whose state should be the reference for HomeOpenDontTriggerModes instead of the mode of the HOMEMODE device
    if one of the listed residents is in the state given by attribute HomeOpenDontTriggerModes, open warnings will not be triggered for this contact sensor
    default:
  • HomeOpenMaxTrigger
    maximum number how often open warning should be triggered
    default: 0
  • HomeReadings
    2 space separated readings for contact sensors open state and tamper alert
    this is the device setting which will override the global setting from attribute HomeSensorsContactReadings from the HOMEMODE device
    default: state sabotageError
  • HomeValues
    regex of open, tilted and tamper values for contact sensors
    this is the device setting which will override the global setting from attribute HomeSensorsContactValues from the HOMEMODE device
    default: open|tilted|on
  • HomeOpenTimes
    space separated list of minutes after open warning should be triggered
    first value is for first warning, second value is for second warning, ...
    if less values are available than the number given by HomeOpenMaxTrigger, the very last available list entry will be used
    this is the device setting which will override the global setting from attribute HomeSensorsContactOpenTimes from the HOMEMODE device
    default: 10
  • HomeOpenTimeDividers
    space separated list of trigger time dividers for contact sensor open warnings depending on the season of the HOMEMODE device.
    dividers in same order and same number as seasons in attribute HomeSeasons
    dividers are not used for contact sensors of type doormain and doorinside!
    this is the device setting which will override the global setting from attribute HomeSensorsContactOpenTimeDividers from the HOMEMODE device
    values from 0.001 to 99.999
    default:
• HomeSensorsContactReadings
  2 space separated readings for contact sensors open state and tamper alert
  this is the global setting, you can also set these readings in each contact sensor individually in attribute HomeReadings once they are added to the HOMEMODE device
  default: state sabotageError
• HomeSensorsContactValues
  regex of open, tilted and tamper values for contact sensors
  this is the global setting, you can also set these values in each contact sensor individually in attribute HomeValues once they are added to the HOMEMODE device
  default: open|tilted|on
• HomeSensorsContactOpenTimeDividers
  space separated list of trigger time dividers for contact sensor open warnings depending on the season of the HOMEMODE device.
  dividers in same order and same number as seasons in attribute HomeSeasons
  dividers are not used for contact sensors of type doormain and doorinside!
  this is the global setting, you can also set these dividers in each contact sensor individually in attribute HomeOpenTimeDividers once they are added to the HOMEMODE device
  values from 0.001 to 99.999
  default:
• HomeSensorsContactOpenTimeMin
  minimal open time for contact sensors open wanings
  default:
• HomeSensorsContactOpenTimes
  space separated list of minutes after open warning should be triggered
  first value is for first warning, second value is for second warning, ...
  if less values are available than the number given by HomeOpenMaxTrigger, the very last available list entry will be used
  this is the global setting, you can also set these times(s) in each contact sensor individually in attribute HomeOpenTimes once they are added to the HOMEMODE device
  default: 10
• HomeSensorHumidityOutside
  main outside humidity sensor
  if HomeSensorTemperatureOutside also has a humidity reading, you don't need to add the same sensor here
• HomeSensorTemperatureOutside
  main outside temperature sensor
  if this sensor also has a humidity reading, you don't need to add the same sensor to HomeSensorHumidityOutside
• HomeSensorsLuminance
  devspec of sensors with luminance measurement capabilities
  these devices will be used for total luminance calculations
  please set the corresponding reading for luminance in attribute HomeSensorsLuminanceReading (if different to luminance) before applying snesors here
• HomeSensorsLuminanceReading
  a single word for the luminance reading
  this is only here available as global setting for all devices
  default: luminance
• HomeSensorsMotion
  devspec of motion sensors
  each applied motion sensor will get the following attributes, attributes will be removed after removing the motion sensors from the HOMEMODE device.
  
  • HomeModeAlarmActive
    specify the alarm mode(s) by regex in which the motion sensor should trigger motions as alerts
    while applying motion sensors to the HOMEMODE device, the value of this attribute will be set to armaway by default
    choose one or a combination of: armaway|armhome|armnight
    default: armaway (if sensor is of type inside)
  • HomeSensorLocation
    specify each motion sensor's location, choose one of: inside, outside
    default: inside
  • HomeReadings
    2 space separated readings for motion sensors open/closed state and tamper alert
    this is the device setting which will override the global setting from attribute HomeSensorsMotionReadings from the HOMEMODE device
    default: state sabotageError
  • HomeValues
    regex of open and tamper values for motion sensors
    this is the device setting which will override the global setting from attribute HomeSensorsMotionValues from the HOMEMODE device
    default: open|on
• HomeSensorsMotionReadings
  2 space separated readings for motion sensors open/closed state and tamper alert
  this is the global setting, you can also set these readings in each motion sensor individually in attribute HomeReadings once they are added to the HOMEMODE device
  default: state sabotageError
• HomeSensorsMotionValues
  regex of open and tamper values for motion sensors
  this is the global setting, you can also set these values in each contact sensor individually in attribute HomeValues once they are added to the HOMEMODE device
  default: open|on
• HomeSensorsPowerEnergy
  devspec of sensors with power and energy readings
  these devices will be used for total calculations
• HomeSensorsPowerEnergyReadings
  2 space separated readings for power/energy sensors power and energy readings
  default: power energy
• HomeSensorsSmoke
  devspec of smoke sensors
  
• HomeSensorsSmokeReading
  reading for smoke sensors on/off state
  default: state
• HomeSensorsSmokeValue
  regex of on values for smoke sensors
  default: on
• HomeSpecialLocations
  comma separated list of additional locations
  default:
• HomeSpecialModes
  comma separated list of additional modes
  default:
• HomeTextAndAreIs
  pipe separated list of your local translations for 'and', 'are' and 'is'
  default: and|are|is
• HomeTextClosedOpen
  pipe separated list of your local translation for 'closed' and 'open'
  default: closed|open
• HomeTextRisingConstantFalling
  pipe separated list of your local translation for 'rising', 'constant' and 'falling'
  default: rising|constant|falling
• HomeTextNosmokeSmoke
  pipe separated list of your local translation for 'no smoke' and 'smoke'
  default: so smoke|smoke
• HomeTextTodayTomorrowAfterTomorrow
  pipe separated list of your local translations for 'today', 'tomorrow' and 'day after tomorrow'
  this is used by weather forecast
  default: today|tomorrow|day after tomorrow
• HomeTextWeatherForecastInSpecDays
  your text for weather forecast in specific days
  placeholders can be used!
  default:
• HomeTextWeatherForecastToday
  your text for weather forecast today
  placeholders can be used!
  default:
• HomeTextWeatherForecastTomorrow
  your text for weather forecast tomorrow and the day after tomorrow
  placeholders can be used!
  default:
• HomeTextWeatherNoForecast
  your text for no available weather forecast
  default: No forecast available
• HomeTextWeatherLong
  your text for long weather information
  placeholders can be used!
  default:
• HomeTextWeatherShort
  your text for short weather information
  placeholders can be used!
  default:
• HomeTrendCalcAge
  time in seconds for the max age of the previous measured value for calculating trends
  default: 900
• HomeTriggerAnyoneElseAtHome
  your anyoneElseAtHome trigger device (device:reading:valueOn:valueOff)
  default:
• HomeTriggerPanic
  your panic alarm trigger device (device:reading:valueOn[:valueOff])
  valueOff is optional
  valueOn will toggle panic mode if valueOff is not given
  default:
• HomeTwilightDevice
  your local Twilight device
  default:
• HomeUWZ
  your local UWZ device
  default:
• HomeWeatherDevice
  your local Weather device
  default:



Readings

• alarmSmoke
  list of triggered smoke sensors
• alarmSmoke_ct
  count of triggered smoke sensors
• alarmSmoke_hr
  (human readable) list of triggered smoke sensors
• alarmState
  current state of alarm system (includes current alarms - for homebridgeMapping)
• alarmTriggered
  list of triggered alarm sensors (contact/motion sensors)
• alarmTriggered_ct
  count of triggered alarm sensors (contact/motion sensors)
• alarmTriggered_hr
  (human readable) list of triggered alarm sensors (contact/motion sensors)
• anyoneElseAtHome
  anyoneElseAtHome on or off
• contactsDoorsInsideOpen
  list of names of open contact sensors of type doorinside
• batteryLow
  list of names of sensors with low battery
• batteryLow_ct
  count of sensors with low battery
• batteryLow_hr
  (human readable) list of sensors with low battery
• contactsDoorsInsideOpen_ct
  count of open contact sensors of type doorinside
• contactsDoorsInsideOpen_hr
  (human readable) list of open contact sensors of type doorinside
• contactsDoorsMainOpen
  list of names of open contact sensors of type doormain
• contactsDoorsMainOpen_ct
  count of open contact sensors of type doormain
• contactsDoorsMainOpen_hr
  (human readable) list of open contact sensors of type doormain
• contactsDoorsOutsideOpen
  list of names of open contact sensors of type dooroutside
• contactsDoorsOutsideOpen_ct
  count of open contact sensors of type dooroutside
• contactsDoorsOutsideOpen_hr
  (human readable) list of contact sensors of type dooroutside
• contactsOpen
  list of names of all open contact sensors
• contactsOpen_ct
  count of all open contact sensors
• contactsOpen_hr
  (human readable) list of all open contact sensors
• contactsOutsideOpen
  list of names of open contact sensors outside (sensor types: dooroutside,doormain,window)
• contactsOutsideOpen_ct
  count of open contact sensors outside (sensor types: dooroutside,doormain,window)
• contactsOutsideOpen_hr
  (human readable) list of open contact sensors outside (sensor types: dooroutside,doormain,window)
• contactsWindowsOpen
  list of names of open contact sensors of type window
• contactsWindowsOpen_ct
  count of open contact sensors of type window
• contactsWindowsOpen_hr
  (human readable) list of open contact sensors of type window
• daytime
  current daytime (as configured in HomeDaytimes) - independent from the mode of the HOMEMODE device
  
• dnd
  dnd (do not disturb) on or off
• devicesDisabled
  comma separated list of disabled devices
• energy
  calculated total energy
• event-<%CALENDAR%>
  current event of the (holiday) CALENDAR device(s)
• humidty
  current humidty of the Weather device or of your own sensor (if available)
• humidtyTrend
  trend of the humidty over the last hour
  possible values: constant, rising, falling
• icawarning
  ice warning
  values: 0 if off and 1 if on
• lastAbsentByPresenceDevice
  last presence device which went absent
• lastAbsentByResident
  last resident who went absent
• lastActivityByPresenceDevice
  last active presence device
• lastActivityByResident
  last active resident
• lastAsleepByResident
  last resident who went asleep
• lastAwokenByResident
  last resident who went awoken
• lastBatteryNormal
  last sensor with normal battery
• lastBatteryLow
  last sensor with low battery
• lastCMDerror
  last occured error and command(chain) while executing command(chain)
• lastContact
  last contact sensor which triggered open
• lastContactClosed
  last contact sensor which triggered closed
• lastGoneByResident
  last resident who went gone
• lastGotosleepByResident
  last resident who went gotosleep
• lastInfo
  last shown item on infopanel (HomeAdvancedDetails)
• lastMotion
  last sensor which triggered motion
• lastMotionClosed
  last sensor which triggered motion end
• lastPresentByPresenceDevice
  last presence device which came present
• lastPresentByResident
  last resident who came present
• light
  current light reading value
• location
  current location
• luminance
  average luminance of all motion sensors (if available)
• luminanceTrend
  trend of the luminance over the last hour
  possible values: constant, rising, falling
• mode
  current mode
• modeAlarm
  current mode of alarm system
• motionsInside
  list of names of open motion sensors of type inside
• motionsInside_ct
  count of open motion sensors of type inside
• motionsInside_hr
  (human readable) list of open motion sensors of type inside
• motionsOutside
  list of names of open motion sensors of type outside
• motionsOutside_ct
  count of open motion sensors of type outside
• motionsOutside_hr
  (human readable) list of open motion sensors of type outside
• motionsSensors
  list of all names of open motion sensors
• motionsSensors_ct
  count of all open motion sensors
• motionsSensors_hr
  (human readable) list of all open motion sensors
• power
  calculated total power
• prevMode
  previous mode
• presence
  presence of any resident
• pressure
  current air pressure of the Weather device
• prevActivityByResident
  previous active resident
• prevContact
  previous contact sensor which triggered open
• prevContactClosed
  previous contact sensor which triggered closed
• prevLocation
  previous location
• prevMode
  previous mode
• prevMotion
  previous sensor which triggered motion
• prevMotionClosed
  previous sensor which triggered motion end
• prevModeAlarm
  previous alarm mode
• publicIP
  last checked public IP address
• season
  current season as configured in HomeSeasons
  
• sensorsTampered
  list of names of tampered sensors
• sensorsTampered_ct
  count of tampered sensors
• sensorsTampered_hr
  (human readable) list of tampered sensors
• state
  current state
• temperature
  current temperature of the Weather device or of your own sensor (if available)
• temperatureTrend
  trend of the temperature over the last hour
  possible values: constant, rising, falling
• twilight
  current twilight reading value
• twilightEvent
  current twilight event
• uwz_warnCount
  current UWZ warn count
• wind
  current wind speed of the Weather device

Placeholders

These placeholders can be used in all HomeCMD attributes

• %ADDRESS%
  mac address of the last triggered presence device
• %ALIAS%
  alias of the last triggered resident
• %ALARM%
  value of the alarmTriggered reading of the HOMEMODE device
  will return 0 if no alarm is triggered or a list of triggered sensors if alarm is triggered
• %ALARMCT%
  value of the alarmTriggered_ct reading of the HOMEMODE device
• %ALARMHR%
  value of the alarmTriggered_hr reading of the HOMEMODE device
  will return 0 if no alarm is triggered or a (human readable) list of triggered sensors if alarm is triggered
  can be used for sending msg e.g.
• %AMODE%
  current alarm mode
• %AEAH%
  state of anyoneElseAtHome, will return 1 if on and 0 if off
• %ARRIVERS%
  will return a list of aliases of all registered residents/guests with location arrival
  this can be used to welcome residents after main door open/close
  e.g. Peter, Paul and Marry
• %AUDIO%
  audio device of the last triggered resident (attribute msgContactAudio)
  if attribute msgContactAudio of the resident has no value the value is trying to be taken from device globalMsg (if available)
  can be used to address resident specific msg(s) of type audio, e.g. night/morning wishes
• %BE%
  is or are of condition reading of monitored Weather device
  can be used for weather (forecast) output
• %BATTERYLOW%
  alias (or name if alias is not set) of the last battery sensor which reported low battery
• %BATTERYLOWALL%
  list of aliases (or names if alias is not set) of all battery sensor which reported low battery currently
• %BATTERYLOWCT%
  number of battery sensors which reported low battery currently
• %BATTERYNORMAL%
  alias (or name if alias is not set) of the last battery sensor which reported normal battery
• %CONDITION%
  value of the condition reading of monitored Weather device
  can be used for weather (forecast) output
• %CONTACT%
  value of the lastContact reading (last opened sensor)
• %DEFINED%
  name of the previously defined device
  can be used to trigger actions based on the name of the defined device
  only available within HomeCMDfhemDEFINED
• %DAYTIME%
  value of the daytime reading of the HOMEMODE device
  can be used to trigger day time specific actions
• %DEVICE%
  name of the last triggered presence device
  can be used to trigger actions depending on the last present/absent presence device
• %DEVICEA%
  name of the last triggered absent presence device
• %DEVICEP%
  name of the last triggered present presence device
• %DISABLED%
  comma separated list of disabled devices
• %DND%
  state of dnd, will return 1 if on and 0 if off
• %DURABSENCE%
  value of the durTimerAbsence_cr reading of the last triggered resident
• %DURABSENCELAST%
  value of the lastDurAbsence_cr reading of the last triggered resident
• %DURPRESENCE%
  value of the durTimerPresence_cr reading of the last triggered resident
• %DURPRESENCELAST%
  value of the lastDurPresence_cr reading of the last triggered resident
• %DURSLEEP%
  value of the durTimerSleep_cr reading of the last triggered resident
• %DURSLEEPLAST%
  value of the lastDurSleep_cr reading of the last triggered resident
• %CALENDARNAME%
  will return the current event of the given calendar name, will return 0 if event is none
  can be used to trigger actions on any event of the given calendar
• %CALENDARNAME-EVENTNAME%
  will return 1 if given event of given calendar is current, will return 0 if event is not current
  can be used to trigger actions during specific events only (Christmas?)
• %FORECAST%
  will return the weather forecast for tomorrow
  can be used in msg or tts
• %FORECASTTODAY%
  will return the weather forecast for today
  can be used in msg or tts
• %HUMIDITY%
  value of the humidity reading of the HOMEMODE device
  can be used for weather info in HomeTextWeather attributes e.g.
• %HUMIDITYTREND%
  value of the humidityTrend reading of the HOMEMODE device
  possible values: constant, rising, falling
• %ICE%
  will return 1 if ice warning is on, will return 0 if ice warning is off
  can be used to send ice warning specific msg(s) in specific situations, e.g. to warn leaving residents
• %IP%
  value of reading publicIP
  can be used to send msg(s) with (new) IP address
• %LIGHT%
  value of the light reading of the HOMEMODE device
• %LOCATION%
  value of the location reading of the HOMEMODE device
• %LOCATIONR%
  value of the location reading of the last triggered resident
• %LUMINANCE%
  average luminance of motion sensors (if available)
• %LUMINANCETREND%
  value of the luminanceTrend reading of the HOMEMODE device
  possible values: constant, rising, falling
• %MODE%
  current mode of the HOMEMODE device
• %MODEALARM%
  current alarm mode
• %MOTION%
  value of the lastMotion reading (last opened sensor)
• %NAME%
  name of the HOMEMODE device itself (same as %SELF%)
• %OPEN%
  value of the contactsOutsideOpen reading of the HOMEMODE device
  can be used to send msg(s) in specific situations, e.g. to warn leaving residents of open contact sensors
• %OPENCT%
  value of the contactsOutsideOpen_ct reading of the HOMEMODE device
  can be used to send msg(s) in specific situations depending on the number of open contact sensors, maybe in combination with placeholder %OPEN%
• %OPENHR%
  value of the contactsOutsideOpen_hr reading of the HOMEMODE device
  can be used to send msg(s)
• %PANIC%
  state of panic, will return 1 if on and 0 if off
• %RESIDENT%
  name of the last triggered resident
• %PRESENT%
  presence of the HOMEMODE device
  will return 1 if present or 0 if absent
• %PRESENTR%
  presence of last triggered resident
  will return 1 if present or 0 if absent
• %PRESSURE%
  value of the pressure reading of the HOMEMODE device
  can be used for weather info in HomeTextWeather attributes e.g.
• %PREVAMODE%
  previous alarm mode of the HOMEMODE device
• %PREVCONTACT%
  previous open contact sensor
• %PREVMODE%
  previous mode of the HOMEMODE device
• %PREVMODER%
  previous state of last triggered resident
• %PREVMOTION%
  previous open motion sensor
• %SEASON%
  value of the season reading of the HOMEMODE device
• %SELF%
  name of the HOMEMODE device itself (same as %NAME%)
• %SENSORSBATTERY%
  all battery sensors from internal SENSORSBATTERY
• %SENSORSCONTACT%
  all contact sensors from internal SENSORSCONTACT
• %SENSORSENERGY%
  all energy sensors from internal SENSORSENERGY
• %SENSORSMOTION%
  all motion sensors from internal SENSORSMOTION
• %SENSORSSMOKE%
  all smoke sensors from internal SENSORSSMOKE
• %SMOKE%
  value of the alarmSmoke reading of the HOMEMODE device
  will return 0 if no smoke alarm is triggered or a list of triggered sensors if smoke alarm is triggered
• %SMOKECT%
  value of the alarmSmoke_ct reading of the HOMEMODE device
• %SMOKEHR%
  value of the alarmSmoke_hr reading of the HOMEMODE device
  will return 0 if no smoke alarm is triggered or a (human readable) list of triggered sensors if smoke alarm is triggered
  can be used for sending msg e.g.
• %TAMPERED%
  value of the sensorsTampered reading of the HOMEMODE device
• %TAMPEREDCT%
  value of the sensorsTampered_ct reading of the HOMEMODE device
• %TAMPEREDHR%
  value of the sensorsTampered_hr reading of the HOMEMODE device
  can be used for sending msg e.g.
• %TEMPERATURE%
  value of the temperature reading of the HOMEMODE device
  can be used for weather info in HomeTextWeather attributes e.g.
• %TEMPERATURETREND%
  value of the temperatureTrend reading of the HOMEMODE device
  possible values: constant, rising, falling
• %TWILIGHT%
  value of the twilight reading of the HOMEMODE device
• %TWILIGHTEVENT%
  current twilight event
• %TOBE%
  are or is of the weather condition
  useful for phrasing sentences
• %UWZ%
  UWZ warnings count
• %UWZLONG%
  all current UWZ warnings as long text
• %UWZSHORT%
  all current UWZ warnings as short text
• %WEATHER%
  value of 'get <HOMEMODE> weather short'
  can be used for for msg weather info e.g.
• %WEATHERLONG%
  value of 'get <HOMEMODE> weather long'
  can be used for for msg weather info e.g.
• %WIND%
  value of the wind reading of the HOMEMODE device
  can be used for weather info in HomeTextWeather attributes e.g.
• %WINDCHILL%
  value of the apparentTemperature reading of the Weather device
  can be used for weather info in HomeTextWeather attributes e.g.

These placeholders can only be used within HomeTextWeatherForecast attributes

• %CONDITION%
  value of weather forecast condition
• %DAY%
  day number of weather forecast
• %HIGH%
  value of maximum weather forecast temperature
• %LOW%
  value of minimum weather forecast temperature

These placeholders can only be used within HomeCMDcontact, HomeCMDmotion and HomeCMDalarm attributes

• %ALIAS%
  alias of the last triggered contact/motion/smoke sensor
• %SENSOR%
  name of the last triggered contact/motion/smoke sensor
• %STATE%
  state of the last triggered contact/motion/smoke sensor

These placeholders can only be used within calendar event related HomeCMDevent attributes

• %CALENDAR%
  name of the calendar
• %DESCRIPTION%
  description of current event of the calendar (not applicable for holiday devices)
• %EVENT%
  summary of current event of the calendar
• %PREVEVENT%
  summary of previous event of the calendar

These placeholders can only be used within HomeCMDdeviceDisable and HomeCMDdeviceEnable attributes

• %DEVICE%
  name of the disabled/enabled device
• %ALIAS%
  alias of the disabled/enabled device

HP1000

Define
define <WeatherStation> HP1000 [<ID> <PASSWORD>]

Provides webhook receiver for Wifi-based weather station which support PWS protocol from Weather Underground (e.g. HP1000, WH2600, WH2601, WH2621, WH2900, WH2950 of Fine Offset Electronics - sometimes also known as Ambient Weather WS-1001-WIFI or similar). In Germany, these devices are commonly distributed by froggit or by Conrad under it's brand name Renkforce.
There needs to be a dedicated FHEMWEB instance with attribute webname set to "weatherstation".
No other name will work as it's hardcoded in the weather station device itself!
If necessary, this module will create a matching FHEMWEB instance named WEBweatherstation during initial definition.

As the URI has a fixed coding as well there can only be one single instance of this module FHEM installation.

Example:

# unprotected instance where ID and PASSWORD will be ignored
define WeatherStation HP1000

# protected instance: Weather Station needs to be configured
# to send this ID and PASSWORD for data to be accepted
define WeatherStation HP1000 MyHouse SecretPassword

IMPORTANT: In your hardware device, make sure you use a DNS name as most revisions cannot handle IP addresses correctly.
You might want to check to install a firmware update from here.



Attributes
• readingFnAttributes


• bogusFilter
Will explicitly drop every numeric value that is below -273.2 (defaults to 0).
This might help in case your station tends to send out of range values from time to time.
• webhookFWinstances
Explicitly specify allowed FHEMWEB instaces for data input (defaults to weatherstation)
• wu_id
Weather Underground (Wunderground) station ID
• wu_password
Weather Underground (Wunderground) password
• wu_dataValues
Add or replace values before pushing data to Weather Underground.
Format is key=value while value may be of set magic format
• wu_indoorValues
Include indoor values for Weather Underground (defaults to 1=yes)
• wu_push
Enable or disable to push data forward to Weather Underground (defaults to 0=no)
• wu_pushValues
Restrict values to be transferred to Weather Underground, otherwise all values will be transferred.
• wu_realtime
Send the data to the WU realtime server instead of using the standard server (defaults to 1=yes)

HProtocolGateway

The HProtocolGateway is a fhem module for the RS232 standard interface for example for HLS 6010 Probes connected to a Hectronic OPTILEVEL Supply.


Define
define <name> HProtocolGateway /dev/tty???
attr <name> pollInterval 120
attr <name> baudrate 1200
attr <name> databitsLength 8
attr <name> parityBit N
attr <name> stopBit 1

Defines an HProtocolGateway connected to RS232 serial standard interface.



Attributes
• pollInterval
  poll Interval in seconds
• baudrate
  Baudrate / 300, 600, 1200, 2400, 4800, 9600
• databitsLength
  Databits Length / 5, 6, 7, 8
• parityBit
  Parity Bit / N, E, O
• stopBit
  Stop Bit / 0, 1

HProtocolTank

The HProtocolTank is a fhem module defines a device connected to a HProtocolGateway.


Define
define <name> HProtocolTank HProtocolGateway
attr <name> hID 01
attr <name> sensorSystem Hectronic
attr <name> product FuelOil

Defines an HProtocolTank connected to a HProtocolGateway.



Readings
• ullage
  0..999999 Ullage in litres
• filllevel
  0..99999 Fill level in cm
• volume
  0..999999 Volume in litres
• volume_15C
  0..999999 Volume in litres at 15 °C
• temperature
  -999 - +999 Temperature in °C
• waterlevel
  0..9999 Water level in mm
• probe_offset
  -9999 - +9999 Probe offset in mm
• version
  00..999 Software version
• error
  0..9 00.. Probe error

Attributes
• hID
  01 - 32 Tank Number / Tank Address (99 for testing only)
• sensorSystem
  Sensor System / Hectronic, Unitronics, PMS-IB
• mode
  Mode / FillLevel, Volume, Ullage
• type
  Type / Strapping Table csv
• product
  Product / Diesel, FuelOil, Petrol


strapping table csv

level,volume
10,16
520,7781
1330,29105
1830,43403
2070,49844
2220,53580
2370,57009
2400,57650
2430,58275
2370,57009
2400,57650
2430,58275


HTTPAPI

HTTPAPI is a compact HTML API server that performs http requests to execute set and get commands and reads and writes readings.

Define
define <name> HTTPAPI [infix=][<apiName>] [port=][[IPV6:]<port>] [global=][global|local|<hostname>]

Defines the HTTP API server.

• <apiName> is the portion behind the base URL (usually http://<hostname>:<port>/<apiName>).
  [<apiName>] = api is default.
• [[IPV6:]<port>] = 8087 is default.
  To use IPV6, specify the portNumber as IPV6:<number>, in this case the perl module IO::Socket:INET6 will be requested. On Linux you may have to install it with cpan -i IO::Socket::INET6 or apt-get libio-socket-inet6-perl.
• [global|local|<hostname>] = global is default.
  If the parameter is set to local, the server will only listen to localhost connections. If is set to global, the server will listen on all interfaces, else it wil try to resolve the parameter as a hostname, and listen only on this interface.

Example:
define httpapi HTTPAPI (Configuration with default values)
or
define httpapi HTTPAPI api 8087 global
or
define httpapi HTTPAPI infix=api1 port=8089 global=local



Get
• API command line for executing a get command
  Request:
  http://<ip-addr>:<port>/<apiName>/get?device=<devname>&action=<cmd>
  
  Response:
  <action>=<response>|error=<error message>
  


Set
• API command line for executing a set command
  Request:
  http://<ip-addr>:<port>/<apiName>/set?device=<devname>&action=<cmd>
  
  Response:
  <device>=<cmd>|error=<error message>
  


Generated events
• API command line for setting a reading
  Request:
  http://<ip-addr>:<port>/<apiName>/write?device=<devname>&reading=<name>&value=<val>
  
  Response:
  <reading name>=<val>|error=<error message>
  
• API command line for querying a reading
  Request:
  http://<ip-addr>:<port>/<apiName>/read?device=<devname>&reading=<name>
  
  Response:
  <reading name>=<val>|error=<error message>
  
• API command line for querying the timestamp of a reading
  Request:
  http://<ip-addr>:<port>/<apiName>/readtimestamp?device=<devname>&reading=<name>
  
  Response:
  <reading name>=<timestamp>|error=<error message>
  
• API command line for deleting a reading
  Request:
  http://<ip-addr>:<port>/<apiName>/write?device=<devname>&reading=<name>&value=
http://<ip-addr>:<port>/<apiName>/write?device=<devname>&reading=<name>
  
  Response:
  <reading name>=|error=<error message>
  
• API command line for querying a internal
  Request:
  http://<ip-addr>:<port>/<apiName>/readinternal?device=<devname>&internal=<name>
  
  Response:
  <internal name>=<val>|error=<error message>
  


Usage information
• All links are relative to http://<ip-addr>:<port>/.
• Commands are not executed if the disable or ignore attribute of the device is set. See also devicesCtrl.
• The http://<ip-addr>:<port>/<apiName>/ command displays the module-specific commandref.
• The response message is encoded to UTF-8.


Attributes
• devicesCtrl <device_1>,...,<device_n>, A comma separated list all devices to be controlled.
  [devicesCtrl] = < > is default, all devices can be controlled.
• disable 0|1
  If applied commands will not be executed.
• verbose 0...5

HTTPMOD

This module provides a generic way to retrieve information from devices with an HTTP Interface and store them in Readings or send information to such devices. It queries a given URL with Headers and data defined by attributes.
From the HTTP Response it extracts Readings named in attributes using Regexes, JSON or XPath also defined by attributes.
To send information to a device, set commands can be configured using attributes.

Prerequisites


• This Module uses the non blocking HTTP function HttpUtils_NonblockingGet provided by FHEM's HttpUtils in a new Version published in December 2013.
  If not already installed in your environment, please update FHEM or install it manually using appropriate commands from your environment.
  Please also note that Fhem HttpUtils need the global attribute dnsServer to be set in order to work really non blocking even when dns requests can not be answered.

Define

define <name> HTTPMOD <URL> <Interval>

The module connects to the given URL every Interval seconds, sends optional headers and data and then parses the response.
URL can be "none" and Interval can be 0 if you prefer to only query data manually with a get command and not automatically in a defined interval.

Example:


define PM HTTPMOD http://MyPoolManager/cgi-bin/webgui.fcgi 60

Simple configuration of HTTP Devices


In a simple configuration you don't need to define get or set commands. One common HTTP request is automatically sent in the interval specified in the define command and to the URL specified in the define command.
Optional HTTP headers can be specified as attr requestHeader1 to attr requestHeaderX,
optional POST data as attr requestData and then pairs of attr readingXName and attr readingXRegex, attr readingXXPath, attr readingXXPath-Strict or attr readingXJSON to define how values are parsed from the HTTP response and in which readings they are stored.
(The old syntax attr readingsNameX and attr readingsRegexX is still supported but it can go away in a future version of HTTPMOD so the new one with attr readingXName and attr readingXRegex should be preferred)

Example for a PoolManager 5:


define PM HTTPMOD http://MyPoolManager/cgi-bin/webgui.fcgi 60

attr PM enableControlSet 1
attr PM enableCookies 1
attr PM enforceGoodReadingNames 1
attr PM handleRedirects 1

attr PM reading01Name PH
attr PM reading01Regex 34.4001.value":[ \t]+"([\d\.]+)"

attr PM reading02Name CL
attr PM reading02Regex 34.4008.value":[ \t]+"([\d\.]+)"

attr PM reading03Name TEMP
attr PM reading03Regex 34.4033.value":[ \t]+"([\d\.]+)"

attr PM requestData {"get" :["34.4001.value" ,"34.4008.value" ,"34.4033.value", "14.16601.value", "14.16602.value"]}
attr PM requestHeader1 Content-Type: application/json
attr PM requestHeader2 Accept: */*

attr PM stateFormat {sprintf("%.1f Grad, PH %.1f, %.1f mg/l Chlor", ReadingsVal($name,"TEMP",0), ReadingsVal($name,"PH",0), ReadingsVal($name,"CL",0))}


This example uses regular expressions to parse the HTTP response. A regular expression describes what text is around the value that is supposed to be assigned to a reading. The value itself has to match the so called capture group of the regular expression. That is the part of the regular expression inside (). In the above example "([\d\.]+)" refers to numerical digits or points between double quotation marks. Only the string consisting of digits and points will match inside (). This piece is assigned to the reading. You can also use regular expressions that have several capture groups which might be helpful when parsing tables. In this case an attribute like
reading02Regex something[ \t]+([\d\.]+)[ \t]+([\d\.]+)
could match two numbers. When you specify only one reading02Name like
reading02Name Temp
the name Temp will be used with the extension -1 and -2 thus giving a reading Temp-1 for the first number and Temp-2 for the second. You can also specify individual names for several readings that get parsed from one regular expression with several capture groups by defining attributes
reading02-1Name
reading02-2Name ...
The same notation can be used for formatting attributes like readingXOMap, readingXFormat and so on.

The usual way to define readings is however to have an individual regular expression with just one capture group per reading as shown in the above example.


formating and manipulating values / readings


Values that are parsed from an HTTP response can be further treated or formatted with the following attributes:

(reading|get)[0-9]*(-[0-9]+)?OExpr
(reading|get)[0-9]*(-[0-9]+)?OMap
(reading|get)[0-9]*(-[0-9]+)?Format
(reading|get)[0-9]*(-[0-9]+)?Decode
(reading|get)[0-9]*(-[0-9]+)?Encode
They can all be specified for an individual reading, for all readings in one match (e.g. if a regular expression has several capture groups) or for all readings in a get command (defined by getXX) or for all readings in the main reading list (defined by readingXX):
reading01Format %.1f
will format the reading with the name specified by the attribute reading01Name to be numerical with one digit after the decimal point.
If the attribute reading01Regex is used and contains several capture groups then the format will be applied to all readings thet are parsed by this regex unless these readings have their own format specified by reading01-1Format, reading01-2Format and so on.

reading01-2Format %.1f
Can be used in cases where a regular expression specified as reading1regex contains several capture groups or an xpath specified as reading01XPath creates several readings. In this case reading01-2Format specifies the format to be applied to the second match.

readingFormat %.1f
applies to all readings defined by a reading-Attribute that have no more specific format.

If you need to do some calculation on a raw value before it is used as a reading, you can define the attribute readingOExpr.
It defines a Perl expression that is used in an eval to compute the readings value. The raw value will be in the variable $val.
Example:

attr PM reading03OExpr $val * 10

Just like in the above example of the readingFormat attributes, readingOExpr and the other following attributes can be applied on several levels.

To map a raw numerical value to a name, you can use the readingOMap attribute. It defines a mapping from raw values read from the device to visible values like "0:mittig, 1:oberhalb, 2:unterhalb".
Example:

attr PM reading02-3OMap 0:kalt, 1:warm, 2:sehr warm

If the value read from a http response is 1, the above map will transalte it to the string warm and the reading value will be set to warm.
To convert character sets, the module can first decode a string read from the device and then encode it again. For example:
attr PM getDecode UTF-8
This applies to all readings defined for Get-Commands.

Configuration to define a set command and send data to a device


When a set option is defined by attributes, the module will use the value given to the set command and translate it into an HTTP-Request that sends the value to the device.
HTTPMOD has a built in replacement that replaces $val in URLs, headers or Post data with the value passed in the set command.
This value is internally stored in the internal "value" ($hash->{value}) so it can also be used in a user defined replacement.
Extension to the above example for a PoolManager 5:


attr PM set01Name HeizungSoll
attr PM set01URL http://MyPoolManager/cgi-bin/webgui.fcgi?sid=$sid
attr PM set01Hint 6,10,20,30
attr PM set01Min 6
attr PM set01Max 30
attr PM setHeader1 Content-Type: application/json
attr PM set01Data {"set" :{"34.3118.value" :"$val" }}


This example defines a set option with the name HeizungSoll.
By issuing set PM HeizungSoll 10 in FHEM, the value 10 will be sent in the defined HTTP Post to URL http://MyPoolManager/cgi-bin/webgui.fcgi and with Post Data as
{"set" :{"34.3118.value" :"10" }}
The optional attributes set01Min and set01Max define input validations that will be checked in the set function.
the optional attribute set01Hint will define the way the Fhemweb GUI shows the input. This might be a slider or a selection list for example.

The HTTP response to such a request will be ignored unless you specify the attribute setParseResponse for all set commands or set01ParseResponse for the set command with number 01.
If the HTTP response to a set command is parsed then this is done like the parsing of responses to get commands and you can use the attributes ending e.g. on Format, Encode, Decode, OMap and OExpr to manipulate / format the values read.
If a parameter to a set command is not numeric but should be passed on to the device as text, then you can specify the attribute setTextArg. For example:
attr PM set01TextArg
If a set command should not require a parameter at all, then you can specify the attribute NoArg. For example:
attr PM set03Name On attr PM set03NoArg



Configuration to define a get command


When a get option is defined by attributes, the module allows querying additional values from the device that require individual HTTP-Requests or special parameters to be sent

Extension to the above example:


attr PM get01Name MyGetValue
attr PM get01URL http://MyPoolManager/cgi-bin/directory/webgui.fcgi?special=1?sid=$sid
attr PM getHeader1 Content-Type: application/json
attr PM get01Data {"get" :{"30.1234.value"}}


This example defines a get option with the name MyGetValue.
By issuing get PM MyGetValue in FHEM, the defined HTTP request is sent to the device.
The HTTP response is then parsed using the same readingXXName and readingXXRegex attributes as above so additional pairs will probably be needed there for additional values.

If the new get parameter should also be queried regularly, you can define the following optional attributes:

attr PM get01Poll 1
attr PM get01PollDelay 300


The first attribute includes this reading in the automatic update cycle and the second defines an alternative lower update frequency. When the interval defined initially in the define is over and the normal readings are read from the device, the update function will check for additional get parameters that should be included in the update cycle. If a PollDelay is specified for a get parameter, the update function also checks if the time passed since it has last read this value is more than the given PollDelay. If not, this reading is skipped and it will be rechecked in the next cycle when interval is over again. So the effective PollDelay will always be a multiple of the interval specified in the initial define.

Please note that each defined get command that is included in the regular update cycle will create its own HTTP request. So if you want to extract several values from the same request, it is much more efficient to do this by defining readingXXName and readingXXRegex, XPath or JSON attributes and to specify an interval and a URL in the define of the HTTPMOD device.

Handling sessions and logging in


In simple cases logging in works with basic authentication. In the case HTTPMOD accepts a username and password as part of the URL in the form http://User:Password@192.168.1.18/something
However basic auth is seldom used. If you need to fill in a username and password in a HTML form and the session is then managed by a session id, here is how to configure this: when sending data to an HTTP-Device in a set, HTTPMOD will replace any $sid in the URL, Headers and Post data with the internal $hash->{sid}. To authenticate towards the device and give this internal a value, you can use an optional multi step login procedure defined by the following attributes:

• sid[0-9]*URL
• sid[0-9]*Data.*
• sid[0-9]*Header.*
• idRegex
• idJSON
• idXPath
• idXPath-Strict
• (get|set|sid)[0-9]*IdRegex
• (get|set|sid)[0-9]*IdJSON
• (get|set|sid)[0-9]*IdXPath
• (get|set|sid)[0-9]*IdXPath-Strict

Each step can have a URL, Headers and Post Data. To extract the actual session Id, you can use regular expressions, JSON or XPath just like for the parsing of readings but with the attributes (get|set|sid)[0-9]*IdRegex, (get|set|sid)[0-9]*IdJSON, (get|set|sid)[0-9]*IdXPath or (get|set|sid)[0-9]*IdXPath-Strict.
An extracted session Id will be stored in the internal $hash->{sid}.
HTTPMOD will create a sorted list of steps (the numbers between sid and URL / Data / Header) and the loop through these steps and send the corresponding requests to the device. For each step a $sid in a Header or Post Data will be replaced with the current content of $hash->{sid}.
Using this feature, HTTPMOD can perform a forms based authentication and send user name, password or other necessary data to the device and save the session id for further requests.
If for one step not all of the URL, Data or Header Attributes are set, then HTTPMOD tries to use a sidURL, sidData.* or sidHeader.* Attribue (without the step number after sid). This way parts that are the same for all steps don't need to be defined redundantly.

To determine when this login procedure is necessary, HTTPMOD will first try to send a request without doing the login procedure. If the result contains an error that authentication is necessary, then a login is performed. To detect such an error in the HTTP response, you can again use a regular expression, JSON or XPath, this time with the attributes
• reAuthRegex
• reAuthJSON
• reAuthXPath
• reAuthXPath-Strict
• (get|set)[0-9]*ReAuthRegex
• (get|set)[0-9]*ReAuthJSON
• (get|set)[0-9]*ReAuthXPath
• (get|set)[0-9]*ReAuthXPath-Strict

reAuthJSON or reAuthXPath typically only extract one piece of data from a response. If the existance of the specified piece of data is sufficent to start a login procedure, then nothing more needs to be defined to detect this situation. If however the indicator is a status code that contains different values depending on a successful request and a failed request if a new authentication is needed, then you can combine things like reAuthJSON with reAuthRegex. In this case the regex is only matched to the data extracted by JSON (or XPath). This way you can easily extract the status code using JSON parsing and then specify the code that means "authentication needed" as a regular expression.

Example for a multi step login procedure:


attr PM reAuthRegex /html/dummy_login.htm attr PM sidURL http://192.168.70.90/cgi-bin/webgui.fcgi?sid=$sid
attr PM sidHeader1 Content-Type: application/json
attr PM sid1IdRegex wui.init\('([^']+)'
attr PM sid2Data {"set" :{"9.17401.user" :"fhem" ,"9.17401.pass" :"password" }}
attr PM sid3Data {"set" :{"35.5062.value" :"128" }}
attr PM sid4Data {"set" :{"42.8026.code" :"pincode" }}

In this case HTTPMOD detects that a login is necessary by looking for the pattern /html/dummy_login.htm in the HTTP response. If it matches, it starts a login sequence. In the above example all steps request the same URL. In step 1 only the defined header is sent in an HTTP get request. The response will contain a session id that is extraced with the regex wui.init\('([^']+)'. In the next step this session id is sent in a post request to the same URL where tha post data contains a username and password. The a third and a fourth request follow that set a value and a code. The result will be a valid and authorized session id that can be used in other requests where $sid is part of a URL, header or post data and will be replaced with the session id extracted above.

In the special case where a session id is set as a HTTP-Cookie (with the header Set-cookie: in the HTTP response) HTTPMOD offers an even simpler way. With the attribute enableCookies a basic cookie handling mechanism is activated that stores all cookies that the server sends to the HTTPMOD device and puts them back as cookie headers in the following requests.
For such cases no sidIdRegex and no $sid in a user defined header is necessary.


Parsing JSON


If a webservice delivers data in JSON format, HTTPMOD can directly parse JSON which might be easier in this case than definig regular expressions.
The next example shows the data that can be requested from a Poolmanager with the following partial configuration:
define test2 HTTPMOD none 0

attr PM enableControlSet 1
attr PM enableCookies 1
attr PM enforceGoodReadingNames 1
attr PM handleRedirects 1

attr test2 get01Name Chlor
attr test2 getURL http://192.168.70.90/cgi-bin/webgui.fcgi
attr test2 getHeader1 Content-Type: application/json
attr test2 getHeader2 Accept: */*
attr test2 getData {"get" :["34.4008.value"]}

The data in the HTTP response looks like this:

        {
            "data": {
                    "34.4008.value": "0.25"
            },
            "status":       {
                    "code": 0
            },
            "event":        {
                    "type": 1,
                    "data": "48.30000.0"
            }
        }
        

the classic way to extract the value 0.25 into a reading with the name Chlor with a regex would have been
attr test2 get01Regex 34.4008.value":[ \t]+"([\d\.]+)"
with JSON you can write
attr test2 get01JSON data_34.4008.value
If you define an explicit json reading with the get01JSON or reading01JSON syntax and there is no full match, HTTPMOD will try to do a regex match using the defined string. If for example the json data contains an array like
"modes":["Off","SimpleColor","RainbowChase","BobblySquares","Blobs","CuriousCat","Adalight","UDP","DMX"],
a Configuration could be
attr test2 get01Name ModesList attr test2 get01JSON modes
The result will be treated as a list just like a list of XPath matches or Regex matches. So it will create readings ModlesList-1 ModesList-2 and so on as described above (simple Comfiguration).
You can also define a recombineExpr to recombine the match list into one reading e.g. as
attr test2 reading01RecombineExpr join ",", @matchlist
If you don't care about the naming of your readings, you can simply extract all JSON data with
attr test2 extractAllJSON 1
which would apply to all data read from this device and create the following readings out of the HTTP response shown above:

data_34.4008.value 0.25
event_data 48.30000.0
event_type 1
status_code 0

or you can specify
attr test2 get01ExtractAllJSON 1
which would only apply to all data read as response to the get command defined as get01.
Another option is setting extractAllJSON or get01ExtractAllJSON to 2. In this case the module analyzes the JSON data when it is first read, creates readingXXName and readingXXJSON attributes for you and then removes the extractAllJSON attribute.

Parsing http / XML using xpath


Another alternative to regex parsing is the use of XPath to extract values from HTTP responses.
The following example shows how XML data can be parsed with XPath-Strict or HTML Data can be parsed with XPath.
Both work similar and the example uses XML Data parsed with the XPath-Strict option: If The XML data in the HTTP response looks like this:
<root xmlns:foo="http://www.foo.org/" xmlns:bar="http://www.bar.org">
<actors>
<actor id="1">Peter X</actor>
<actor id="2">Charles Y</actor>
<actor id="3">John Doe</actor>
</actors>
</root>
with XPath you can write
attr htest reading01Name Actor
attr htest reading01XPath-Strict //actor[2]/text()
This will create a reading with the Name "Actor" and the value "Charles Y".

Since XPath specifications can define several values / matches, HTTPMOD can also interpret these and store them in multiple readings:
attr htest reading01Name Actor
attr htest reading01XPath-Strict //actor/text()
will create the readings
Actor-1 Peter X
Actor-2 Charles Y
Actor-3 John Doe

Parsing with named regex groups


If you are an expert with regular expressions you can also use named capture groups in regexes for parsing and HTTPMOD will use the group names as reading names. This feature is only meant for experts who know exactly what they are doing and it is not necessary for normal users. For formatting such readings the name of a capture group can be matched with a readingXYName attribute and then the correspondug formatting attributes will be used here.

Further replacements of URL, header or post data


sometimes it is helpful to dynamically change parts of a URL, HTTP header or post data depending on existing readings, internals or perl expressions at runtime.
HTTPMOD has two built in replacements: one for values passed to a set or get command and the other one for a session id.
Before a request is sent, the placeholder $val is replaced with the value that is passed in a set command or an optional value that can be passed in a get command (see getXTextArg). This value is internally stored in the internal "value" so it can also be used in a user defined replacement as explaind in this section.
The other built in replacement is for the session id. If a session id is extracted via a regex, JSON or XPath the it is stored in the internal "sid" and the placeholder $sid in a URL, header or post data is replaced by the content of this internal. User defined replacements can exted this functionality and this might be needed to pass further variables to a server, a current date, a CSRF-token or other things.
To support this, HTTPMOD offers user defined replacements that are as well applied to a request before it is sent to the server. A replacement can be defined with the attributes
"replacement[0-9]*Regex "
"replacement[0-9]*Mode "
"replacement[0-9]*Value "
"(get|set)[0-9]*Replacement[0-9]*Value "

A replacement always replaces a match of a regular expression. The way the replacement value is defined can be specified with the replacement mode. If the mode is reading, then the value is interpreted as the name of a reading of the same device or as device:reading to refer to another device. If the mode is internal, then the value is interpreted as the name of an internal of the same device or as device:internal to refer to another device.
The mode text will use the value as a static text and the mode expression will evaluate the value as a perl expression to compute the replacement. Inside such a replacement expression it is possible to refer to capture groups of the replacement regex.
The mode key will use a value from a key / value pair that is stored in an obfuscated form in the file system with the set storeKeyValue command. This can be useful for storing passwords.

Example:
attr mydevice getData {"get" :["%%value%%.value"]}
attr mydevice replacement01Mode text
attr mydevice replacement01Regex %%value%%

attr mydevice get01Name Chlor
attr mydevice get01Replacement01Value 34.4008

attr mydevice get02Name Something
attr mydevice get02Replacement01Value 31.4024

attr mydevice get05Name profile
attr mydevice get05URL http://www.mydevice.local/getprofile?password=%%password%%
attr mydevice replacement02Mode key
attr mydevice replacement02Regex %%password%%
attr mydevice get05Replacement02Value password

defines that %%value%% will be replaced by a static text.
All Get commands will be HTTP post requests of a similar form. Only the %%value%% will be different from get to get.
The first get will set the reading named Chlor and for the request it will take the generic getData and replace %%value%% with 34.4008.
A second get will look the same except a different name and replacement value.
With the command set storeKeyValue password geheim you can store the password geheim in an obfuscated form in the file system. To use this password and send it in a request you can use the above replacement with mode key. The value password will then refer to the ofuscated string stored with the key password.

HTTPMOD has two built in replacements: One for session Ids and another one for the input value in a set command. The placeholder $sid is always replaced with the internal $hash->{sid} which contains the session id after it is extracted from a previous HTTP response. If you don't like to use the placeholder $sid the you can define your own replacement for example like:
attr mydevice replacement01Mode internal
attr mydevice replacement01Regex %session%
attr mydevice replacement01Value sid

Now the internal $hash->{sid} will be used as a replacement for the placeholder %session%.

In the same way a value that is passed to a set-command can be put into a request with a user defined replacement. In this case the internal $hash->{value} will contain the value passed to the set command. It might even be a string containing several values that could be put into several different positions in a request by using user defined replacements.
The mode expression allows you to define your own replacement syntax:
attr mydevice replacement01Mode expression
attr mydevice replacement01Regex {{([^}]+)}}
attr mydevice replacement01Value ReadingsVal("mydevice", $1, "")
attr mydevice getData {"get" :["{{temp}}.value"]}
In this example any {{name}} in a URL, header or post data will be passed on to the perl function ReadingsVal which uses the string between {{}} as second parameter. This way one defined replacement can be used for many different readings.

replacing reading values when they have not been updated / the device did not respond


If a device does not respond then the values stored in readings will keep the same and only their timestamp shows that they are outdated. If you want to modify reading values that have not been updated for a number of seconds, you can use the attributes
(reading|get)[0-9]*(-[0-9]+)?MaxAge
(reading|get)[0-9]*(-[0-9]+)?MaxAgeReplacementMode
(reading|get)[0-9]*(-[0-9]+)?MaxAgeReplacement

Every time the module tries to read from a device, it will also check if readings have not been updated for longer than the MaxAge attributes allow. If readings are outdated, the MaxAgeReplacementMode defines how the affected reading values should be replaced. MaxAgeReplacementMode can be text, reading, internal, expression or delete.
MaxAge specifies the number of seconds that a reading should remain untouched before it is replaced.
MaxAgeReplacement contains either a static text that is used as replacement value or a Perl expression that is evaluated to give the replacement value. This can be used for example to replace a temperature that has not bee updated for more than 5 minutes with the string "outdated - was 12":
attr PM readingMaxAge 300
attr PM readingMaxAgeReplacement "outdated - was " . $val
attr PM readingMaxAgeReplacementMode expression
The variable $val contains the value of the reading before it became outdated.
If the mode is delete then the reading will be deleted if it has not been updated for the defined time.
If you want to replace or delete a reading immediatley if a device doid not respond, simply set the maximum time to a number smaller than the update interval. Since the max age is checked after a HTTP request was either successful or it failed, the reading will always contain the read value or the replacement after a failed update.

Set-Commands

As defined by the attributes set.*Name
HTTPMOD also supports setExtensions so if you define sets named on and off, setExtensions will provide their usual sets like on-for-timer.
Since setExtensions include AttrTemplate, HTTPMOD also supports these templates.
If you set the attribute enableControlSet to 1, the following additional built in set commands are available:

• interval
  set new interval time in seconds and restart the timer
  
• reread
  request the defined URL and try to parse it just like the automatic update would do it every Interval seconds without modifying the running timer.
• stop
  stop interval timer.
• start
  restart interval timer to call GetUpdate after interval seconds
• clearCookies
  delete all saved cookies
• upgradeAttributes
  convert the attributes for this device from the old syntax to the new one.
  atributes with the description "this attribute should not be used anymore" or similar will be translated to the new syntax, e.g. readingsName1 to reading01Name.
• storeKeyValue
  stores a key value pair in an obfuscated form in the file system. Such values can then be used in replacements where the mode is "key" e.g. to avoid storing passwords in the configuration in clear text
  



Get-Commands

as defined by the attributes get.*Name

Attributes


• do_not_notify
• readingFnAttributes


• reading[0-9]+(-[0-9]+)?Name
  specifies the name of a reading to extract with the corresponding readingRegex, readingJSON, readingXPath or readingXPath-Strict
  Example:

              attr myWebDevice reading01Name temperature
              attr myWebDevice reading02Name humidity
              

  Please note that the old syntax readingsName.* does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.
• (get|set|reading)[0-9]+Regex
  If this attribute is specified, the Regex defined here is used to extract the value from the HTTP Response and assign it to a Reading with the name defined in the (get|set|reading)[0-9]+Name attribute.
  If this attribute is not specified for an individual Reading or get or set but without the numbers in the middle, e.g. as getRegex or readingRegex, then it applies to all the other readings / get / set commands where no specific Regex is defined.
  The value to extract should be in a capture group / sub expression e.g. ([\d\.]+) in the above example. Multiple capture groups will create multiple readings (see explanation above)
  Using this attribute for a set command (setXXRegex) only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.
  Please note that the old syntax readingsRegex.* does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD. If for get or set commands neither a generic Regex attribute without numbers nor a specific (get|set)[0-9]+Regex attribute is specified and also no XPath or JSON parsing specification is given for the get or set command, then HTTPMOD tries to use the parsing definitions for general readings defined in reading[0-9]+Name, reading[0-9]+Regex or XPath or JSON attributes and assigns the Readings that match here.
  Example:

              attr myWebDevice get01Regex temperature:.([0-9]+)
              attr myWebDevice reading102Regex 34.4001.value":[ \t]+"([\d\.]+)"
              

• (get|set|reading)[0-9]+RegOpt
  Lets the user specify regular expression modifiers. For example if the same regular expression should be matched as often as possible in the HTTP response, then you can specify RegOpt g which will case the matching to be done as /regex/g
  The results will be trated the same way as multiple capture groups so the reading name will be extended with -number. For other possible regular expression modifiers see http://perldoc.perl.org/perlre.html#Modifiers Example:

              attr myWebDevice reading0088Regex temperature:.([0-9]+)
              attr myWebDevice reading0088RegOpt g
              

• (get|set)[0-9]+Name
  Name of a get or set command to be defined. If the HTTP response that is received after the command is parsed with an individual parse option then this name is also used as a reading name. Please note that no individual parsing needs to be defined for a get or set. If no regex, XPath or JSON is specified for the command, then HTTPMOD will try to parse the response using all the defined readingRegex, readingXPath or readingJSON attributes.
  Example:

              attr myWebDevice get01Name temperature
              attr myWebDevice set01Name tempSoll
              

• (get|set|reading)[0-9]+XPath-Strict
  defines an xpath to one or more values when parsing XML data (see examples above)
  Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.
  
• (get|set|reading)[0-9]+XPath
  defines an xpath to one or more values when parsing HTML data (see examples above)
  Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.
  
• (get|set|reading)[0-9]+AutoNumLen
  In cases where a regular expression or an XPath results in multiple results and these results are stored in a common reading name with extension -number, then you can modify the format of this number to have a fixed length with leading zeros. AutoNumLen 3 for example will lead to reading names ending with -001 -002 and so on.
• (reading|get|set)[0-9]*AlwaysNum
  if set to 1 this attributes forces reading names to end with a -1, -01 (depending on the above described AutoNumLen) even if just one value is parsed.
• get|set|reading[0-9]+JSON
  defines a path to the JSON object wanted by concatenating the object names. See the above example.
  If you don't know the paths, then start by using extractAllJSON and the use the names of the readings as values for the JSON attribute.
  Please don't forget to also specify a name for a reading, get or set. Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.
  
• extractAllJSONFilter
  is an optional regular expression that filters the readings to be created with extractAllJSON.
• (get|set)[0-9]+ExtractAllJSON or extractAllJSON
  if set to 1 it will create a reading for every JSON object. The reading names will be deducted from the JSON strings hierarchically concatenated by "_".
  if set to 2 it will create attributes for naming and parsing the JSON objects to make it easier to rename or remove some of them.
• (get|set|reading)[0-9]*RecombineExpr
  defines an expression that is used in an eval to compute one reading value out of the list of matches.
  This is supposed to be used for regexes or xpath specifications that produce multiple results if only one result that combines them is wanted. The list of matches will be in the variable @matchlist.
  Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.
  Please note that the recombine feature does not sort the liste to be reombinded but just takes the order thet is created during parsing which might be sorted in some way or not.
• get[0-9]*CheckAllReadings
  this attribute modifies the behavior of HTTPMOD when the HTTP Response of a get command is parsed.
  If this attribute is set to 1, then additionally to the matching of get specific regexe (get[0-9]*Regex), XPath or JSON also all the reading names and parse definitions defined in Reading[0-9]+Name and Reading[0-9]+Regex, XPath or JSON attributes are checked and if they match, the coresponding Readings are assigned as well.
  This is automatically done if a get or set command is defined without its own parse attributes.
  
• (get|reading)[0-9]*OExpr
  defines an optional expression that is used in an eval to compute / format a readings value after parsing an HTTP response
  The raw value from the parsing will be in the variable $val.
  If specified as readingOExpr then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Expr.
  Please note that the old syntax readingsExpr.* does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.
• (get|reading)[0-9]*Expr
  This is the old syntax for (get|reading)[0-9]*OExpr. It should be replaced by (get|reading)[0-9]*OExpr. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.
• (get|reading)[0-9]*OMap
  Map that defines a mapping from raw value parsed to visible values like "0:mittig, 1:oberhalb, 2:unterhalb".
  If specified as readingOMap then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Map.
  The individual options in a map are separated by a komma and an optional space. Spaces are allowed to appear in a visible value however kommas are not possible.
• (get|reading)[0-9]*Map
  This is the old syntax for (get|reading)[0-9]*OMap. It should be replaced by (get|reading)[0-9]*OMap. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.
• (get|set|reading)[0-9]*Format
  Defines a format string that will be used in sprintf to format a reading value.
  If specified without the numbers in the middle e.g. as readingFormat then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Format. Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.
  
• bodyDecode
  defines an encoding to be used in a call to the perl function decode to convert the raw http response body data string read from the device before further processing / matching
  If you have trouble matching special characters or if your reading values contain Umlauts and they are shown as strange looking icons then you might need to use this feature.
  If this attribute is set to 'auto' then HTTPMOD automatically looks for a charset header and decodes the body acordingly. If no charset header is found, the body will remain undecoded.
  
• bodyEncode
  defines an encoding to be used in a call to the perl function encode to convert the raw http response body data string read from the device before further processing / matching
  If you have trouble with JSON parsing you might need to use this feature and set it to utf8.
  
• regexDecode
  defines an encoding to be used in a call to the perl function decode to convert the raw data string from regex attributes before further processing / matching
  If you have trouble matching special characters or if you need to get around a memory leak in Perl regex processing this might help
  
• regexCompile
  defines that regular expressions will be precompiled when they are used for the first time and then stored internally so that subsequent uses of the same regular expression will be faster. This option is turned on by default but setting this attribute to 0 will disable it.
• (get|set|reading)[0-9]*Decode
  defines an encoding to be used in a call to the perl function decode to convert the raw data string read from the device to a reading. This can be used if the device delivers strings in an encoding like cp850 instead of utf8.
  If your reading values contain Umlauts and they are shown as strange looking icons then you probably need to use this feature. Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.
  
• (get|set|reading)[0-9]*Encode
  defines an encoding to be used in a call to the perl function encode to convert the data string read from the device to a reading. This can be used if the device delivers strings in an encoding like cp850 and after decoding it you want to reencode it to e.g. utf8.
  When the attribute bodyDecode is not set to 'none' then this encoding attribute defaults to utf8. If your reading values contain Umlauts and they are shown as strange looking icons then you probably need to modidify this attribute. Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.
  
• (get|set)[0-9]*URL
  URL to be requested for the get or set command. If this option is missing, the URL specified during define will be used.
• (get|set)[0-9]*Data
  optional data to be sent to the device as POST data when the get oer set command is executed. if this attribute is specified, an HTTP POST method will be sent instead of an HTTP GET
• set[0-9]*Method
  HTTP Method (GET, POST or PUT) which shall be used for the set.
• (get|set)[0-9]*NoData
  can be used to override a more generic attribute that specifies POST data for all get commands. With NoData no data is sent and therefor the request will be an HTTP GET.
• (get|set)[0-9]*Header.*
  optional HTTP Headers to be sent to the device when the get or set command is executed
• requestHeader.*
  Define an optional additional HTTP Header to set in the HTTP request
  
• requestData
  optional POST Data to be sent in the request. If not defined, it will be a GET request as defined in HttpUtils used by this module
  
• get[0-9]+Poll
  if set to 1 the get is executed automatically during the normal update cycle (after the interval provided in the define command has elapsed)
• get[0-9]+PollDelay
  if the value should not be read in each iteration (after the interval given to the define command), then a minimum delay can be specified with this attribute. This has only an effect if the above Poll attribute has also been set. Every time the update function is called, it checks if since this get has been read the last time, the defined delay has elapsed. If not, then it is skipped this time.
  PollDelay can be specified as seconds or as x[0-9]+ which means a multiple of the interval in the define command.
  
• (get|set)[0-9]*FollowGet
  allows to chain a get command after another set or get command.
  If for example you want to set a new required temerature with a set 'TargetTemp' command and this set command changes the temperature with a series of HTTP requests in your heating system, then you can automaticaly do a get 'TargetTemp' to read out the new value from your heating.
  The value of this attribute must match a defined get command name.
• maxGetChain
  limits the chain of get command that can be defied with FollowGet
  
• (get|set)[0-9]*TextArg
  For a get command this defines that the command accepts a text value after the option name. By default a get command doesn't accept optional values after the command name. If TextArg is specified and a value is passed after the get name then this value can then be used in a request URL, header or data as replacement for $val or in a user defined replacement that uses the internal "value" ($hash->{value}).
  If used for a set command then it defines that the value to be set doesn't require any validation / conversion. The raw value is passed on as text to the device. By default a set command expects a numerical value or a text value that is converted to a numeric value using a map.
• set[0-9]+Min
  Minimum value for input validation.
• set[0-9]+Max
  Maximum value for input validation.
• set[0-9]+IExpr
  Perl Expression to compute the raw value to be sent to the device from the input value passed to the set. E.g. "$val*100" will multiply $val by 100 after a set command, the thusly modified $val will then be used in subsequent processing, e.g. "(get|set)[0-9]*Data" will use the modified $val
• set[0-9]+Expr
  This is the old syntax for (get|reading)[0-9]*IExpr. It should be replaced by (get|reading)[0-9]*IExpr. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.
• set[0-9]+IMap
  Map that defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb". This attribute atomatically creates a hint for FhemWEB so the user can choose one of the visible values and HTTPMOD sends the raw value to the device.
• set[0-9]+Map
  This is the old syntax for (get|reading)[0-9]*IMap. It should be replaced by (get|reading)[0-9]*IMap. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.
• set[0-9]+Hint
  Explicit hint for fhemWEB that will be returned when set ? is seen.
• set[0-9]*NoArg
  Defines that this set option doesn't require arguments. It allows sets like "on" or "off" without further values.
• (set|sid)[0-9]*ParseResponse
  defines that the HTTP response to the set or auth step will be parsed as if it was the response to a get command.
• set[0-9]*Local
  defines that no HTTP request will be sent. Instead the value is directly set as a reading value.
  
• set[0-9]*ValueSeparator
  defines characters to split a set value into pieces that then can be used as $val1, $val2 and so on.
  This allows several values to be passed in one set. e.g. attr H1 set01Name Set1
attr H1 set01URL https://testurl.local/send?v1=$val1&v2=$val2&v3=$val3
attr H1 set01ValueSeparator ,
set H1 Set1 1,22,333

  
• (get|set)[0-9]*HdrExpr
  Defines a Perl expression to specify the HTTP Headers for this request. This overwrites any other header specification and should be used carefully only if needed. The original headers are availabe as $old and separated by newlines. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.
• (get|set)[0-9]*DatExpr
  Defines a Perl expression to specify the HTTP Post data for this request. This overwrites any other post data specification and should be used carefully only if needed. The original Data is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.
• (get|set)[0-9]*URLExpr
  Defines a Perl expression to specify the URL for this request. This overwrites any other URL specification and should be used carefully only if needed. The original URL is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.
  
• (get|set)[0-9]*ReAuth.*, reAuthRegex, reAuthJSON, reAuthXPath or reAuthXPath-Strict
  regular Expression, JSON or XPath specification to match an error page indicating that a session has expired and a new authentication for read access needs to be done. This attribute only makes sense if you need a forms based authentication for reading data and if you specify a multi step login procedure based on the sid.. attributes.
  This attribute is used for all requests or for matching get / set requests if sepcified as (get|set)[0-9]ReAuth(Regex|JSON|XPath|XPath-Strict).
• reAuthAlways
  if set to 1 will force authentication requests defined in the sid-attributes to be sent before each getupdate, get or set.
• sid[0-9]*URL
  different URLs or one common URL to be used for each step of an optional login procedure.
• (get|set|sid)[0-9]*IdRegex or IdJSON or IdXPath or IdXPath-Strict
  different Regexes, JSON or XPath specifications for get, set or login procedure step to extract the session ID from the HTTP response
• idRegex, idJSON, idXPath or idXPath-Strict
  common Regexes, JSON or XPath specifications to extract the session ID from the HTTP response
• sid[0-9]*Data.*
  data part for each step to be sent as POST data to the corresponding URL
• sid[0-9]*Header.*
  HTTP Headers to be sent to the URL for the corresponding step
• sid[0-9]*IgnoreRedirects
  tell HttpUtils to not follow redirects for this authentication request
• clearSIdBeforeAuth
  will set the session id to "" before doing the authentication steps
• authRetries
  number of retries for authentication procedure - defaults to 1
  
• replacement[0-9]*Regex
  Defines a replacement to be applied to an HTTP request header, data or URL before it is sent. This allows any part of the request to be modified based on a reading, an internal or an expression. The regex defines which part of a header, data or URL should be replaced. The replacement is defined with the following attributes:
• replacement[0-9]*Mode
  Defines how the replacement should be done and what replacementValue means. Valid options are text, reading, internal and expression.
• replacement[0-9]*Value
  Defines the replacement. If the corresponding replacementMode is text, then value is a static text that is used as the replacement.
  If replacementMode is reading then Value can be the name of a reading of this device or it can be a reading of a different device referred to by devicename:reading.
  If replacementMode is internal the Value can be the name of an internal of this device or it can be an internal of a different device referred to by devicename:internal.
  If replacementMode is expression the the Value is treated as a Perl expression that computes the replacement value. The expression can use $1, $2 and so on to refer to capture groups of the corresponding regex that is matched against the original URL, header or post data.
  If replacementMode is key then the module will use a value from a key / value pair that is stored in an obfuscated form in the file system with the set storeKeyValue command. This might be useful for storing passwords.
• (get|set)[0-9]*Replacement[0-9]*Value
  This attribute can be used to override the replacement value for a specific get or set.
  
• get|reading[0-9]*MaxAge
  Defines how long a reading is valid before it is automatically overwritten with a replacement when the read function is called the next time.
• get|reading[0-9]*MaxAgeReplacement
  specifies the replacement for MaxAge - either as a static text, the name of a reading / internal or as a perl expression.
  If MaxAgeReplacementMode is reading then the value of MaxAgeReplacement can be the name of a reading of this device or it can be a reading of a different device referred to by devicename:reading.
  If MaxAgeReplacementMode is internal the value of MaxAgeReplacement can be the name of an internal of this device or it can be an internal of a different device referred to by devicename:internal.
• get|reading[0-9]*MaxAgeReplacementMode
  specifies how the replacement is interpreted: can be text, reading, internal, expression and delete.
  
• get|reading[0-9]*DeleteIfUnmatched
  If set to 1 this attribute causes certain readings to be deleted when the parsing of the website does not match the specified reading. Internally HTTPMOD remembers which kind of operation created a reading (update, Get01, Get02 and so on). Specified readings will only be deleted if the same operation does not parse this reading again. This is especially useful for parsing that creates several matches / readings and this number of matches can vary from request to request. For example if reading01Regex creates 4 readings in one update cycle and in the next cycle it only matches two times then the readings containing the remaining values from the last round will be deleted.
  Please note that this mechanism will not work in all cases after a restart. Especially when a get definition does not contain its own parsing definition but ExtractAllJSON or relies on HTTPMOD to use all defined reading.* attributes to parse the responsee to a get command, old readings might not be deleted after a restart of fhem.
• get|reading[0-9]*DeleteOnError
  If set to 1 this attribute causes certain readings to be deleted when the website can not be reached and the HTTP request returns an error. Internally HTTPMOD remembers which kind of operation created a reading (update, Get01, Get02 and so on). Specified readings will only be deleted if the same operation returns an error.
  The same restrictions as for DeleteIfUnmatched apply regarding a fhem restart.
• httpVersion
  defines the HTTP-Version to be sent to the server. This defaults to 1.0.
• sslVersion
  defines the SSL Version for the negotiation with the server. The attribute is evaluated by HttpUtils. If it is not specified, HttpUtils assumes SSLv23:!SSLv3:!SSLv2
• sslArgs
  defines a list that is converted to a key / value hash and gets passed to HttpUtils. To avoid certificate validation for broken servers you can for example specify attr myDevice sslArgs SSL_verify_mode,SSL_VERIFY_NONE
• noShutdown
  pass the noshutdown flag to HTTPUtils for webservers that need it (some embedded webservers only deliver empty pages otherwise)
• disable
  stop communication with the Web_Server with HTTP requests while this attribute is set to 1
• enableControlSet
  enables the built in set commands like interval, stop, start, reread, upgradeAttributes, storeKeyValue.
  starting with featurelevel > 5.9 HTTPMOD uses this feature by default. So you don't need to set it to 1, but you can disable it by setting it to 0.
• enableCookies
  enables the built cookie handling if set to 1. With cookie handling each HTTPMOD device will remember cookies that the server sets and send them back to the server in the following requests. This simplifies session magamenet in cases where the server uses a session ID in a cookie. In such cases enabling Cookies should be sufficient and no sidRegex and no manual definition of a Cookie Header should be necessary.
  starting with featurelevel > 5.9 HTTPMOD uses this feature by default. So you don't need to set it to 1, but you can disable it by setting it to 0.
• enableTokens
  enables experimental support for access tokens. When a respons contains JSON coded access_token or refresh_token then they are saved in an internal under $hash->{TOKENS}. They then can be used as %%ACCESS_TOKEN%% and %%REFRESH_TOKEN%% in further requests. E.g.:
  attr H1 set02Header3 authorization: Bearer %%ACCESS_TOKEN%%
• showMatched
  if set to 1 then HTTPMOD will create a reading with the name MATCHED_READINGS that contains the names of all readings that could be matched in the last request.
• showError
  if set to 1 then HTTPMOD will create a reading and event with the Name LAST_ERROR that contains the error message of the last error returned from HttpUtils.
• removeBuf
  This attribute has been removed. If set to 1 then HTTPMOD used to removes the internal named buf when a HTTP-response had been received. $hash->{buf} is used internally be Fhem httpUtils and used to be visible. This behavior of httpUtils has changed so removeBuf has become obsolete.
• showBody
  if set to 1 then the body of http responses will be visible as internal httpbody.
• timeout
  time in seconds to wait for an answer. Default value is 2
• queueDelay
  HTTP Requests will be sent from a queue in order to avoid blocking when several Requests have to be sent in sequence. This attribute defines the delay between calls to the function that handles the send queue. It defaults to one second.
• queueMax
  Defines the maximum size of the send queue. If it is reached then further HTTP Requests will be dropped and not be added to the queue
• minSendDelay
  Defines the minimum time between two HTTP Requests.
  
• alignTime
  Aligns each periodic read request for the defined interval to this base time. This is typically something like 00:00 (see the Fhem at command)
  
• enableXPath
  This attribute should no longer be used. Please specify an HTTP XPath in the dedicated attributes shown above.
• enableXPath-Strict
  This attribute should no longer be used. Please specify an XML XPath in the dedicated attributes shown above.
• enforceGoodReadingNames
  makes sure that reading names are valid and especially that extractAllJSON creates valid reading names.
  starting with featurelevel > 5.9 HTTPMOD uses this feature by default. So you don't need to set it to 1, but you can disable it by setting it to 0.
• handleRedirects
  enables redirect handling inside HTTPMOD. This makes complex session establishment where the HTTP responses contain a series of redirects much easier. If enableCookies is set as well, cookies will be tracked during the redirects.
  starting with featurelevel > 5.9 HTTPMOD uses this feature by default. So you don't need to set it to 1, but you can disable it by setting it to 0.
• useSetExtensions
  enables or disables the integration of setExtensions in HTTPMOD. By default this is enabled, but setting this attribute to 0 will disable setExtensions in HTTPMOD.
• dontRequeueAfterAuth
  prevents the original HTTP request to be added to the send queue again after the authentication steps. This might be necessary if the authentication steps will automatically get redirects to the URL originally requested. This option will likely need to be combined with sidXXParseResponse.
• parseFunction1 and parseFunction2
  These functions allow an experienced Perl / Fhem developer to plug in his own parsing functions.
  Please look into the module source to see how it works and don't use them if you are not sure what you are doing.
• preProcessRegex
  can be used to fix a broken HTTP response before parsing. The regex should be a replacement regex like s/match/replacement/g and will be applied to the buffer.
• errorLogLevel
  allows to modify the loglevel used to log errors from HttpUtils. by default level 3 is used.
• errorLogLevelRegex
  restricts the effect of errorLogLevel to error messages that match this regex.
• Remarks regarding the automatically created userattr entries
  Fhemweb allows attributes to be edited by clicking on them. However this did not work for attributes that match to a wildcard attribute in earlier versions. To circumvent this restriction HTTPMOD automatically added an entry for each instance of a defined wildcard attribute to the device userattr list. E.g. if you define a reading[0-9]Name attribute as reading01Name, HTTPMOD added reading01Name to the device userattr list. These entries only had the purpose of making editing in Fhemweb easier. In newer versions this has become obsolete.

Author's notes


• If you don't know which URLs, headers or POST data your web GUI uses, you might try a local proxy like BurpSuite to track requests and responses

HTTPSRV

Provides a mini HTTP server plugin for FHEMWEB. It serves files from a given directory. It optionally accepts a query string to set readings of this device if an attribute allows the given reading

HTTPSRV is an extension to FHEMWEB. You must install FHEMWEB to use HTTPSRV.

Define
define <name> HTTPSRV <infix> <directory> <friendlyname>

Defines the HTTP server. <infix> is the portion behind the FHEMWEB base URL (usually http://hostname:8083/fhem), <directory> is the absolute path the files are served from, and <friendlyname> is the name displayed in the side menu of FHEMWEB.

Example:

define myJSFrontend HTTPSRV jsf /usr/share/jsfrontend My little frontend
or
define kindleweb HTTPSRV kindle /opt/fhem/kindle Kindle Web
attr kindleweb readings KindleBatt



Set
n/a


Attributes


• directoryindex: if the request is sent with no filename, i.e. the infix (with or without trailing slash) only, the file given in this attribute is loaded. Defaults to index.html.
• readings: a comma separated list of reading names. If the request ends with a querystring like ?Batt=43 and an attribute is set like attr kindleweb readings Batt, then a reading with the Name of this Attribute (here Batt) is created with the value from the request.


Usage information


The above example on http://hostname:8083/fhem will return the file /usr/share/jsfrontend/foo.html for http://hostname:8083/fhem/jsf/foo.html. If no filename is given, the filename prescribed by the directoryindex attribute is returned.

Notice: All links are relative to http://hostname:8083/fhem.

HUEBridge

Module to access the bridge of the philips hue lighting system.

The actual hue bulbs, living colors or living whites devices are defined as HUEDevice devices.

All newly found lights and groups are autocreated at startup and added to the room HUEDevice.

Notes:
• This module needs JSON.
  Please install with 'cpan install JSON' or your method of choice.


Define
define <name> HUEBridge [<host>] [<interval>]

Defines a HUEBridge device with address <host>.

If [<host>] is not given the module will try to autodetect the bridge with the hue portal services.

The bridge status will be updated every <interval> seconds. The default and minimum is 60.

After a new bridge is created the pair button on the bridge has to be pressed.

Examples:
define bridge HUEBridge 10.0.1.1


Get
• lights
  list the lights known to the bridge.
• groups
  list the groups known to the bridge.
• scenes [detail]
  list the scenes known to the bridge.
• schedules [detail]
  list the schedules known to the bridge.
• startup
  show startup behavior of all known lights
• rule <id>
  list the rule with <id>.
• rules [detail]
  list the rules known to the bridge.
• sensors [detail]
  list the sensors known to the bridge.
• whitelist
  list the whitlist of the bridge.

Set
• autocreate [sensors]
  Create fhem devices for all light and group devices. sensors are autocreated only if sensors parameter is given.
• autodetect
  Initiate the detection of new ZigBee devices. After aproximately one minute any newly detected devices can be listed with get <bridge> devices and the corresponding fhem devices can be created by set <bridge> autocreate.
• delete <name>|<id>
  Deletes the given device in the bridge and deletes the associated fhem device.
• creategroup <name> <lights>
  Create a group out of <lights> in the bridge. The lights are given as a comma sparated list of fhem device names or bridge light numbers.
• deletegroup <name>|<id>
  Deletes the given group in the bridge and deletes the associated fhem device.
• savescene <name> <lights>
  Create a scene from the current state of <lights> in the bridge. The lights are given as a comma sparated list of fhem device names or bridge light numbers.
• modifyscene <id> <light> <light-args>
  Modifys the given scene in the bridge.
• scene <id>|&lr;name>
  Recalls the scene with the given id.
• deletescene <id>|&lr;name>
  Deletes the scene with the given id.
• updateschedule <id> <attributes json>
  updates the given schedule in the bridge with <attributes json>
• enableschedule <id>
  enables the given schedule
• disableschedule <id>
  disables the given schedule
• createrule <name> <conditions&actions json>
  Creates a new rule in the bridge.
• deleterule <id>
  Deletes the given rule in the bridge.
• updaterule <id> <json>
  Write specified rule's toplevel data.
• createsensor <name> <type> <uniqueid> <swversion> <modelid>
  Creates a new CLIP (IP) sensor in the bridge.
• deletesensor <id>
  Deletes the given sensor in the bridge and deletes the associated fhem device.
• configlight <id> <json>
  Sends the specified json string as configuration to the light <id>. You can use this e.g. to modify the startup behaviour of a light. For a full list of available options see: Config object attributes (free Hue developer account needed, use wisely)
• configsensor <id> <json>
  Write sensor config data.
• setsensor <id> <json>
  Write CLIP sensor status data.
• updatesensor <id> <json>
  Write sensor toplevel data.
• deletewhitelist <key>
  Deletes the given key from the whitelist in the bridge.
• touchlink
  perform touchlink action
• checkforupdate
  perform checkforupdate action
• statusRequest
  Update bridge status.
• swupdate
  Update bridge firmware. This command is only available if a new firmware is available (indicated by updatestate with a value of 2. The version and release date is shown in the reading swupdate.
  A notify of the form define HUEUpdate notify bridge:swupdate.* {...} can be used to be informed about available firmware updates.
  
• inactive
  inactivates the current device. note the slight difference to the disable attribute: using set inactive the state is automatically saved to the statefile on shutdown, there is no explicit save necesary.
  this command is intended to be used by scripts to temporarily deactivate the harmony device.
  the concurrent setting of the disable attribute is not recommended.
• active
  activates the current device (see inactive).

Attributes
• disable
• disabledForIntervals
• httpUtils
  0 -> use HttpUtils_BlockingGet
  1 -> use HttpUtils_NonblockingGet
  not set -> use old module specific implementation
• pollDevices
  1 -> the bridge will poll all lights in one go instead of each light polling itself independently
  2 -> the bridge will poll all devices in one go instead of each device polling itself independently
  default is 2. will be deleted if v2 api is detected and eventstream connects.
• createEventTimestampReading
  timestamp reading for every event received
  0 -> update reading without fhem event
  1 -> update reading with fhem event
  undef -> don't create reading
• createGroupReadings
  create 'artificial' readings for group devices.
  0 -> create readings only for group devices where createGroupReadings ist set to 1
  1 -> create readings for all group devices where createGroupReadings ist not set or set to 1
  undef -> do nothing
• forceAutocreate
  try to create devices even if autocreate is disabled.
• ignoreUnknown
  don't try to create devices after data or events with unknown references are received.
• queryAfterEvent
  the bridge will request the real button state 1 sec after the final event in a quick series. default is 0.
• queryAfterSet
  the bridge will request the real device state after a set command. default is 1.
• noshutdown
  Some bridge devcies require a different type of connection handling. raspbee/deconz only works if the connection is not immediately closed, the philips hue bridge now shows the same behavior. so this is now the default.

HUEDevice

Define
define <name> HUEDevice [group|sensor] <id> [<interval>]

Defines a device connected to a HUEBridge.

This can be a hue bulb, a living colors light or a living whites bulb or dimmer plug.

The device status will be updated every <interval> seconds. 0 means no updates. The default and minimum is 60 if the IODev has not set pollDevices to 1. The default ist 0 if the IODev has set pollDevices to 1. Groups are updated only on definition and statusRequest, but see createGroupReadings
Sensor devices will only be autocreated with deconz bridge devices. Use get <bridge> sensors will provide the sensor id vor manual definition.

Examples:
define bulb HUEDevice 1
define LC HUEDevice 2
define allLights HUEDevice group 0 define motion HUEDevice sensor 1


Readings
• bri
  the brightness reported from the device. the value can be betwen 1 and 254
• colormode
  the current colormode
• ct
  the colortemperature in mireds and kelvin
• hue
  the current hue
• pct
  the current brightness in percent
• onoff
  the current on/off state as 0 or 1
• sat
  the current saturation
• xy
  the current xy color coordinates
• state
  the current state

Notes:
• with current bridge firware versions groups have all_on and any_on readings, with older firmware versions groups have no readings.
• not all readings show the actual device state. all readings not related to the current colormode have to be ignored.
• the actual state of a device controlled by a living colors or living whites remote can be different and will be updated after some time.



Set
• on [<ramp-time>]
• off [<ramp-time>]
• toggle [<ramp-time>]
• statusRequest
  Request device status update.
• pct <value> [<ramp-time>]
  dim to <value>
  Note: the FS20 compatible dimXX% commands are also accepted.
• color <value>
  set colortemperature to <value> kelvin.
• bri <value> [<ramp-time>]
  set brighness to <value>; range is 0-254.
• dimUp [delta]
• dimDown [delta]
• ct <value> [<ramp-time>]
  set colortemperature to <value> in mireds (range is 154-500) or kelvin (range is 2000-6493).
• ctUp [delta]
• ctDown [delta]
• hue <value> [<ramp-time>]
  set hue to <value>; range is 0-65535.
• hueUp [delta]
• hueDown [delta]
• sat <value> [<ramp-time>]
  set saturation to <value>; range is 0-254.
• satUp [delta]
• satDown [delta]
• xy <x>,<y> [<ramp-time>]
  set the xy color coordinates to <x>,<y>
• alert [none|select|lselect]
• effect [none|colorloop] [{<json>}]
• transitiontime <time>
  set the transitiontime to <time> 1/10s
• rgb <rrggbb>
  set the color to (the nearest equivalent of) <rrggbb>


• delayedUpdate
• immediateUpdate


• savescene <id>
• deletescene <id>
• scene


• lights <lights>
  Only valid for groups. Changes the list of lights in this group. The lights are given as a comma sparated list of fhem device names or bridge light numbers.
• rename <new name>
  Renames the device in the bridge and changes the fhem alias.
• json [setsensor|configsensor] {<json>}
  send {<json>} to the state or config endpoints for this device.
• setsensor|configsensor|config {<json>}
  send {<json>} to the state or config endpoints for this device.
• setlight|configlight|config {<json>}
  send {<json>} to the state or config endpoints for this device. see: HUEBridge:configlight
• habridgeupdate [ : < on | off > ] [ : < bri | pct > < value > ]
  This command is only for usage of HA-Bridges that are emulating an Hue Hub.
  It updates your HA-Bridge internal light state of the devices without changing the devices itself.
  bri and pct have to be used in the same way as changing the brightness or dimvalue of the device.


• set extensions are supported.

Note:
• <ramp-time> is given in seconds
• multiple paramters can be set at once separated by :
  Examples:
  set LC on : transitiontime 100
set bulb on : bri 100 : color 4000
  

Get
• rgb
• RGB
• startup
  show startup behavior.
• devStateIcon
  returns html code that can be used to create an icon that represents the device color in the room overview.

Attributes
• color-icon
  1 -> use lamp color as icon color and 100% shape as icon shape
  2 -> use lamp color scaled to full brightness as icon color and dim state as icon shape
• createActionReadings
  create readings for the last action in group devices
• createGroupReadings
  create 'artificial' readings for group devices. default depends on the createGroupReadings setting in the bridge device.
• ignoreReachable
  ignore the reachable state that is reported by the hue bridge. assume the device is allways reachable.
• setList
  The list of know set commands for sensor type devices. one command per line, eg.:
attr mySensor setList present:{<json>}\
absent:{<json>}
• configList
  The list of know config commands for sensor type devices. one command per line, eg.:
attr mySensor mode:{<json>}\
/heatsetpoint (.*)/:perl:{'{"heatsetpoint":'. $VALUE1 * 100 .'}'}
/sensitivity (.*)/:0,1,2,3:{"sensitivity":$1}
• readingList
  The list of readings that should be created from the sensor state object. Space or comma separated.
• subType
  extcolordimmer -> device has rgb and color temperatur control
  colordimmer -> device has rgb controll
  ctdimmer -> device has color temperature control
  dimmer -> device has brightnes controll
  switch -> device has on/off controll
  
• transitiontime
  default transitiontime for all set commands if not specified directly in the set.
• delayedUpdate
  1 -> the update of the device status after a set command will be delayed for 1 second. usefull if multiple devices will be switched.
• devStateIcon
  will be initialized to {(HUEDevice_devStateIcon($name),"toggle")} to show device color as default in room overview.
• webCmd
  will be initialized to a device specific value according to subType.

HVAC_DaikinAC

This module can control indoor Daikin airconditioning units that have been equipped with a Daikin WiFi adapter. Supported adapters are:

• BRP069B41
• BRP069B42
• BRP069B43
• BRP069B45
• BRP069A81
• All integrated adapters

One HVAC_DaikinAC device is required for each indoor unit to be controlled. On multisplit systems, each indoor unit needs to be equipped with it's own Wifi adapter and be reachable for FHEM.

A unit can be specified with either a hostname or an IP address. As long as FHEM can resolve the hostname and reach the unit's Wifi adapter with a TCP connection to port 80, you should be ok.

All requests to the airconditioner are made using a nonblocking call. Only a single call can be active at any time. A default timeout of 5 seconds applies for all requests.

Normal execution flow:

• Device is defined.
• Initial poll is performed after 1 second if [ interval ] is not set to 0.
• Device will be repolled every [ interval ] seconds and readings updated. When powered on, the attribute is used.
• On the initial poll, the model and wifi adapter info will be polled. This info will not be automatically updated afterwards.
• If interval is set to 0, a poll can be initiated by running a "get update" command on the device. This get command can also be used to forcibly refresh the model and wifi adapter info
• On each poll, the htemp, hhum and otemp readings will always be updated, even if they are unchanged. That will make their last updated timestamp meaningful as a validity timestamp and these readings are most useful for interactive display, for example in TabletUI. All other readings will only be updated if they have changed.
• The htemp_ifchanged, hhum_ifchanged and otemp_ifchanged readings will only be updated if they are different from the previous reading. These can be used for logging purposes
• Any set command is sent to the airconditioner, and will be immediately followed by a poll. The set command itsself will never modify a reading. The change in the reading value will always be the result of the subsequent poll and therefore will be the current reading from the airconditioner unit.
• If the operation mode is changed (cool to heat, heat to vent, etc), the units stored temperature and humidity setting will be used for the new mode. Each mode has it's own stored temperature and humidity settings. The "stemp" and "shum" readings reflect the temperature and humidity setpoint for the currently active operation mode.

Define

define <name> HVAC_DaikinAC <hostname or ip> [interval] [interval_powered]

• hostname or ip: Hostname or IPv4 address of unit
• interval: Poll interval in seconds. Default value is 60. Set to 0 to disable automatic polling of the device.
• interval_powered: Poll interval in seconds as long as the device is turned on. Default value is 10. Set to 0 to disable automatic polling when on.

Examples:

• define MYDEVICENAME HVAC_DaikinAC 172.12.1.10
  create a device with name MYDEVICENAME. Unit has IP address 172.12.1.10. Use the default polling intervals (60 seconds when off, 10 seconds when powered on)
• define MYDEVICENAME HVAC_DaikinAC daikin-living.mydomainname 300 60
  create a device with name MYDEVICENAME. Unit can be reached through DNS name daikin-living.mydomainname. Set polling intervals to 300 seconds when turned off and 60 seconds when the unit is powered on.

Note: if interval is set to 0, but interval_powered is not (or left to it's default value of 10 seconds), the device will not be automatically polled. However, if it is turned on through FHEM, or a forced "set update" is run and the unit is turned on, the interval_powered setting is evaluated. This will cause automatic polling to start until the device is turned off again. This can be used for devices that are exclusively controlled through FHEM. In such a case, there is no need to keep polling the device when it's turned off if the temperature or humidity readings are not used for other purposes.

Readings

• power: [ on | off ] Unit's current power status (on or off)
• mode: [ auto | dehumidify | cool | heat | vent ] Current active mode
• rate: [ auto | silent | lowest | low | medium | high | highest ] Current fan speed setting
• swing: [ none | vertical | horizontal | 3d ] Current airflow swing setting
• stemp: Setpoint temperature (18 - 30 degrees C)
• shum: Humidity setpoint (0-100/5). Must be set with a number that is a multiple of 5. So 0, 5, 10, ... 95 or 100
• htemp: Measured indoor temperature (only valid if running)
• htemp_ifchanged: Measured indoor temperature (Equal to htemp, but only modified if value changed)
• otemp: Measured outdoor temperature (not always present, depends on unit type). For some unit types, this value is always present, even if turned off. Others only supply the outside temperature while the unit is running. Most units set this to "-" if not present.
• otemp_ifchanged: Measured outdoor temperature (Equal to otemp, but only modified if value changed)
• hhum: Current indoor relative humidity if supported
• hhum_hhum: Measured indoor relative humidity (Equal to hhum, but only modified if value changed)
• adv: List of currently active additional settings, slash seperated (2=powerful, 13=streamer)
• powerful: [ on | off ] Current status of "Powerful" special mode (powerful ventilation, automatically turned off by unit after 20 mins)
• econo: [ on | off ] Current status of "Econo" special mode (econo mode)
• streamer: [ on | off ] Current status of "Streamer" special mode (ionized air cleaner)
• cmpfreq: Current compressor frequency in number of revolutions per second
• cmpfreq_max: Maximum compressor frequency observed since creation
• name: Unit name (can be changed using the Daikin online controller app)
• mac: MAC address of Wifi unit's adapter
• id: Username in use with Daikin online controller if this unit is registered for the service
• pw: Password that is in use with Daikin online controller service
• port: TCP port number in use for communcations with Daikin online controller
• rev: Revision of Wifi adapter
• ver: Software version for Wifi adapter
• model: Model name of unit if supported
• method: Currently selected protocol for communications (should be "polling")
• mompow: Current (momentary) power usage (in kW, 100W resolution). Forced to 0 is the unit is turned off, as most units seem to report a 100W value in idle mode, even though the unit does not consume anywhere close to 100W while turned off.
• mompow_max: Maximum value for mompow observed since device creation
• reg: Area/country of registration (EU for EU models)
• type: Unknown (all units here I've send always have "N" stored here)

The readings below are for internal use, but might prove useful

• dh1: Stored humidity setpoint for mode 1 (auto)
• dh3: Stored humidity setpoint for mode 3 (cool)
• dh4: Stored humidity setpoint for mode 3 (heat)
• dt1: Stored temperature setpoint for mode 1 (auto)
• dt3: Stored temperature setpoint for mode 3 (cool)
• dt4: Stored temperature setpoint for mode 3 (heat)
• f_dir: Airflow swing setting (0=off, 1=vertical, 2=horizontal, 3=3D)
• f_rate: Fan speed setting (A=auto, B=silent, 3=lowest .. 7=highest)
• f_moode: Operation mode (1=auto, 2=dehumidify, 3=cool, 4=heat, 6=fan)
• pow: Power status numeric (0=off, 1=on)

The readings below are only stored when the pwrconsumption attribute is set to 1

• unit_date: Current date and time according to the unit. This is used as the basis for all data represented below. If the unit is in a different timezone (or set at an offset), the hour, day and month breaks will not sync up with the system date and time. That will not cause any problems, but the data might be harder to interpret.
• pwr_hour_cur: Power consumption for current hour. On all units that I have observed, power readings are updated just once per hour and this reading will always read 0.
• pwr_hour_last: Power consumption for last complete hour. Updated once per hour. Good for logging and plotting in a graph.
• pwr_day_cur: Power consumption for current day up to now. Updated once every hour for most units
• pwr_day_last: Power consumption for previous day. Similar to pwr_hour_last. Updated once per day.
• pwr_month_cur: Power consumption for current calendar month to date. Updated once per hour for most units
• pwr_month_last: Power consumption for previous calendar month. Updated once per month.
• pwr_year_cur: Power consumption for current calendar year to date. Updated once per hour for most units
• pwr_year_last: Power consumption for previous calendar year. Updated once per year.
• pwr_history_hourly_today: Power consumption history for today, per hour. Updated once per hour. This is a comma seperated list with 24 values, each representing an hourly slice of the day. The value at position 0 represents the timeframe from midnight to 1am and so forth. Last value will always be 0 (day will rollover as soon as the hourly data for that hour is known)
• pwr_history_hourly_yesterday: same as pwr_history_hourly_today, but for previous day.
• pwr_history_daily_: Power consumption history calendar month, per day. Updated once per day. This is a comma seperated list with 31 values. The value at position 0 represents day 1 and so forth. There will be no value (empty string) for any days that are non-existant in this month. Month names are "jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov" and "dec". Only the current and previous month are retained in the unit and will be created upon device definition.
• pwr_history_monthly_: Power consumption history for complete calendar year , per month. Updated once per month. This is a comma seperated list with 12 values. The value at position 0 represents the month of january and so forth. Only the current and previous year are retained in the unit and will be created upon device definition.

Attributes

• disable: [ 0 | 1 ] If set to 1, disable all polling. Set will not be possible on a disabled device. If you just need to stop automatic polls, use the "interval" attribute
• interval: Set the polling interval (in seconds). This will override the interval as set in the define command. If set to "0", no more scheduled polling will happen. However, the device will be polled one time directly following a "set" command so that the requested change is reflected in the readings. A poll can also be forced by issuing the "set refresh" command. Keep in mind that any change in ambient or outside temperature will not be reflected in FHEM. Also, any changes resulting from a control action that was initiated through another channel (e.g. the remote control or Daikin's online controller) will not be reflected in the FHEM device readings.
• interval_powered: Set the polling interval (in seconds) in case the unit is turned on.
• pwrconsumption: [ 0 | 1 ] If set to 1, power consumption data is read from the unit and stored in the readings specified above. This is not supported by older units, who will return all 0 readings for power usage. All consumption data is represented in kWh, as a floating point number with a precision of 1/10 kWh. For all of the the pwr_period_last readings readings to be correctly updated, automatic polling must be enabled with an interval of at most 3600 seconds (1 hour).
• rawdata: [ 0 | 1 ] If set to 1, 4 extra readings will be generated:
  • basic_info: Raw data from get_basic_info request (on new define or after "set refresh")
  • model_info: Raw data from get_model_info request (on new define or after "set refresh")
  • sensor_info: Raw data from get_sensor_info request (on each poll or after set command)
  • control_info: Raw data from get_control_info request (on each poll or after set command)
• timeout: Sets the request timeout - default 5 seconds. Any request to the airconditioner will be aborted after this interval and readings will not be updated. Only set to a higher value if you have a very slow or unreliable network connection to the airconditioner and you are aware of what you are doing. A value as low a 1 second should work just fine under normal circumstances.

If using the FHEM standard web frontend, you can use the stateFormat and devStateIcon attributes to visualize the current state and temperature readings. The default setting is:

attr [devicename] stateFormat power/mode\
<br>In: htemp &degC <br>Out: otemp &degC
attr [devicename] devStateIcon off.*:control_standby@gray on.*cool:frost@blue on.*heat:sani_heating@red on.*dehumidify:humidity@blue on.*vent:vent_ventilation@green on.*auto:temp_temperature@red

Set

• refresh: Force immediate poll of device - will also request and update version and device info
• power: [ on | off ] Set power status (on or off)
• on: Shortcut for "power on"
• off: Shortcut for "power off"
• mode: [ auto | dehumidify | cool | heat | vent ] Set new operation mode
• rate: [ auto | silent | lowest | low | medium | high | highest ] Set fan speed (silent not supported on all Wifi controllers, even if the unit itsself supports the mode)
• swing: [ none | vertical | horizontal | 3d ] Set airflow swing setting (horizontal or 3D not present on all units)
• stemp: Set setpoint temperature. Can be an absolute temperature (resolution 0.5 degrees) or an offset (prefix with + or -, e.g. "set stemp -0.5" or "set stemp -2")
• shum: Set humidity setpoint if supported. Valid numbers are between 0 and 100 and a multiple of 5. An offset can be set in a similar way as with stemp. The offset needs to be a multiple of 5 as well.
• powerful: [ on | off ] Activate or deactivate powerful mode if unit supports remote activation. Older models will not support this option, even though the powerful mode is present and can be controlled through the IR remote.
• streamer: [ on | off ] Activate or deactivate ion streamer mode if present
• econo: [ on | off ] Activate or deactivate econo mode if present and units supports remote activation
• reboot: Reboots the units' wifi module

Get

No parameters at this time

Logging

A log definition that will allow you to track and graph the units' status, power usage and temperature and humidity readings without clogging up the file with unneccesary log entries should include the following readings:

pwr.*_last, pwr_year_cur, power, pow, cmpfreq, mompow, stemp, shum, mode, rate, swing, powerful, streamer, econo, .*_ifchanged

It might include other readings, but never htemp, hhum, or otemp or unit_date, as these readings are produced on each poll.

For example, for an FHEM device named MYDAIKINAC:

  define MYDAIKINAC_LOG FileLog mydaikinac-%Y.log MYDAIKINAC:(pwr.*_last|pwr_year_cur|power|pow|cmpfreq|mompow|stemp|shum|mode|rate|swing|powerful|streamer|econo|.*_ifchanged:.*
  

Notes

• Be careful if you are thinking about using the htemp reading as a temperature input for other devices (room thermostat for example). The reading does not seem to be reliable when the airconditioner is not turned on.
• Behaviour on US based models using a fahrenheit scale is unknown. If you have one of those, I'ld love to hear from you.
• If you have issues with your aircon, please report back and include the readings that are returned if you set the attribute "rawdata" to 1.
• If there are other modes that you can set using the Daikin online controller app that are not present in this module, please let me know and include the readings that are returned if you set the attribute "rawdata" to 1 and turn the function on and off through the Daikin app.

Tablet UI

An example Tablet UI frontend can be found in this topic on the FHEM forum

HXB

[EN DE]

Define
define <name> HXB

Defines a Hexabus. You need one Hexabus to receive multicast messages from Hexabus devices. Have a look at the Hexabus wiki for more information on Hexabus.

You need the perl modules IO::Socket::Multicast6 and Digest::CRC. Under Debian and its derivatives they are installed with apt-get install libio-socket-multicast6-perl libdigest-crc-perl.

HXBDevice

[EN DE]

Define
define <name> HXB <IPv6Address>

Defines a Hexabus device at the IPv6 address <IPv6Address>. You need one Hexabus to receive multicast messages from Hexabus devices. Have a look at the Hexabus wiki for more information on Hexabus.

Example: define myPlug fd01:1::50:c4ff:fe04:81ad

Hunter Hydrawise

[EN DE]

The module receives data and sends commands via the Hunter Hydrawise API.
All zones are identified by a unique ID - this ID is used to modify zone watering schedules, including running a zone, stopping a zone and suspending a zone for a period of time. Status information on all zones associated with an account can also be queried.

Prerequisits

API keys can be obtained from your Hydrawise account under My Account -> Generate API Key. This has the format XXXX-XXXX-XXXX-XXXX.


Definition and usage

The module is defined using the API key and the refresh interval!


Definition of the module


define <name> HYDRAWISE <API-KEY> <Interval>



Example of a definition:


define myHydrawise HYDRAWISE 1234-5678-90AB-CDEF 60


Set


renewcontext	Returns details of all controllers associated with the customer account.
renewRelays	Return of irrigation plans for control units
run	Execute a zone for a certain period of time. 2 Parameters: "relay_id" "time_in_seconds
runall	Execute all zones for a certain period of time. 1 Parameter: "time_in_seconds"
stop	Stops a zone. 1 Parameter: "relay_id"
stopall	Stops all running zones.
suspend	Suspends a zone for a certain time. 3 Parameters: "relay_id" "DD.MM.YYYY" "HH24:MI".
suspendall	Suspends all zones for a certain time. 2 Parameters: "DD.MM.YYYY" "HH24:MI"


Get


help	Displays help for the SET commands


Readings



controller_counts	Number of available controllers
controller_id	Controller ID
ct1_controller_id	Controler 1: ID
ct1_controller_message	Controler 1: Status message from Hydrawise
ct1_controller_name	Controler 1: Defined name in Hydrawise
ct1_last_contact	Controler 1: Last contact from Hydrawise to the controller
ct1_serial_number	Controler 1: Serial number of the controller
cur_controller_id	Current Controller (ID)
cur_controller_name	Current Controller name
customer_id	Customer ID of Hydrawise
presence	Status of the module: presence or absent
relay_counts	Number of relays
rl1_name	Relay 1: Name
rl1_next	Relay 1: Next time this zone will water
rl1_relay	Relay 1: Physical zone number
rl1_relay_id	Relay 1: Unique ID for this zone
rl1_run_minutes	Relay 1: Length of next run time. If a run is in progress value will indicate number of seconds remaining.

Hideki

[EN DE]

The Hideki module is a module for decoding weather sensors, which use the hideki protocol. Known brands are Bresser, Cresta, TFA and Hama.

Supported Brands
• Arduinos with remote Sensor lib from Randy Simons
• Bresser
• Cresta
• Hama
• Hideki (Anemometer | UV sensor | Rain level meter | Thermo/hygro-sensor)
• TFA Dostman
• all other devices, which use the Hideki protocol
Please note, currently temp/hum devices are implemented. Please report data for other sensortypes.

Define
define <name> Hideki <code>


• <code> is the address of the sensor device and is build by the sensor type and the channelnumber (1 to 5) or if the attribute longid is specfied an autogenerated address build when inserting the battery (this adress will change every time changing the battery).


• If autocreate is enabled, the device will be defined via autocreate. This is also the preferred mode of defining such a device.



Generated readings
• battery & batteryState (ok or low)
• channel (The Channelnumber (number if)
• humidity (0-100)
• state (T:x.xx H:y B:z)
• temperature (°C)

- Hideki only -
• comfort_level (Status: Humidity OK... , Wet. More than 69% RH, Dry. Less than 40% RH, Temperature and humidity comfortable)
• package_number (reflect the package number in the stream starting at 1)


Set
N/A

Get
N/A

Attributes
• do_not_notify
• eventMap
• ignore
• readingFnAttributes
• showtime
• windDirCorr
  correction value of your displayed wind direction deztimal degree value. The correction value is added to the measured direction in dgrees.
  Example value: 5
  Default value: 0
  
• windSpeedCorr
  correction value of your displayed wind speed as floatingpoint value. The measured speed is multiplied with the specified value. The value 0 disables the feature.
  Example value: 1.25
  Default value: 1
  

HourCounter

[EN DE]

Define

define <name> HourCounter <pattern_for_ON> [<pattern_for_OFF>]

Hourcounter can detect both the activiy-time and the inactivity-time of a property.
The "pattern_for_ON" identifies the events, that signal the activity of the desired property.
The "pattern_for_OFF" identifies the events, that signal the inactivity of the desired property.

If "pattern_for_OFF" is not defined, any matching event of "patter_for_ON" will be counted.
Otherwise only the rising edges of "pattern_for_ON" will be counted.
This means a "pattern_for_OFF"-event must be detected before a "pattern_for_ON"-event is accepted.

"pattern_for_ON" and "pattern_for_OFF" must be formed using the following structure:

device:[regexp]

The forming-rules are the same as for the notify-command.

Example:

define BurnerCounter HourCounter SHUTTER_TEST:on SHUTTER_TEST:off

Set-Commands

set <name> calc

starts the calculation of pulse/pause-time.

set <name> clear

clears the readings countsPerDay, countsOverall,pauseTimeIncrement, pauseTimePerDay, pauseTimeOverall, pulseTimeIncrement, pulseTimePerDay, pulseTimeOverall by setting to 0.
The reading clearDate is set to the current Date/Time.

set <name> countsOverall <value>

Sets the reading countsOverall to the given value.This is the total-counter.

set <name> countsPerDay <value>

Sets the reading countsPerDay to the given value. This reading will automatically be set to 0, after change of day.

set <name> pauseTimeIncrement <value>

Sets the reading pauseTimeIncrement to the given value.
This reading in seconds is automatically set after a rising edge.

set <name> pauseTimeEdge <value>

Sets the reading pauseTimeEdge to the given value.
This reading in seconds is automatically set after a rising edge.

set <name> pauseTimeOverall <value>

Sets the reading pauseTimeOverall to the given value.
This reading in seconds is automatically adjusted after a change of pauseTimeIncrement.

set <name> pauseTimePerDay <value>

Sets the reading pauseTimePerDay to the given value.
This reading in seconds is automatically adjusted after a change of pauseTimeIncrement and set to 0 after change of day.

set <name> pulseTimeIncrement <value>

Sets the reading pulseTimeIncrement to the given value.
This reading in seconds is automatically set after a falling edge of the property.

set <name> pulseTimeEdge <value>

Sets the reading pulseTimeEdge to the given value.
This reading in seconds is automatically set after a rising edge.

set <name> pulseTimeOverall <value>

Sets the reading pulseTimeOverall to the given value.
This reading in seconds is automatically adjusted after a change of pulseTimeIncrement.

set <name> pulseTimePerDay <value>

Sets the reading pulseTimePerDay to the given value.
This reading in seconds is automatically adjusted after a change of pulseTimeIncrement and set to 0 after change of day.

set <name> forceHourChange

This modifies the reading tickHour, which is automatically modified after change of hour.

set <name> forceDayChange

This modifies the reading tickDay, which is automatically modified after change of day.

set <name> forceWeekChange

This modifies the reading tickWeek, which is automatically modified after change of week.

set <name> forceMonthChange

This modifies the reading tickMonth, which is automatically modified after change of month.

set <name> forceYearChange

This modifies the reading tickYear, which is automatically modified after change of year.

set <name> app.* <value>

Any reading with the leading term "app", can be modified.
This can be useful for user-readings.

Get-Commands

get <name> version

Get the current version of the module.

Attributes

• interval
  the update interval for pulse/pause-time in minutes [default 60]

• readingFnAttributes

Additional information

• Discussion in FHEM forum

• WIKI information in FHEM Wiki

• The file 99_UtilsHourCounter.pm is a reference implementation for user defined extensions.
  It shows how to create sum values for hours,days, weeks, months and years.
  This file is located in the sub-folder contrib. For further information take a look to FHEM Wiki.

Husqvarna Automower with Connect Module (SIM)

[EN DE]

Requirements


• This module allows the communication between the Husqvarna Cloud and FHEM.
• You can control any Automower that is equipped with the original Husqvarna Connect Module (SIM).
• The Automower must be registered in the Husqvarna App beforehand.

Define
define <name> HusqvarnaAutomower

Beispiel:

define myMower HusqvarnaAutomower
attr myMower username YOUR_USERNAME
attr myMower password YOUR_PASSWORD



You must set both attributes username and password. These are the same that you use to login via the Husqvarna App.

Set
• startTimer - Start with next timer (Caution: might not start mowing immdiately)
• start3h - Starts immediately for 3 hours
• start6h - Starts immediately for 6 hours
• start9h - Starts immediately for 9 hours
• stop - Stops/pauses mower immediately at current position
• park - Parks mower in charging station until further notice
• parkTimer - Parks mower in charging station and starts with next timer
• update - Updates the status

Attributes
• username - Email that is used in Husqvarna App
• password - Password that is used in Husqvarna App

Optional attributes
• mower - ID of Automower, if more that one is registered. Default: 0
• interval - Time in seconds that is used to get new data from Husqvarna Cloud. Default: 300
• language - language setting, EN = original messages, DE = german translation. Default: DE

Readings
• expires - date when session of Husqvarna Cloud expires
• batteryPercent - Battery power in percent
• mower_id - ID of the mower
• mower_battery - Battery power in percent
• mower_commandStatus - Status of the last sent command
• mower_lastLatitude - last known position (latitude)
• mower_lastLongitude - last known position (longitude)
• mower_mode - current working mode (e. g. AUTO)
• mower_name - name of the mower
• mower_nextStart - next start time
• mower_state - current status (e. g. OFF_HATCH_CLOSED_DISABLED, PARKED_IN_CS)
• mower_cuttingMode - mode of cutting area (e. g. MAIN_AREA)
• mower_nextStartSource - detailed status (e. g. COMPLETED_CUTTING_TODAY_AUTO)
• mower_restrictedReason - reason for parking (e. g. SENSOR)
• provider - should be Husqvarna
• state - status of connection to Husqvarna Cloud (e. g. connected)
• token - current session token of Husqvarna Cloud
• user_id - your user ID in Husqvarna Cloud

Hyperion

[EN DE]

With Hyperion it is possible to change the color or start an effect on a hyperion server.
It's also possible to control the complete color calibration (changes are temorary and will not be written to the config file).
The Hyperion server must have enabled the JSON server.
You can also restart Hyperion with different configuration files (p.e. switch input/grabber)



Define

define <name> Hyperion <IP or HOSTNAME> <PORT> [<INTERVAL>]


<INTERVAL> is optional for periodically polling.

After defining "get <name> statusRequest" will be called once automatically to get the list of available effects and the current state of the Hyperion server.

Example for running Hyperion on local system:


define Ambilight Hyperion localhost 19444 10


Example for running Hyperion on remote system:


define Ambilight Hyperion 192.168.1.4 19444 10



To change config files on your running Hyperion server or to stop/restart your Hyperion server you have to put the following code into your sudoers file (/etc/sudoers) (visudo):


fhem ALL=(ALL) NOPASSWD:/usr/bin/hyperiond,/bin/kill



set <required> [optional]

• active
  activates the device (similar to attr disable but without the need of saving)
• addEffect <custom_name>
  add the current effect with the given name to the custom effects
  can be altered after adding in attribute hyperionCustomEffects
  device has to be in effect mode with a non-custom effect and given name must be a unique effect name
• adjustBlue <0,0,255>
  adjust each color of blue separately (comma separated) (R,G,B)
  values from 0 to 255 in steps of 1
• adjustGreen <0,255,0>
  adjust each color of green separately (comma separated) (R,G,B)
  values from 0 to 255 in steps of 1
• adjustRed <255,0,0>
  adjust each color of red separately (comma separated) (R,G,B)
  values from 0 to 255 in steps of 1
• binary <restart/stop>
  restart or stop the hyperion binary
  only available after successful "get <name> configFiles"
• blacklevel <0.00,0.00,0.00>
  adjust blacklevel of each color separately (comma separated) (R,G,B)
  values from 0.00 to 1.00 in steps of 0.01
• clear <1000>
  clear a specific priority channel
• clearall
  clear all priority channels / switch to Ambilight mode
• colorTemperature <255,255,255>
  adjust temperature of each color separately (comma separated) (R,G,B)
  values from 0 to 255 in steps of 1
• configFile <filename>
  restart the Hyperion server with the given configuration file (files will be listed automatically from the given directory in attribute hyperionConfigDir)
  please omit the double extension of the file name (.config.json)
  only available after successful "get <name> configFiles"
• correction <255,255,255>
  adjust correction of each color separately (comma separated) (R,G,B)
  values from 0 to 255 in steps of 1
• dim <percent> [duration] [priority]
  dim the rgb light to given percentage with optional duration in seconds and optional priority
• dimDown [delta]
  dim down rgb light by steps defined in attribute hyperionDimStep or by given value (default: 10)
• dimUp [delta]
  dim up rgb light by steps defined in attribute hyperionDimStep or by given value (default: 10)
• effect <effect> [duration] [priority] [effectargs]
  set effect (replace blanks with underscore) with optional duration in seconds and priority
  effectargs can also be set as very last argument - must be a JSON string without any whitespace
• gamma <1.90,1.90,1.90>
  adjust gamma of each color separately (comma separated) (R,G,B)
  values from 0.00 to 5.00 in steps of 0.01
• inactive
  deactivates the device (similar to attr disable but without the need of saving)
• luminanceGain <1.00>
  adjust luminanceGain
  values from 0.00 to 5.00 in steps of 0.01
• luminanceMinimum <0.00>
  adjust luminanceMinimum
  values from 0.00 to 5.00 in steps of 0.01
• mode <clearall|effect|off|rgb>
  set the light in the specific mode with its previous value
• off
  set the light off while the color is black
• on
  set the light on and restore previous state
• reopen
  reopen the connection to the hyperion server
• rgb <RRGGBB> [duration] [priority]
  set color in RGB hex format with optional duration in seconds and priority
• saturationGain <1.10>
  adjust saturationGain
  values from 0.00 to 5.00 in steps of 0.01
• saturationLGain <1.00>
  adjust saturationLGain
  values from 0.00 to 5.00 in steps of 0.01
• threshold <0.16,0.16,0.16>
  adjust threshold of each color separately (comma separated) (R,G,B)
  values from 0.00 to 1.00 in steps of 0.01
• toggle
  toggles the light between on and off
• toggleMode
  toggles through all modes
• valueGain <1.70>
  adjust valueGain
  values from 0.00 to 5.00 in steps of 0.01
• whitelevel <0.70,0.80,0.90>
  adjust whitelevel of each color separately (comma separated) (R,G,B)
  values from 0.00 to 1.00 in steps of 0.01



Get

• configFiles
  get the available config files in directory from attribute hyperionConfigDir
  File names must have no spaces and must end with .config.json .
  For non-local Hyperion servers you have to configure passwordless SSH login for the user running fhem to the Hyperion server host (http://www.linuxproblem.org/art_9.html), with attribute hyperionSshUser you can set the SSH user for login.
  Please watch the log for possible errors while getting config files.
• devStateIcon
  get the current devStateIcon
• statusRequest
  get the state of the Hyperion server,
  get also the internals of Hyperion including available effects



Attributes

• disable
  stop polling and disconnect
  default: 0
• disabledForIntervals
  stop polling in given time frames
  default:
• hyperionBin
  path to the hyperion daemon
  OpenELEC users may set hyperiond.sh as daemon
  default: /usr/bin/hyperiond
• hyperionConfigDir
  path to the hyperion configuration files
  default: /etc/hyperion/
• hyperionCustomEffects
  space separated list of JSON strings (without spaces - please replace spaces in effect names with underlines)
  must include name (as diplay name), oname (name of the base effect) and args (the different effect args), only this order is allowed (if different an error will be thrown on attribute save and the attribut value will not be saved).
  example: {"name":"Knight_Rider_speed_2","oname":"Knight_rider","args":{"color":[255,0,255],"speed":2}} {"name":"Knight_Rider_speed_4","oname":"Knight_rider","args":{"color":[0,0,255],"speed":4}}
• hyperionDefaultDuration
  default duration
  default: 0 = infinity
• hyperionDefaultPriority
  default priority
  default: 0 = highest priority
• hyperionDimStep
  dim step for dimDown/dimUp
  default: 10 (percent)
• hyperionGainStep
  valueGain step for valueGainDown/valueGainUp
  default: 0.1
• hyperionNoSudo
  disable sudo for non-root ssh user
  default: 0
• hyperionSshUser
  user name for executing SSH commands
  default: pi
• hyperionToggleModes
  modes and order of toggleMode as comma separated list (min. 2 modes, max. 4 modes, each mode only once)
  default: clearall,rgb,effect,off
• hyperionVersionCheck
  disable hyperion version check to (maybe) support prior versions
  DO THIS AT YOUR OWN RISK! FHEM MAY CRASH UNEXPECTEDLY!
  default: 1
• queryAfterSet
  If set to 0 the state of the Hyperion server will not be queried after setting, instead the state will be queried on next interval query.
  This is only used if periodically polling is enabled, without this polling the state will be queried automatically after set.
  default: 1



Readings

• adjustBlue
  each color of blue separately (comma separated) (R,G,B)
• adjustGreen
  each color of green separately (comma separated) (R,G,B)
• adjustRed
  each color of red separately (comma separated) (R,G,B)
• blacklevel
  blacklevel of each color separately (comma separated) (R,G,B)
• colorTemperature
  temperature of each color separately (comma separated) (R,G,B)
• configFile
  active/previously loaded configuration file, double extension (.config.json) will be omitted
• correction
  correction of each color separately (comma separated) (R,G,B)
• dim
  active/previous dim value (rgb light)
• duration
  active/previous/remaining primary duration in seconds or infinite
• effect
  active/previous effect
• effectArgs
  active/previous effect arguments as JSON
• gamma
  gamma for each color separately (comma separated) (R,G,B)
• id
  id of the Hyperion server
• lastError
  last occured error while communicating with the Hyperion server
• luminanceGain
  current luminanceGain
• luminanceMinimum
  current luminanceMinimum
• mode
  current mode
• mode_before_off
  previous mode before off
• priority
  active/previous priority
• rgb
  active/previous rgb
• saturationGain
  active saturationGain
• saturationLGain
  active saturationLGain
• serverResponse
  last Hyperion server response (success/ERROR)
• state
  current state
• threshold
  threshold of each color separately (comma separated) (R,G,B)
• valueGain
  valueGain - gain of the Ambilight
• whitelevel
  whitelevel of each color separately (comma separated) (R,G,B)

I2C_ADS1x1x

[EN DE]

(en | de)

Provides an interface to an ADS1x1x A/D converter via I2C.
The I2C messages are send through an I2C interface module like RPII2C, FRM or NetzerI2C so this device must be defined first.

Limitations:
For simplification most settings can only be set for all 4 channels globally.
Comparator Mode (delta between two channels) is not supported.
Temperatures are in centigrade only


Special features:
Device supports reading voltages (RAW), resistance (RES) with divider resistor and temperature measurements of RTD (Platin Resistors like PT1000 or PT100) and NTC.

Circuit:
To measure resistance and temperature (thermistors) your circuit should look like this:
(T)----GND
|
|-----(A0)-----(R0)-----VCC

T= Temperature Sensor or Resistor
R0= Pull-up Resistor (typically in the same range as the resistance you measure (e.g 1KOhm for PT1000)
A0= Connected to A0 Port of ADS1x1x (same for A1,A2,A3)


Attribute IODev must be set. This is typically the name of a defined RPII2C device

Define
define <name> I2C_ADS1x1x <I2C Address>
where <I2C Address> is without direction bit


Set
• update
  set <name> update
  Trigger a reading. Resets the timers so the first reading will start within 1s - continuing with the other channels based on the polling_interleave attribute.
  
  
Attributes
• device
  Defines the Texas Instruments ADS1x1x device that is actually being used.
  • ADS1013 - 12Bit, 1 channel
  • ADS1014 - 12Bit, 1 channel with Comparator
  • ADS1015 - 12Bit, 4 channels with Comparator
  • ADS1113 - 16Bit, 1 channel
  • ADS1114 - 16Bit, 1 channel with Comparator
  • ADS1115 - 16Bit, 4 channels with Comparator
  
  Note that the comparator feature is not supported by this module (so no difference between ADSxx13 and ADSxx14 is made).
  Default: ADS1115
  


• poll_interval
  Set the polling interval in minutes to query a new reading from enabled channels
  By setting this number to 0, the device can be set to manual mode (new readings only by "set update").
  Default: 5, valid values: decimal number
  


• poll_interleave
  Interleave between reading 2 channels in seconds (only valid for multi channel devices). Can be used to distribute the load more evenly.
  Default: 0.008, valid values: decimal number
  


• sys_voltage
  System voltage running the chip and typically connected to the pull-up resistor (e.g. 3.3V with a Raspberry Pi)
  Default: 3.3, valid values: float number
  


• decimals
  Number of decimals (after the decimal point) for voltage and resistance to make results more readable. Calculations are still based on full precision. Temperatures are fixed to one decimal.
  Default: 3, valid values: 0,1,2,3,4,5
  


• a[0-3]_gain
  Gain amplifier value (sensibility and range of measurement) used per channel a0-a3. Standard is 4V which can measure a range between 0 and 4 Volts. If measuring smaller voltage, the amplification can be increased to get more accurate readings. The module will automatically calculate the value back to the correct voltage output.
  Default: 4V, valid values: 6V,4V,2V,1V,0.5V,0.25V
  


• a[0-3]_mode
  Determines how the results are interpreted.
  • off: The channel is not measured
  • RAW: Only voltage is measured and placed in reading a[0-3]_voltage
  • RES: Plain resistor measurement, typically needs a pull-up resistor defined by a[0-3]_res. Reading in a[0-3]_resistance
  • RTD: For Platin temperature resistors (PT1000,PT100), like RES needs a pull-up and also reference resistance at 0°C in a[0-3]_r0. Reading in a[0-3]_temperature
  • NTC: For NTC Thermistors, like RES needs a pull-up, reference resistance at 25°C in a[0-3]_r0 and B-value in a[0-3]_b. Reading in a[0-3]_temperature


• a[0-3]_res
  Value of pull-up resistor for resistance and temperature measurement. Connected between A0 and VCC (defined in "sys_voltage")
  Default: 1000, valid values: float numbers
  


• a[0-3]_r0
  Reference resistance for temperature measurements at 0°C (for RTD) and 25°C (for NTC) in Ohm.
  Default: 1000.0 in RTD and 50000.0 in NTC mode, valid values: float numbers
  


• a[0-3]_bval
  B-Value for NTC Thermistors (define the increase from the base value).
  Default: 3950.0, valid values: float numbers
  


• a[0-3]_avg
  Sometimes measurements can fluctuate. To get smoother values, this attribute will enable creating an average of n numbers, which should result in more stable results.
  Default: 1, valid values: integers
  


• data_rate (1/16x,1/8x,1/4x,1/2x,1x,2x,4x,8x )
  
  Conversion speed - default is 1x. The 12-bit chips use 1600 SPS as default rate, while the 16-bit chips are slower with 128 SPS. Below table translates the settings based on the actual device used.
  
  

  Data Rate	ADS101x Setting	ADS111x Settings
  1/16x	128_SPS	8_SPS
  1/8x	250_SPS	16_SPS
  1/4x	490_SPS	32_SPS
  1/2x	920_SPS	64_SPS
  1x (default)	1600_SPS	128_SPS
  2x	2400_SPS	250_SPS
  4x	3300_SPS	475_SPS
  8x	3300_SPS	860_SPS




The following entries are only valid in comparator mode and with thresholds which are currently disabled or not implemented, since my use case is a plain 4-channel A/D conversion.
Please refer to ADS1x1x chip documentation for more details on the effect of these settings.
If you have a valid use case, please contact me in the FHEM forum to discuss a potential implementation.


• operation_mode
  
  Not implemented, since Continuous Mode make no sense when using multiple input registers and is meant to read values in very high speed (e.g. one value every 8 ms) which IMHO makes no sense with FHEM.
  
  • SingleShot: Do one reading and then power down
  • Continuously: Keep powered on and continiously read data
• comparator_mode (Traditional|Window)
  
  Not implemented.


• comparator_polarity (ActiveHigh|ActiveLow)
  
  Not implemented.


• comparator_queue_disable (AfterOneConversion|AfterTwoConversions|AfterFourConversions|disable)
  
  Define for how many conversions the chip remains active (powered on)
  


• latching_comparator (on|off)
  
  Not implemented.

I2C_BH1750

[EN DE]

Module for the I²C BH1750 light sensor. The BH1750 sensor supports a luminous flux from 0 up to 120k lx and a resolution up to 0.11lx. It supports different modes to be able to cover this large range of data.
The I2C_BH1750 module tries always to get the luminosity data from the sensor as good as possible. To achieve this the module first reads flux data in the least sensitive mode and then decides which mode to take to get best results.

For the I²C bus the same things are valid as described in the I2C_TSL2561   module.
Define

define BH1750 I2C_BH1750 [I2C address]

I2C address must be 0x23 or 0x5C (if omitted default address 0x23 is used)
Examples:

        # define IO-Module:
        define I2C_2 RPII2C 2
        # Use IODev I2C_2 with default i2c address 0x23
        # set poll interval to 1 min
        # generate luminosity value only if difference to last value is at least 10%
        define BH1750 I2C_BH1750
        attr BH1750 IODev I2C_2
        attr BH1750 poll_interval 1
        attr BH1750 percentdelta 10
      

Set
• set <device name> update
  Force immediate illumination measurement and restart a new poll_interval. Note that the new readings are not yet available after set returns because the measurement is performed asynchronously. Depending on the flux value this may require more than one second to complete.
  
• set <device name> deleteminmax
  Delete the minimum maximum readings to start new min/max measurement

Readings

• luminosity
  Illumination measurement in the range of 0 to 121557 lx.
  The generated luminosity value is stored with up to one fractional digit for values below 100 and rounded to 3 significant digits for all other values. Compared with the accuracy of the sensor it makes no sense to store the values with more precision.
• minimum
  minimum of measured luminosity
• maximum
  maximum of measured luminosity
• state
  Default: Defined, Ok, Saturated, I2C Error

Attributes

• IODev
  Set the name of an IODev module like RPII2C
  Default: undefined
  
• poll_interval
  Set the polling interval in minutes to query the sensor for new measured values. By changing this attribute a new illumination measurement will be triggered.
  valid values: 0.1, 0.2, 0.5, 1, 2, 5, 10, 20, 30, 60
  
• percentdelta
  If set a luminosity reading is only generated if the difference between the current luminosity value and the last reading is at least percentdelta percents.
  
• correction
  Linear correction factor to be applied to the sensor value. Compared with a commercial light meter it seems that the values for my BH1750 are about 25% to low in day light (correction 1.25). The TLS2561 compares much better with the light meter but has the disadvantage that it saturates at about 40k lux.
  The correction factor can also be used if your sensor is behind an opal glass.
  valid range: 0.5 to 2.0
  

I2C_BME280

[EN DE]

Provides an interface to the digital pressure/humidity sensor BME280 The I2C messages are send through an I2C interface module like RPII2C, FRM or NetzerI2C so this device must be defined first.
attribute IODev must be set
Define
define BME280 I2C_BME280 [<I2C Address>]

<I2C Address> may be an 2 digit hexadecimal value (0xnn) or an decimal value
Without defined <I2C Address> 0x76 (hexadecimal) = 118 (decimal) will be used.
An I2C address are 7 MSB, the LSB is the R/W bit.

Examples:

      define BME280 I2C_BME280 0x77
      attr BME280 poll_interval 5
    

Set
set BME280 <readValues>

Reads current temperature, humidity and pressure values from the sensor.
Normaly this execute automaticly at each poll intervall. You can execute this manually if you want query the current values.


Attributes
• oversampling_t,oversampling_h,oversampling_p
  Controls the oversampling settings of the temperature,humidity or pressure measurement in the sensor.
  Default: 1, valid values: 0, 1, 2, 3, 4, 5
  0 switches the respective measurement off
  1 to 5 complies to oversampling value 2^value/2
  
  
• poll_interval
  Set the polling interval in minutes to query the sensor for new measured values.
  Default: 5, valid values: any whole number
  
  
• roundTemperatureDecimal,roundHumidityDecimal,roundPressureDecimal
  Round temperature, humidity or pressure values to given decimal places.
  Default: 1, valid values: 0, 1, 2
  
  
• altitude
  if set, this altitude is used for calculating the pressure related to sea level (metres above mean sea level) MAMSL
  
  Note: this is a global attributes, e.g
  attr global altitude 220
• IODev
• do_not_notify
• showtime

I2C_BMP180

[EN DE]

With this module you can read values from the digital pressure sensors BMP180 and BMP085 via the i2c bus on Raspberry Pi.

There are two possibilities connecting to I2C bus:


• via RPII2C module
  The I2C messages are send through an I2C interface module like RPII2C, FRM or NetzerI2C so this device must be defined first.
  attribute IODev must be set
  
  
• via HiPi library
  Add these two lines to your /etc/modules file to load the I2C relevant kernel modules automaticly during booting your Raspberry Pi.
  

  i2c-bcm2708 
          i2c-dev

  Install HiPi perl modules:
  

  wget http://raspberry.znix.com/hipifiles/hipi-install
          perl hipi-install

  To change the permissions of the I2C device create file:
  

  	/etc/udev/rules.d/98_i2c.rules

  with this content:
  

  SUBSYSTEM=="i2c-dev", MODE="0666"

  Reboot
  
  To use the sensor on the second I2C bus at P5 connector (only for version 2 of Raspberry Pi) you must add the bold line of following code to your FHEM start script:

  	case "$1" in
          'start')
          sudo hipi-i2c e 0 1
          ...

Define

define BMP180 I2C_BMP180 [<I2C device>]

<I2C device> must not be used if you connect via RPII2C module. For HiPi it's mandatory.

Examples:

      define BMP180 I2C_BMP180 /dev/i2c-0
      attr BMP180 oversampling_settings 3
      attr BMP180 poll_interval 5
    

      define BMP180 I2C_BMP180
      attr BMP180 IODev RPiI2CMod
      attr BMP180 oversampling_settings 3
      attr BMP180 poll_interval 5
    

Set
set BMP180 <readValues>

Reads the current temperature and pressure values from sensor.
Normaly this execute automaticly at each poll intervall. You can execute this manually if you want query the current values.


Get
N/A

Attributes
• oversampling_settings
  Controls the oversampling setting of the pressure measurement in the sensor.
  Default: 3, valid values: 0, 1, 2, 3
  
  
• poll_interval
  Set the polling interval in minutes to query the sensor for new measured values.
  Default: 5, valid values: 1, 2, 5, 10, 20, 30
  
  
• roundTemperatureDecimal
  Round temperature values to given decimal places.
  Default: 1, valid values: 0, 1, 2
  
  
• roundPressureDecimal
  Round temperature values to given decimal places.
  Default: 1, valid values: 0, 1, 2
  
  
• altitude
  if set, this altitude is used for calculating the pressure related to sea level (metres above mean sea level) MAMSL
  
  Note: this is a global attributes, e.g
  
  attr global altitude 220

Notes
• I2C bus timing
  For all sensor operations an I2C interface with blocking IO is assumed (e.g. RPII2C). If you use an I2C interface with non-blocking IO (e.g. FRM over ethernet) operation errors may occur, especially if setting the attribute oversampling_settings to a value higher than 1. This may be compensated depending on I2C interface used. For Firmata try setting the attribute i2c-config in the FRM module to a value of about 30000 microseconds.
  
  

I2C_DS1307

[EN DE]

reads a DS1307 real-time clock chip via I2C. Requires a defined I2C-device to work.
Define
define <name> I2C_DS1307 <i2c-address>
Specifies the I2C_DS1307 device.

• i2c-address is the (device-specific) address of the ic on the i2c-bus

Set

• set <name> datetime; set DS1307 time. Format is JJJJ-MM-DD HH:MM:SSdisplayed>
  
• set <name> now
  
Get

N/A


Attributes

• poll_interval <seconds>
• IODev
  Specify which I2C to use. (Optional, only required if there is more than one I2C-device defined.)
• eventMap
  
• readingFnAttributes
  

I2C_EEPROM

[EN DE]

Provides an interface to an I2C EEPROM.
The I2C messages are send through an I2C interface module like RPII2C, FRM or NetzerI2C so this device must be defined first.
attribute IODev must be set

Define
define <name> I2C_EEPROM <I2C Address>
<I2C Address> may be an 2 digit hexadecimal value (0xnn) or an decimal value
For example 0x40 (hexadecimal) = 64 (decimal). An I2C address are 7 MSB, the LSB is the R/W bit.

Set
set <name> <byte address> <value>

where <byte address> is a number (0..device specific) and <value> is a number (0..255)
both numbers can be written in decimal or hexadecimal notation.

Example:
set eeprom1 0x02 0xAA
set eeprom1 2 170



Get
get <name>

refreshes all readings


get <name> <byte address> [Bit<bitnumber(0..7)>]

returnes actual reading of stated <byte address> or a single bit of <byte address>
Values are readout from readings, NOT from device!

Attributes
• poll_interval
  Set the polling interval in minutes to query the EEPROM content
  Default: -, valid values: decimal number
  
  
• EEPROM_size
  Sets the storage size of the EEPROM
  Default: 128, valid values: 128 (128bit), 2k (2048bit)
  
  
• IODev
• ignore
• do_not_notify
• showtime

I2C_EMC1001

[EN DE]

(en | de)

Provides an interface to the digital temperature sensor EMC1001 The I2C messages are send through an I2C interface module like RPII2C, FRM or NetzerI2C so this device must be defined first.
attribute IODev must be set
Define
define EMC1001 I2C_EMC1001 [<I2C Address>]

without defined <I2C Address> 0x48 will be used as address

Examples:

      define EMC1001 I2C_EMC1001 0x48
      attr EMC1001 poll_interval 5
			attr roundTemperatureDecimal 2
    

Set
set EMC1001 <readValues>

Reads current temperature values from the sensor.
Normaly this execute automaticly at each poll intervall. You can execute this manually if you want query the current values.


Attributes
• poll_interval
  Set the polling interval in minutes to query the sensor for new measured values.
  Default: 5, valid values: any whole number
  
  
• roundTemperatureDecimal
  Round temperature values to given decimal places.
  Default: 1, valid values: 0, 1, 2
  
  
• IODev
• do_not_notify
• showtime

I2C_HDC1008

[EN DE]

Provides an interface to the I2C_HDC1008 I2C Humidity sensor from Texas Instruments. The I2C messages are send through an I2C interface module like RPII2C, FRM or NetzerI2C so this device must be defined first.
attribute IODev must be set

Define
define <name> I2C_HDC1008 [<I2C Address>]
where <I2C Address> is an 2 digit hexadecimal value

Set
set <name> Update
Reads the current temperature and humidity values from sensor.

set <name> Reset
Resets the sensor set <name> Heater {on|off}
turns the sensor heater on or off
Attributes
• interval
  Set the polling interval in minutes to query data from sensor
  Default: 5, valid values: 1,2,5,10,20,30
  
  
• Resolution_Temperature
  resolution for measurement temperature.
  Standard: 14Bit, valid values: 11Bit, 14Bit
  
  
• Resolution_Humidity
  resolution for measurement humidity.
  Standard: 14Bit, valid values: 8Bit, 11Bit, 14Bit
  
  
• roundHumidityDecimal
  Number of decimal places for humidity value
  Default: 1, valid values: 0 1 2,...
  
  
• roundTemperatureDecimal
  Number of decimal places for temperature value
  Default: 1, valid values: 0,1,2,...
  
  
• IODev

I2C_K30

[EN DE]

(en | de)

Provides an interface to the K30 CO2 sensor from SenseAir. This module expects the sensor to be connected via I2C (for a quick summary, see Application Note 142 "K-30/K-33 I2C on Raspberry Pi" from co2meters.com).
On my Raspberry Pi 2, I needed to reduce I2C frequency to 90 kHz, otherwise most read/write cycles failed (add "options i2c_bcm2708 baudrate=90000", e.g. to /etc/modprobe.d/i2c-options.conf). I still see sporadic errors (about 5% of all readings fail), but this seems to be expected - the datasheet warns that the uC on the sensor will only correctly handle I2C when it's not busy doing CO2 measurement. The I2C messages are sent through an I2C interface module like RPII2C, FRM or NetzerI2C so this device must be defined first.
attribute IODev must be set

Define
define <name> I2C_K30 [<I2C Address>]
where <I2C Address> is the configured I2C address of the sensor (default: 104, i.e. 0x68)

Set
set <name> readValues
Reads the current CO2 value from sensor.


Attributes
• poll_interval
  Set the polling interval in minutes to query data from sensor
  Default: 5, valid values: 1,2,5,10,20,30
  
  
• IODev
• do_not_notify
• showtime

I2C_LCD

[EN DE]

drives LiquidCrystal Displays (LCD) that are connected to Firmata (via I2C). Supported are Displays that use a PCF8574T as I2C Bridge (as found on eBay when searching for 'LCD' and 'I2C'). Tested is the 1602 type (16 characters, 2 Lines), the 2004 type (and other cheap chinise-made I2C-LCDs for Arduino) ship with the same library, so they should work as well. See http://arduino.cc/en/Tutorial/LiquidCrystal for details about how to hook up the LCD to the arduino. Requires a defined I2C-device to work.
this I2C-device has to be configures for i2c by setting attr 'i2c-config' on the I2C-device
Define
define <name> I2C_LCD <size-x> <size-y> <i2c-address>
Specifies the I2C_LCD device.

• size-x is the number of characters per line
• size-y is the numbers of rows.
• i2c-address is the (device-specific) address of the ic on the i2c-bus

Set

• set <name> text <text to be displayed>
  
• set <name> home
  
• set <name> clear
  
• set <name> display on|off
  
• set <name> cursor <...>
  
• set <name> scroll left|right
  
• set <name> backlight on|off
  
• set <name> reset
  
• set <name> writeXY x-pos,y-pos,len[,l] <text to be displayed>
  
Get

N/A


Attributes

• backLight <on|off>
• autoClear <on|off>
• autoBreak <on|off>
• restoreOnStartup <on|off>
• restoreOnReconnect <on|off>
• replaceRegex ä=ae,cd+=ef,g=\x{DF}
  specify find=replace regex pattern eg for non-printable characters. \x{DF} will become char 223, which is º on my lcd.
• customChar<0-7>
  up to 8 5x8px custom chars, see http://www.quinapalus.com/hd44780udg.html for a generator, use \x{00} to \x{07} to display
• IODev
  Specify which I2C to use. (Optional, only required if there is more than one I2C-device defined.)
• eventMap
  
• readingFnAttributes
  

I2C_LM75A

[EN DE]

(en | de)

Provides an interface to the LM75A I2C Temperature sensor.. The I2C messages are send through an I2C interface module like RPII2C, FRM or NetzerI2C so this device must be defined first.
attribute IODev must be set

Define
define <name> I2C_LM75A [<I2C Address>]
<I2C Address> may be an 2 digit hexadecimal value (0xnn) or an decimal value
Without defined <I2C Address> 0x48 (hexadecimal) = 72 (decimal) will be used.. An I2C address are 7 MSB, the LSB is the R/W bit.

Set
set <name> readValues
Reads the current temperature values from sensor.


Attributes
• poll_interval
  Set the polling interval in minutes to query data from sensor
  Default: 5, valid values: 1,2,5,10,20,30
  
  
• roundTemperatureDecimal
  Number of decimal places for temperature value
  Default: 1, valid values: 0 1 2
  
  
• IODev
• do_not_notify
• showtime

I2C_MCP23008

[EN DE]

Provides an interface to the MCP23008 16 channel port extender IC. On Raspberry Pi the Interrupt Pin's can be connected to an GPIO and RPI_GPIO can be used to get the port values if an interrupt occurs.
The I2C messages are send through an I2C interface module like RPII2C, FRM or NetzerI2C so this device must be defined first.
attribute IODev must be set

Define
define <name> I2C_MCP23008 <I2C Address>
<I2C Address> may be an 2 digit hexadecimal value (0xnn) or an decimal value
For example 0x40 (hexadecimal) = 64 (decimal). An I2C address are 7 MSB, the LSB is the R/W bit.

Set
set <name> <port[,port[...]]> <value>

where <port> is one of PortA0 to PortA7 and <value> is one of:

off
on


Example:
set mod1 PortA4 on
set mod1 PortA4,PortA6 off
set mod1 PortA4,A6 on



Get
get <name>

refreshes all readings

Attributes
• poll_interval
  Set the polling interval in minutes to query the GPIO's level
  Default: -, valid values: decimal number
  
  
• OutputPorts
  Comma separated list of ports that are used as Output
  Ports not in this list can't be written
  Default: no, valid values: A0-A7
  
  
• OnStartup
  Comma separated list of output ports and their desired state after start
  Without this atribut all output ports will set to last state
  Default: -, valid values: <port>=on|off|last where <port> = A0-A7
  
  
• Pullup
  Comma separated list of input ports which switch on their internal 100k pullup
  Default: -, valid values: A0-A7
  
  
• Interrupt
  Comma separated list of input ports which will trigger the IntA/B pin
  Default: -, valid values: A0-A7
  
  
• invert_input
  Comma separated list of input ports which use inverted logic
  Default: -, valid values: A0-A7
  
  
• InterruptOut
  Configuration options for INT output pin
  Values:
  
  • active-low (INT output is active low)
  • active-high (INT output is active high)
  • open-drain (INTA output is open drain)
  
  
• IODev
• ignore
• do_not_notify
• showtime

I2C_MCP23017

[EN DE]

Provides an interface to the MCP23017 16 channel port extender IC. On Raspberry Pi the Interrupt Pin's can be connected to an GPIO and RPI_GPIO can be used to get the port values if an interrupt occurs.
The I2C messages are send through an I2C interface module like RPII2C, FRM or NetzerI2C so this device must be defined first.
attribute IODev must be set

Define
define <name> I2C_MCP23017 <I2C Address>
<I2C Address> may be an 2 digit hexadecimal value (0xnn) or an decimal value
For example 0x40 (hexadecimal) = 64 (decimal). An I2C address are 7 MSB, the LSB is the R/W bit.

Set
set <name> <port[,port[...]]> <value>

where <port> is one of PortA0 to PortA7 / PortB0 to PortB7 and <value> is one of:

off
on


Example:
set mod1 PortA4 on
set mod1 PortA4,PortB6 off
set mod1 PortA4,B6 on



Get
get <name>

refreshes all readings

Attributes
• poll_interval
  Set the polling interval in minutes to query the GPIO's level
  Default: -, valid values: decimal number
  
  
• OutputPorts
  Comma separated list of ports that are used as Output
  Ports not in this list can't be written
  Default: no, valid values: A0-A7, B0-B7
  
  
• OnStartup
  Comma separated list of output ports and their desired state after start
  Without this atribut all output ports will set to last state
  Default: -, valid values: <port>=on|off|last where <port> = A0-A7, B0-B7
  
  
• Pullup
  Comma separated list of input ports which switch on their internal 100k pullup
  Default: -, valid values: A0-A7, B0-B7
  
  
• Interrupt
  Comma separated list of input ports which will trigger the IntA/B pin
  Default: -, valid values: A0-A7, B0-B7
  
  
• invert_input
  Comma separated list of input ports which use inverted logic
  Default: -, valid values: A0-A7, B0-B7
  
  
• InterruptOut
  Configuration options for INTA/INTB output pins
  Values:
  
  • separate_active-low (INTA/INTB outputs are separate for both ports and active low)
  • separate_active-high (INTA/INTB outputs are separate for both ports and active high)
  • separate_open-drain (INTA/INTB outputs are separate for both ports and open drain)
  • connected_active-low (INTA/INTB outputs are internally connected and active low)
  • connected_active-high (INTA/INTB outputs are internally connected and active high)
  • connected_open-drain (INTA/INTB outputs are internally connected and open drain)
  
  
• IODev
• ignore
• do_not_notify
• showtime

I2C_MCP342x

[EN DE]

Provides an interface to the MCP3422/3/4 A/D converter. The I2C messages are send through an I2C interface module like RPII2C, FRM or NetzerI2C so this device must be defined first.
attribute IODev must be set

Define
define <name> I2C_MCP342x [[<I2C Address>] <n channels>]
<I2C Address> may be an 2 digit hexadecimal value (0xnn) or an decimal value
For example 0x40 (hexadecimal) = 64 (decimal). An I2C address are 7 MSB, the LSB is the R/W bit.
<n channels> is the number of A/D channels


Get
get <name> [[[<channel>] <resolution> ] <gain>]
Returns the level on specific <channel>. <resolution> and <gain> will override attibutes for actual operation. Without attributes only the readings will be refreshed.


Attributes
• poll_interval
  Set the polling interval in minutes to query data from sensor
  Default: 5, valid values: 1,2,5,10,20,30
  
  
Following attributes are separate for all channels.


• ch1resolution
  resolution settings
  the bigger the resolution the longer the conversion time.
  Default: 12, valid values: 12,14,16,18
  
  
• ch1gain
  gain setting
  Important: the gain setting will reduce the measurement range an may produce an overflow. In this case "overflow" will be added to reading
  Default: 1, valid values: 1,2,4,8
  
  
• ch1factor
  correction factor (will be mutiplied to channel value)
  Default: 1, valid values: number
  
  
• ch1roundDecimal
  Number of decimal places for value
  Default: 3, valid values: 0,1,2,3
  
  
• IODev
• do_not_notify
• showtime

I2C_MMA845X

[EN DE]

This modules is a driver for using the Freescale/NXP MMA8451/MMA84512/MMA84513 accelerometer with I2C bus interface (see the NXP product description for full specifications). Note that the Freescale/NXP MMA8450 accelerometer, though similar, has a different register set and cannot be addressed by this module.

The I2C messages are sent through an interface module like RPII2C or FRM, so this device must be defined first and assigned as IODev attribute.

This module supports the following features:
• read current acceleration (x, y, z)
• calibrate acceleration offsets
• orientation detection
• motion detection (at least one axis above threshold) or freefall detection (all axes below threshold)
• jolt detection (at least one axis change above threshold)
• single and/or double pulse (tap) detection
• detection event latching
• hardware interrupt signalling of detection events

The accelerometer is configured for an output data rate of 200 Hz in normal oversampling mode with the low noise filter enabled providing a full scale range of +/-4 g as default. This output data rate can be changed if required.

The detection events (orientation, motion/freefall, jolt, pulse) can be signaled by one or two hardware outputs that can be used for interrupt driven operations without need for continuous polling. If the event latch is enabled, the events and the interrupt signals will remain set until the event source register is read, providing additional event details (e.g. axis, direction). With orientation detection the event latch is always enabled.

The acceleration measurement output can optionally be passed through a high-pass filter with a selectable cutoff frequency effectively eliminating the gravity offset of 1g to provide change detection instead of orientation detection. The motion/freefall detection will always bypass the high-pass filter while the jolt and pulse detections will always use the high-pass filter with default settings. When using motion detection you would typically not enable the gravity axis or set a threshold higher than 1 g.

While the orientation detection works well with the default settings the other detection modes typically require fine tuning of their parameters. To understand the detection modes and their parameters in detail please refer to the Freescale annotations AN4068 (orientation), AN4070 (freefall/motion), AN4071 (jolt) and AN4072 (pulse).

Several of the parameters represent a frequency [Hz], a threshold [g]/[°] or a duration [ms]. Their absolute values often depend on a combination of register settings requiring lookup tables. This module uses the raw binary values for these attributes making fine tuning easier because value granularity is always 1. If you need to translate between binary values and absolute values please refer to the device documentation.

Define
define <device name> I2C_MMA845X <I2C address>

<I2C address> may be 0x1C or 0x1D

Example:

             define MMA8452 I2C_MMA845X 0x1D
             attr MMA8452 IODev I2CModule
             attr MMA8452 pollInterval 5
        

Notes:


• The I2C bus connection must be kept active between write and read with the MMA8451/MMA84512/MMA84513 devices (repeated start alias combined write/read). This communication mode is not the default on most platforms:
  
  Raspberry:
  • Change parameter 'combined' of BCM2708 driver from N to Y.
    Temporary: sudo su - echo -n 1 > /sys/module/i2c_bcm2708/parameters/combined exit.
    Permanent: add echo -n 1 > /sys/module/i2c_bcm2708/parameters/combined to script /etc/init.d/rc.local.
  • Set attribute useHWLib of your RPII2C device to SMBus (RPII2C's ioctl mode currently does not support combined write/read mode).
  
  Firmata:
  • Make sure to call Wire.endTransmission(false). Currently requires manually changing the ino file (Standard Firmata) or I2CFirmata.h (Configurable Firmata).

Set

• set <device name> calibrate
  Calibrate the acceleration offset based on the next sample assuming 1g gravity on any one axis.
  Prerequisites: Align one axis with gravity and keep device stationary during calibration.

Get

• get <device name> update
  Request an update of the acceleration readings.


• get <device name> orientation
  Request an update of the orientation reading.
• get <device name> eventSources
  Request an update of the event source readings.


• get <device name> update
  Perform manual polling, e.g. when attribute pollInterval is set to zero. At least one of pollAccelerations, pollOrientation or pollEventSources should be enabled.

Attributes
attr <device name> <attribute name> <value>

Attributes:
• IODev <IODev device name>
  I2C IODev device name, no default, required
• pollInterval <seconds>
  period for updating acceleration and event source readings, default 10 s
  fractional seconds are supported, use 0 to disable polling
• pollAccelerations 0|1
  include reading of accelerations when polling, default 1
  
• pollOrientation 0|1
  include reading of orientation when polling, default 1
  
• pollEventSources 0|1
  include reading of event sources when polling, default 1
  
• disable 0|1
  disables device (I2C operations), default 0
• outputDataRate <frequency>
  device internal acceleration value output rate, may be one of 1.56, 6.25, 12.5, 50, 100, 200, 400 or 800 Hz, default 200 Hz
  affects all timing parameters, is independent of pollInterval
• highPass <function>[,<function>]
  select which function should use the high-pass filter, may be any of outputData, jolt or pulse, default jolt,pulse
  activating the high-pass filter will remove the 1g offset in the gravity direction
• highPassCutoffFrequency 0 ... 3
  set the high-pass filter cutoff frequency, changes with on output data rate, default 0
  0 is a higher cutoff frequency (up to 16 Hz) and 3 is a lower cutoff frequency (down to 0.25 Hz), see device manual for details
• orientation...
  orientation detection parameters, see device manual for details
• motion...
  motion/freefall detection parameters, see device manual for details
• jolt...
  jolt detection parameters, see device manual for details
• pulse...
  pulse (tap) detection parameters, see device manual for details
• ...EventLatch 0|1
  if enabled an event (and the hardware output) will stay latched until the event source register is read, default 0
  the corresponding event source reading will provide additional information about the event
• ...Interrupt 0|1|2
  an event will also raise one of two hardware outputs, default 0
  use 0 to disable linking an event with an hardware outputs

Readings
• out...
  acceleration for x, y and z axes [g]
  the number of decimal places is limited to 3 to remove a significant amount of noise
• off...
  acceleration offset for x, y and z axes from last calibration [g]
  to adjust offsets manually at runtime, change offset readings and toggle disable attribute
• orientation
  current orientation, orientation detection must be enabled, the reading is only updated on change
  P=portrait + U=up/D=down or L=landscape + L=left/R=right, B=back or F=front, X=z-lockout
• ...Event
  source of last event, event and event latch must be enabled, the reading is only updated on change
  motion/jolt/pulse: X, Y or Z for the affected axis preceded by a sign for the direction of the the event
  pulse: additional pulse type indicator postfix S=single or D=double

I2C_PCA9532

[EN DE]

Provides an interface to the PCA9532 I2C 16 channel PWM IC. The PCA9532 has 2 independent PWM stages and every channel can be attached to on of these stages or directly turned on or off. The I2C messages are send through an I2C interface module like RPII2C, FRM or NetzerI2C so this device must be defined first.
attribute IODev must be set

Define
define <name> I2C_PCA9532 <I2C Address>
<I2C Address> may be an 2 digit hexadecimal value (0xnn) or an decimal value
For example 0x40 (hexadecimal) = 64 (decimal). An I2C address are 7 MSB, the LSB is the R/W bit.

Set
set <name> <port> <value>


• if <port> is one of Port0 to Port15, then <value> will be one of:
  
  off
on
PWM0 (output is switched with PWM0 frequency and duty cycle)
PWM1 (output is switched with PWM1 frequency and duty cycle)

• if <port> is PWM0 or PWM1, then <value> is an value between 0 and 255 and stands for the duty cycle of the PWM stage.

Examples:
set mod1 Port4 PWM1
set mod1 PWM1 128



Get
get <name>

refreshes all readings

Attributes
• poll_interval
  Set the polling interval in minutes to query the GPIO's level
  Default: -, valid values: decimal number
  
  
• OutputPorts
  Comma separated list of Portnumers that are used as Outputs
  Only ports in this list can be written
  Default: no, valid values: 0 1 2 .. 15
  
  
• OnStartup
  Comma separated list of output ports/PWM registers and their desired state after start
  Without this atribut all output ports will set to last state
  Default: -, valid values: <port>=on|off|PWM0|PWM1|last or PWM0|PWM1=0..255|last where <port> = 0 - 15
  
  
• T0
  Sets PWM0 to another Frequency. The Formula is: Fx = 152/(Tx + 1) The corresponding frequency value is shown under internals.
  Default: 0 (152Hz), valid values: 0-255
  
  
• T1
  Sets PWM1 to another Frequency. The Formula is: Fx = 152/(Tx + 1) The corresponding frequency value is shown under internals.
  Default: 0 (152Hz), valid values: 0-255
  
  
• IODev
• ignore
• do_not_notify
• showtime

I2C_PCA9685

[EN DE]

Provides an interface to the PCA9685 I2C 16 channel PWM IC. The I2C messages are send through an I2C interface module like RPII2C, FRM or NetzerI2C so this device must be defined first.
attribute IODev must be set

Define
define <name> I2C_PCA9685 <I2C Address> [<I2C Buffer Size>]
<I2C Address> may be an 2 digit hexadecimal value (0xnn) or an decimal value
For example 0x40 (hexadecimal) = 64 (decimal). An I2C address are 7 MSB, the LSB is the R/W bit.
<I2C Buffer Size> sets the maximum size of the I2C-Packet. Without this option the packet size is 30 Bytes (32 incl. Address and Register number). For RPII2C this option has no influence, cause it can deal with arbitrary packet sizes.

Set
set <name> <port> <dimvalue> [<delay>]


• where <port> is one of Port0 to Port15
  and <dimvalue> one of
  
  off
on
0..4095

  <delay> defines the switch on time inside the PWM counting loop. It does not have an influence to the duty cycle. Default value is 0 and, possible values are 0..4095
  


• It is also possible to change more than one port at the same time. Just separate them by comma. If only the last of the comma separated ports has dimvalue (and delay), all ports will set to the same values. Sequently ports will set at once (useful for multi color LED's).
  Also P instead of Port is Possible.


Examples:
set mod1 Port04 543
set mod1 Port4 434 765
set mod1 Port1, Port14 434 765
set mod1 Port1 on, P14 434 765



Get
get <name>

refreshes all readings

Attributes
• SUBADR1,SUBADR2,SUBADR3,ALLCALLADR
  Alternative slave addresses, if you want to control more than one PCA9685 with one define Respective flag in modereg1 must be set as well
  Default: SUBADR1=113,SUBADR2=114,SUBADR3=116,ALLCALLADR=112, valid values: valid I2C Address
  
  
• OnStartup
  Comma separated list of output ports/PWM registers and their desired state after start
  Without this atribut all output ports will set to last state
  Default: -, valid values: <port>=on|off|0..4095|last where <port> = 0 - 15
  
  
• prescale
  Sets PWM Frequency. The Formula is: Fx = 25MHz/(4096 * (prescale + 1)). The corresponding frequency value is shown under internals. If provided, attribute extClock will be used for frequency calculation. Otherwise 25MHz
  Default: 30 (200Hz for 25MHz clock), valid values: 0-255
  
  
• modereg1
  Comma separated list of:
  • EXTCLK
    If set the an external connected clock will be used instead of the internal 25MHz oscillator. Use the attribute extClock to provide the external oscillater value.
  • SUBADR1
    If set the PCA9685 responds to I2C-bus SUBADR 1.
  • SUBADR2
    If set the PCA9685 responds to I2C-bus SUBADR 2.
  • SUBADR3
    If set the PCA9685 responds to I2C-bus SUBADR 3.
  • ALLCALLADR
    If set the PCA9685 responds to I2C-bus ALLCALLADR address.
• modereg2
  Comma separated list of:
  • INVRT
    If set the Output logic state is inverted.
    
  • OCH
    If set the outputs changes on ACK (after every byte sent).
    Otherwise the output changes on STOP command (bus write action finished)
    
  • OUTDRV
    If set the outputs are configured with a totem pole structure.
    Otherwise the outputs are configured with open-drain.
    
  Behaviour when OE = 1 (if OE = 0 the output will act according OUTDRV configuration):
  • OUTNE0
    If set:
    LEDn = 1 when OUTDRV = 1
    LEDn = high-impedance when OUTDRV = 0
    If not set: LEDn = 0.
    
  • OUTNE1
    LEDn = high-impedance.
    OUTNE1 overrides OUTNE0
    
    
• IODev
• ignore
• do_not_notify
• showtime

I2C_PCF8574

[EN DE]

Provides an interface to the PCA9532 8 channel port extender IC. On Raspberry Pi the Interrupt Pin can be connected to an GPIO and RPI_GPIO can be used to get the port values if an interrupt occurs.
The I2C messages are send through an I2C interface module like RPII2C, FRM or NetzerI2C so this device must be defined first.
attribute IODev must be set

Define
define <name> I2C_PCF8574 <I2C Address>
<I2C Address> may be an 2 digit hexadecimal value (0xnn) or an decimal value
For example 0x40 (hexadecimal) = 64 (decimal). An I2C address are 7 MSB, the LSB is the R/W bit.

Set
set <name> <port[,port[...]]> <value>


• <port> is one of Port0 to Port7 and <value> is one of:
  
  off
on


Example:
set mod1 Port4 on
set mod1 Port4,Port6 off
set mod1 Port4,6 on



Get
get <name>

refreshes all readings

Attributes
• poll_interval
  Set the polling interval in minutes to query the GPIO's level
  Default: -, valid values: decimal number
  
  
• InputPorts
  Comma separated list of Portnumers that are used as Inputs
  Ports in this list can't be written
  Default: -, valid values: 0 - 7
  
  
• InvrtPorts
  Comma separated list of Portnumers that will be inverted
  Default: -, valid values: 0 - 7
  
  
• OnStartup
  Comma separated list of output ports and their desired state after start
  Without this atribut all output ports will set to last state
  Default: -, valid values: <port>=on|off|last where <port> = 0 - 7
  
  
• IODev
• ignore
• do_not_notify
• showtime

I2C_SHT21

[EN DE]

Provides an interface to the SHT21 I2C Humidity sensor from Sensirion. The I2C messages are send through an I2C interface module like RPII2C, FRM or NetzerI2C so this device must be defined first.
attribute IODev must be set

Define
define <name> I2C_SHT21 [<I2C Address>]
<I2C Address> may be an 2 digit hexadecimal value (0xnn) or an decimal value
For example 0x40 (hexadecimal) = 64 (decimal). An I2C address are 7 MSB, the LSB is the R/W bit.

Set
set <name> readValues
Reads the current temperature and humidity values from sensor.


Attributes
• poll_interval
  Set the polling interval in minutes to query data from sensor
  Default: 5, valid values: 1,2,5,10,20,30
  
  
• roundHumidityDecimal
  Number of decimal places for humidity value
  Default: 1, valid values: 0 1 2
  
  
• roundTemperatureDecimal
  Number of decimal places for temperature value
  Default: 1, valid values: 0 1 2
  
  
• IODev
• do_not_notify
• showtime

I2C_SHT3x

[EN DE]

(en | de)

Provides an interface to the SHT30/SHT31 I2C Humidity sensor from Sensirion. The I2C messages are sent through an I2C interface module like RPII2C, FRM or NetzerI2C so this device must be defined first.
attribute IODev must be set

Define
define <name> I2C_SHT3x [<I2C Address>]
where <I2C Address> is an 2 digit hexadecimal value:
ADDR (pin 2) connected to VSS (supply voltage): 0x44 (default, if <I2C Address> is not set)
ADDR (pin 2) connected to VDD (ground): 0x45
For compatible sensors also other values than 0x44 or 0x45 can be set.


Set
set <name> readValues
Reads the current temperature and humidity values from sensor.


Attributes
• poll_interval
  Set the polling interval in minutes to query data from sensor
  Default: 5, valid values: 1,2,5,10,20,30
  
  
• roundHumidityDecimal, roundTemperatureDecimal
  Number of decimal places for humidity or temperature value
  Default: 1, valid values: 0 1 2
  
  
• IODev
• do_not_notify
• showtime

I2C_TSL2561

[EN DE]

With this module you can read values from the ambient light sensor TSL2561 via the i2c bus on Raspberry Pi.
The luminosity value returned is a good human eye reponse approximation of an illumination measurement in the range of 0.1 to 40000+ lux (but not a replacement for a precision measurement, relation between measured value and true value may vary by 40%).

There are two possibilities connecting to I2C bus:


• via IODev module
  The I2C messages are send through an I2C interface module like RPII2C, FRM or NetzerI2C so this device must be defined first.
  attribute IODev must be set
  
  
• via HiPi library
  Add these two lines to your /etc/modules file to load the I2C relevant kernel modules automaticly during booting your Raspberry Pi.
  

   
              i2c-bcm2708
              i2c-dev
              

  Install HiPi perl modules:
  

   wget http://raspberry.znix.com/hipifiles/hipi-install perl hipi-install

  To change the permissions of the I2C device create file:
  

   /etc/udev/rules.d/98_i2c.rules

  with this content:
  

   SUBSYSTEM=="i2c-dev", MODE="0666"

  Reboot
  
  To use the sensor on the second I2C bus at P5 connector (only for version 2 of Raspberry Pi) you must add the bold line of following code to your FHEM start script:

              case "$1" in
              'start')
                  sudo hipi-i2c e 0 1
              ...
              

Define

define TSL2561 I2C_TSL2561 [<I2C device>] <I2C address>

<I2C device> mandatory for HiPi, must be omitted if you connect via IODev
<I2C address> may be 0x29, 0x39 or 0x49 (and 'AUTO' when using IODev to search for device at startup and after an I2C error)

Examples:

        define TSL2561 I2C_TSL2561 /dev/i2c-0 0x39
        attr TSL2561 poll_interval 5
        

        define TSL2561 I2C_TSL2561 0x39
        attr TSL2561 IODev I2CModule
        attr TSL2561 poll_interval 5
        

        define TSL2561 I2C_TSL2561 AUTO
        attr TSL2561 IODev I2CModule
        attr TSL2561 poll_interval 5
        

Set
get <name> update

Force immediate illumination measurement and restart a new poll_interval.

Note that the new readings are not yet available after set returns because the measurement is performed asynchronously. Depending on the attributes integration time, autoGain and autoIntegrationTime this may require more than one second to complete.

Readings

• luminosity
  Good human eye reponse approximation of an illumination measurement in the range of 0.1 to 40000+ lux.
  Rounded to 3 significant digits or one fractional digit.
• broadband
  Broadband spectrum sensor sample.
  Enable attribute normalizeRawValues for continuous readings independed of actual gain and integration time settings.
• ir
  Infrared spectrum sensor sample.
  Enable attribute normalizeRawValues for continuous readings independed of actual gain and integration time settings.
• gain
  sensor gain used for current luminosity measurement (1 or 16)
  
• integrationTime
  integration time in seconds used for current luminosity measurement
  
• state
  Default: Initialized, valid values: Undefined, Defined, Initialized, Saturated, Disabled, I2C Error

Attributes

• IODev
  Set the name of an IODev module. If undefined the perl modules HiPi::Device::I2C are required.
  Default: undefined
  
• poll_interval
  Set the polling interval in minutes to query the sensor for new measured values. By changing this attribute a new illumination measurement will be triggered.
  Default: 5, valid values: 1, 2, 5, 10, 20, 30
  
• gain
  Set gain factor. Attribute will be ignored if autoGain is enabled.
  Default: 1, valid values: 1, 16
• integrationTime
  Set time in ms the sensor takes to measure the light. Attribute will be ignored if autoIntegrationTime is enabled.
  Default: 13, valid values: 13, 101, 402
  See this tutorial for more details.
• autoGain
  Enable auto gain. If set to 1, the gain parameter is adjusted automatically depending on light conditions.
  Default: 1, valid values: 0, 1
  
• autoIntegrationTime
  Enable auto integration time. If set to 1, the integration time parameter is adjusted automatically depending on light conditions.
  Default: 0, valid values: 0, 1
  
• normalizeRawValues
  Scale the sensor raw values broadband and ir depending on actual gain and integrationTime to the equivalent of the settings for maximum sensitivity (gain=16 and integrationTime=403ms). This feature may be useful when autoGain or autoIntegrationTime is enabled to provide continuous values instead of jumping values when gain or integration time changes.
  Default: 0, valid values: 0, 1
  
• floatArithmetics
  Enable float arithmetics.
  If set to 0, the luminosity is calculated using int arithmetics (for very low powered platforms).
  If set to 1, the luminosity is calculated using float arithmetics, yielding some additional precision. Default: 1, valid values: 0, 1
  
• disable
  Disable I2C bus access.
  Default: 0, valid values: 0, 1

Notes

• Because the measurement may take several 100 milliseconds a measurement cycle will be executed asynchronously, so do not expect to have new values immediately available after "set update" returns. If autoGain or autoIntegrationTime are enabled, more than one measurement cycle will be required if light conditions change.
• With HiPi and especially IODev there are several I2C interfaces available, some blocking, some non-blocking and some with different physical layers. The module has no knowledge of the specific properties of an interface and therefore module operation and timing may not be exactly the same with each interface type.
• If AUTO is used as device address, one address per measurement cycle will be tested. Depending on your device address it may be necessary to execute "set update" several times to find your device.
• When using Firmata the I2C write/read delay attribute "i2c-config" of the FRM module can be set to any value.

IF

[EN DE]

IF (<condition>) (<FHEM commands1>) ELSE (<FHEM commands2>)

Executes <FHEM commands1> if <condition> is true, else <FHEM commands2> are executed.

IF can be used anywhere where FHEM commands can be used.

The ELSE-case is optional.

The <condition> is the same as in perl-if.

In addition, readings can be specified in the form:

[<device>:<reading>:<format>|[<regular expression>]]

In addition, internals can be specified with & in the form:

[<device>:&<internal>:<format>|[<regular expression>]]

<format> and [<regular expression>] are filter options und are optional.

possible <format>:

'd' for decimal number

If only the state of a device is to be used, then only the device can be specified:

[<device>] corresponsed to [<device>:&STATE]

Examples:

IF in combination with at-module, Reading specified in the condition:

define check at +00:10 IF ([outdoor:humidity] > 70) (set switch1 off) ELSE (set switch1 on)

IF state query of the device "outdoor" in the condition:

define check at +00:10 IF ([outdoor] eq "open") (set switch1 on)

corresponds with details of the internal:

define check at +00:10 IF ([outdoor:&STATE] eq "open") (set switch1 on)

If the reading "state" to be queried, then the name of reading is specified without &:

define check at +00:10 IF ([outdoor:state] eq "open") (set switch1 on)

Nested IF commands (It can be entered in the DEF input on multiple lines with indentation for better representation):

define test notify lamp
IF ([lampe] eq "on") (

IF ([outdoor:humidity] < 70)

(set lamp off)
ELSE

(set lamp on)
) ELSE

(set switch on)

Filter by numbers in Reading "temperature":

define settemp at 22:00 IF ([tempsens:temperature:d] >= 10) (set heating on)

Filter by "on" and "off" in the status of the device "move":

define activity notify move IF ([move:&STATE:[(on|off)]] eq "on" and $we) (set lamp off)

Example of the use of Readings in the then-case:

define temp at 18:00 IF ([outdoor:temperature] > 10) (set lampe [dummy])

If an expression is to be evaluated first in a FHEM command, then it must be enclosed in brackets.
For example, if at 18:00 clock the outside temperature is higher than 10 degrees, the desired temperature is increased by 1 degree:

define temp at 18:00 IF ([outdoor:temperature] > 10) (set thermostat desired-temp {([thermostat:desired-temp:d]+1)})

Multiple commands are separated by a comma instead of a semicolon, thus eliminating the doubling, quadrupling, etc. of the semicolon:

define check at +00:10 IF ([outdoor:humidity] > 10) (set switch1 off,set switch2 on) ELSE (set switch1 on,set switch2 off)

If a comma in FHEM expression occurs, this must be additionally bracketed so that the comma is not recognized as a delimiter:

define check at +00:10 IF ([outdoor:humidity] > 10) ((set switch1,switch2 off))

IF in combination with a define at multiple set commands:

define check at *10:00 IF ([indoor] eq "on") (define a_test at +00:10 set lampe1 on;;set lampe2 off;;set temp desired 20)

The comma can be combined as a separator between the FHEM commands with double semicolon, eg:

define check at *10:00 IF ([indoor] eq "on") (set lamp1 on,define a_test at +00:10 set lampe2 on;;set lampe3 off;;set temp desired 20)

sleep can be used with comma, it is not blocking:

define check at *10:00 IF ([indoor] eq "on") (sleep 2,set lampe1 on,sleep 3,set lampe2 on)

Time-dependent switch: In the period 20:00 to 22:00 clock the light should go off when it was on and I leave the room:

define n_lamp_off notify sensor IF ($hms gt "20:00" and $hms lt "22:00" and [sensor] eq "absent") (set lamp:FILTER=STATE!=off off)

Combination of Perl and FHEM commands ($NAME and $EVENT can also be used):

define mail notify door:open IF ([alarm] eq "on")({system("wmail $NAME:$EVENT")},set alarm_signal on)


IOhomecontrol

[EN DE]

Define


define <name> IOhomecontrol <model> <host> <pwfile>

Defines an IOhomecontrol interface device (gateway) to communicate with IOhomecontrol devices. <model> is a placeholder for future amendments. Currently only the Velux Integra KLF200 Interface model KLF200 is supported as a gateway. <host> is the IP address or hostname of the IOhomecontrol interface device (gateway). <pwfile> is a file that contains the password to log into the device.

Example:
define myKLF200 IOhomecontrol KLF200 192.168.0.91 /opt/fhem/etc/veluxpw.txt




Set


set <name> scene <id>

Runs the scene identified by <id> which can be either the numeric id of the scene or the scene's name.

Examples:
set velux scene 1
set velux scene "all shutters down"


Scene names with blanks must be enclosed in double quotes.


Get


get <name> scenes

Retrieves the ids and names of the scenes from the device. This is done automatically after FHEM is initialized. So you should need this only if you have altered scenes in the interface device.

Example:
get myKLF200 scenes



get <name> sceneList

Displays the scenes.

get <name> log

Retrieves the event log from the device.

get <name> showLog

Displays the event log.

get <name> password

Reads the password from the password file <pwfile>. This is done automatically after FHEM is initialized. So you should need this only if you have altered the password in the file.


Attributes


• setCmds: a comma-separated list of set command definitions. Every definition is of the form <shorthand>=<command>. This defines a new single-word command <shorthand> as a substitute for <command>.
  Example: attr velux setCmds evening=scene "close all",morning=scene "open all"
  
  
• logTraffic: if set to a nonzero value, request and reply JSON strings are logged with log level 5 and stored in the callRequest and callReply readings. Use with caution because the password is transmitted in plain text in the authentication request.
  
  
• readingFnAttributes

IOhomecontrolDevice

[EN DE]

Define


define <name> IOhomecontrolDevice <interface>

Defines an IOhomecontrol device. <interface> is the name of the IOhomecontrol interface device (gateway) that is used to communicate with the IOhomecontrol devices.

Example:
define shutter1 IOhomecontrolDevice myKLF200




Set


set <name> scene <id>

Runs the scene identified by <id> which can be either the numeric id of the scene or the scene's name.

Examples:
set shutter1 scene 1
set shutter1 scene "3.dz.roll2 100%"


Scene names with blanks must be enclosed in double quotes.


Attributes


• setCmds: a comma-separated list of set command definitions. Every definition is of the form <shorthand>=<command>. This defines a new single-word command <shorthand> as a substitute for <command>.
  Example: attr shutter1 setCmds up=scene "3.dz.roll2 100%",down=scene "3.dz.roll2 0%"
  Substituted commands (and only these) are shown in the state reading. This is useful in conjunction with the devStateIcon attribute, e.g. attr shutter1 devStateIcon down:shutter_closed up:shutter_open.


• readingFnAttributes


Full example
define myKLF200 IOhomecontrol KLF200 velux.local /opt/fhem/etc/veluxpw.txt
attr myKLF200 verbose 5
attr myKLF200 logTraffic 1

define shutter1 IOhomecontrolDevice myKLF200
attr shutter1 setCmds up=scene "3.dz.roll2 0%",down=scene "3.dz.roll2 100%"
attr shutter1 webCmd up:down
attr shutter1 devStateIcon down:shutter_closed up:shutter_open


IPCAM

[EN DE]

Define
define <name> IPCAM <ip[:port]>

Defines a network camera device to trigger snapshots on events.

Network cameras (IP cameras) usually have a build-in function to create snapshot images. This module enables the event- or time-controlled recording of these images.
In addition, this module allows the recording of many image formats like JPEG, PNG, GIF, TIFF, BMP, ICO, PPM, XPM, XBM and SVG. The only requirement is that the recorded image must be accessible via a URL.
So it is also possible to record images of e.g. a public Weather Camera from the internet or any picture of a website.
Furthermore, it is possible to control the camera via PTZ-mode or custom commands.

Examples:

A local ip-cam takes 5 snapshots with 10 seconds delay per call:

define ipcam IPCAM 192.168.1.205
attr ipcam delay 10
attr ipcam path snapshot.cgi?user=foo&pwd=bar
attr ipcam snapshots 5
attr ipcam storage /srv/share/surveillance/snapshots


A notify on a motion detection of a specified device:

define MOTION.not.01 notify GH.ga.SEC.MD.01:.*on.* get ipcam image


Send an eMail after snapshots are taken:

define MOTION.not.02 notify ipcam:.*snapshots.* { myEmailFunction("%NAME") }


A public web-cam takes only 1 snapshot per call:

define schloss IPCAM www2.braunschweig.de
attr schloss path webcam/schloss.jpg
attr schloss storage /srv/share/surveillance/snapshots


An at-Job takes every hour a snapshot:

define snapshot_schloss at +*00:01:00 get schloss image


Move the camera up:

set ipcam tilt up

Move the camera to a the predefined position 4:

set ipcam pos 4


Set
set <name> <value> <argument>

where value is one of:

• cmd 1 .. 15
  Sets the camera to a custom defined command. The command must be defined as an attribute first.
  You can define up to 15 custom commands. The given number always relates to an equivalent attribute cmd<number>.
• pan <direction> [steps]
  Move the camera to the given <direction>, where <direction> could be left or right.
  The command always relates to an equivalent attribute cmdPan<direction>.
  Furthermore, a step size can be specified, which relates to the equivalent attribute cmdStep.
• pos 1 .. 15|home
  Sets the camera to a custom defined position in PTZ mode. The position must be defined as an attribute first.
  You can define up to 15 custom positions and a predefined home position. The given number always relates to an equivalent attribute cmdPos<number>.
• tilt <direction> [steps]
  Move the camera to the given <direction>, where <direction> could be up or down.
  The command always relates to an equivalent attribute cmdPan<direction>.
  Furthermore, a step size can be specified, which relates to the equivalent attribute cmdStep.
• raw <argument>
  Sets the camera to a custom defined argument.


Get
get <name> <value>

where value is one of:

• image
  Get one or more images of the defined IP-Cam. The number of images
  and the time interval between images can be specified using the
  attributes snapshots and delay.
• imageWithCallback
  Like get image, but allows you to provide a command
  that's executed as soon as the picture is taken.
  This is one-time trigger only, not for intervals and more images.
  Allows you to eg send pictures immediately and
  without creating a dedicated notify.
  Example:
  get ipcam3 imageWithCallback set pushmsg msg Frontdoor Ding Dong! expire=3600 attachment='www/snapshot/ipcam3_snapshot.jpg'
  The callback command can also hold references to other readings, internals, etc. The following example will lead to the same command as the first one:
  get ipcam3 imageWithCallback set pushmsg msg Frontdoor Ding Dong! expire=3600 attachment='www/snapshot/[ipcam3:latest]'
• last
  Show the name of the last snapshot.
• snapshots
  Show the total number of a image sequence.

Attributes
• basicauth
  If your camera supports authentication like http://username:password@domain.com/, you can store your creditials within the basicauth attribute.
  If you prefer to store the credentials in a file (take a look at the attribute credentials) you have to set the placeholder {USERNAME} and {PASSWORD} in the basicauth string. These placeholders will be replaced with the values from the credentials file.
  Example:
  attr ipcam3 basicauth {USERNAME}:{PASSWORD}
• blocking
  If set to 1, FHEM will make a blocking call to the camera. Try this if getting snapshot runs into timeouts regularly.
  Per default, this is set to 0.
• cmd01, cmd02, cmd03, .. cmd13, cdm14, cdm15
  It is possible to define up to 15 custom commands.
  Examples:
  attr ipcam cmd01 led_mode=0
attr ipcam cmd02 resolution=8
  
• cmd01data, cmd02data, ...
  You can define the POST data that is to be sent with the according cmd.
  If this is defined, the request will be POST instead of GET.
  Example:
  attr ipcam cmd01data [{"cmd":"Login"},{"cmd":"SetOSD"}]
  You can provide references to readings and internals easliy like this:
  attr ipcam cmd01data [{"cmd":"Login"},{"cmd":"SetOSD"},{"key":"[devicename:reading]"}]
  will be resolved into [{"cmd":"Login"},{"key":"value-from-reading"}]
• cmdPanLeft, cmdPanRight, cmdTiltUp, cmdTiltDown, cmdStep
  Depending of the camera model, are different commands necessary.
  Examples:
  attr ipcam cmdTiltUp command=0
attr ipcam cmdTiltDown command=2
attr ipcam cmdPanLeft command=4
attr ipcam cmdPanRight command=6
attr ipcam cmdStep onstep
  
• cmdPos01, cmdPos02, cmdPos03, .. cmdPos13, cmdPos14, cmdPos15, cmdPosHome It is possible to define up to 15 predefined position in PTZ-mode.
  Examples:
  attr ipcam cmdPosHome command=25
attr ipcam cmdPos01 command=31
attr ipcam cmdPos02 command=33
  
• credentials
  Defines the location of the credentials file.
  If you prefer to store your cam credentials in a file instead be a part of the URI (see attributes path and query), set the full path with filename on this attribute.
  Example:
  attr ipcam3 credentials /etc/fhem/ipcam.conf
  
  The credentials file has the following structure:
  

        #
        # Webcam credentials
        #
        $credentials{<name_cam1>}{username} = "<your_username>";
        $credentials{<name_cam1>}{password} = "<your_password>";
        $credentials{<name_cam2>}{username} = "<your_username>";
        $credentials{<name_cam2>}{password} = "<your_password>";
        ...
        

  Replace <name_cam1> respectively <name_cam2> with the names of your defined ip-cams and <your_username> respectively <your_password> with your credentials (all without the brackets < and >!).
• delay
  Defines the time interval between snapshots in seconds.
  If more then one snapshot is taken, then it makes sense to define a short delay between the snapshots. On the one hand, the camera is not addressed in short intervals and the second may be better represented movements between images.
  Example: attr ipcam3 delay 10
• disable
• do_not_notify
• readingFnAttributes
• handleAnyXmlAsSvg
  Previous versions of this module, any XML file was (maybe incorrectly) identified as SVG file.
  Now, only valid SVG files or SVG documents are identified as SVG, leading to a 'unknown format' response for any other XML file.
  If you rely on the previous behavior for any reason, setting this to 1 will handle any XML as valid SVG, writing it as .svg file to the storage.
  The default value is 0.
• unknownFormatRetryCount
  If this module is unable to guess the correct file format, your camera might have been under heavy load and unable to respond with a proper image file.
  The file format will be 'unknown' in that case. Setting this to a positive integer allows you to define how often
  this module should re-try to grab an image.
  Default value is 0.
  Example: attr ipcam3 unknownFormatRetryCount 3
• unknownFormatRetryDelay
  This defines the interval in seconds between retries, if [code]unknownFormatRetryCount[/code] is set to a positive integer.
  The following example sets a 5 seconds delay.
  Default is 2 seconds.
  Example: attr ipcam3 unknownFormatRetryDelay 5
• path
  Defines the path and query component of the complete URI to get a snapshot of the camera. Is the full URI of your ip-cam for example http://CAMERA_IP/snapshot.cgi?user=admin&pwd=password, then only the path and query part is specified here (without the leading slash (/).
  Example:
  attr ipcam3 path snapshot.cgi?user=admin&pwd=password
  
  If you prefer to store the credentials in a file (take a look at the attribute credentials) you have to set the placeholder {USERNAME} and {PASSWORD} in the path string. These placeholders will be replaced with the values from the credentials file.
  Example:
  attr ipcam3 path snapshot.cgi?user={USERNAME}&pwd={PASSWORD}
• pathCmd
  Defines a path for the custom commands, if it is necessary.
  Example:
  attr ipcam3 pathCmd set_misc.cgi
• pathPanTilt
  Defines a path for the PTZ-mode commands pan, tilt and pos, if it is necessary.
  Example:
  attr ipcam3 pathPanTilt decoder_control.cgi?user={USERNAME}&pwd={PASSWORD}
• query
  query string parameters that will be attached to all commands. Without leading ? or &
  Example:
  attr ipcam3 query user={USERNAME}&pwd={PASSWORD}
• showtime
• scheme
  Defines the URI-Scheme for generating the download path.
  If this attribute is not defined, then the default value is http. Default: http
  Example:
  attr ipcam3 scheme https
• snapshots
  Defines the total number of snapshots to be taken with the get <name> image command. If this attribute is not defined, then the default value is 1.
  The snapshots are stored in the given path of the attribute storage and are numbered sequentially (starts with 1) like snapshot_01, snapshot_02, etc. Furthermore, an additional file last will be saved, which is identical with the last snapshot-image. The module checks the imagetype and stores all these files with the devicename and a correct extension, e.g. <devicename>_snapshot_01.jpg.
  If you like a timestamp instead a sequentially number, take a look at the attribute timestamp.
  All files are overwritten on every get <name> image command (except: snapshots with a timestamp. So, keep an eye on your diskspace if you use a timestamp extension!).
  Example:
  attr ipcam3 snapshots 5
• storage
  Defines the location for the file storage of the snapshots.
  Default: $modpath/www/snapshots
  Example:
  attr ipcam3 storage /srv/share/surveillance/snapshots
• timestamp
  If this attribute is unset or set to 0, snapshots are stored with a sequentially number like <devicename>_snapshot_01.jpg, <devicename>_snapshot_02.jpg, etc.
  If you like filenames with a timestamp postfix, e.g. <devicename>_20121023_002602.jpg, set this attribute to 1.

Generated events
• last: <name_of_device>_snapshot.<image_extension>
• snapshots: <total_number_of_taken_snapshots_at_end>

IPWE

[EN DE]

Define
define <name> IPWE <hostname> [<delay>]

Define a IPWE network attached weather data receiver device sold by ELV. Details see here. It's intended to receive the same sensors as WS300 (8 T/H-Sensors and one kombi sensor), but can be accessed via http and telnet.
For unknown reason, my try to use the telnet interface was not working neither with raw sockets nor with Net::Telnet module. Therefore i choosed here the "easy" way to simple readout the http page and extract all data from the offered table. For this reason this module doesnt contain any option to configure this device.

Note: You should give your sensors a name within the web interface, once they a received the first time.
To extract a single sensor simply match for this name or sensor id

Attributes:
• delay: seconds between read accesses(default 300s)

Example:
define ipwe IPWE ipwe1 120

attr ipwe delay 600 : 10min between readouts



Set
N/A

Get
get <name> status

Gets actual data from device for sensors with data

get <name> <sensorname>

will grep output from device for this sensorname


Attributes
• model (ipwe)
• delay
• loglevel

IT - InterTechno

[EN DE]

The InterTechno 433MHZ protocol is used by a wide range of devices, which are either of the sender/sensor or the receiver/actuator category. Momentarily, we are able to send and receive InterTechno commands. Supported devices are switches, dimmers, etc. through an CUL or SIGNALduino device (this must be defined first).
This module supports the version 1 and version 3 of the Intertechno protocol. Newly found devices are added into the category "IT" by autocreate. Hint: IT protocol 1 devices are only created when pressing the on-button twice within 30 seconds.

Define
define <name> IT <housecode> <on-code> <off-code> [<dimup-code>] [<dimdown-code>]
or
define <name> IT <ITRotarySwitches|FLS100RotarySwitches>
or
define <name> IT <address 26 Bit> <group bit> <unit Code>
or
define <name> IT HE800 <Transmitter ID> <Receiver ID>

The value of <housecode> is a 10-digit InterTechno Code, consisting of 0/1/F (co called tri-state format). These digits depend on the device you are using.
Bit 11 and 12 are used for switching/dimming. Different manufacturers are using different bit-codes. You specifiy here the 2-digit code for off/on/dimup/dimdown using the tri state format, i.e., 0/1/F.
The value of ITRotarySwitches consists of the value of the alpha switch A-P and the numeric switch 1-16 as set on the intertechno device (for example A1 or G12). Please use the Wiki for more information how to decode your device.
The value of FLS100RotarySwitches consist of the value of the I,II,II,IV switch and the numeric 1,2,3,4 switch (for example I2 or IV4).
The value of ITRotarySwitches and FLS100RotarySwitches are internaly translated into a houscode value.
For the Intertechno protocol 3 the housecode consists of 26 numbers. Additionally 4 numbers are used as unit code as well as group code.
To add a new device in Fhem: define IT myITSwitch IT

Intertechno protocol 1 (ITv1)
• <housecode> 10 numbers in tri state format (i.e., either 0/1/F) depending on the device.
• <on-code> <off-code> 2 numbers in quad state format (0/1/F/D), containing the on-format; this number is added to the <housecode> to get the 12-number IT command that is acutally send.
• optional <dimup-code> <dimdown-code> 2 numbers in quad state format (0/1/F/D), contains the command for dimming; this number is added to the <housecode> to define tha actual 12-number sending command.
• If the attribute userV1setCodes exists, these codes are also used for reception, the userV1setCodes have priority over the XMIT Codes.
• Notice: orginal ITv1 devices are only defined using the on command.
• Devices which are nt orignal ITv1 devices cen be defined as follows:

To autocreate press twice "on" within 30 seconds. The Log gives:
2016.11.27 11:47:37.753 4: sduinoD IT: 001F001000 not defined (Switch code: 11)
2016.11.27 11:47:37.755 2: autocreate: define IT_001F001000 IT 001F001000 0F F0

Now press "off" or any other button:
2016.11.27 11:48:32.004 3: sduinoD IT: Code 1D not supported by IT_001F001000.

Because this is not original Intertechno, the on/off code in the list is not correct and has to be changed. This can be done as follows
DEF 001F001000 11 1D


• EV1527
If the housecode does not contain a valid (10) ITv1 tri state code, autocreate will define the deviceas EV1527.
<housecode> 1527xabcde , abcde is the collected housecode in hex format
<on-code> <off-code> 4 numbers bin number (0/1) containing the on command; this number is added to the housecode to get the entire 12-number sending command.
optional <dimup-code> <dimdown-code> 4 numbers in bin format (0/1), contains the command for dimming up or down; this number is added to the housecode to get the entire 12-number sending command.

If the device was autocreated the on/off- as well as the dimcode has to be adapted.


SBC_FreeTec

• <housecode> 8 numbers in tri state format (0/1/F), depending from the used device.
• <on-code> 4 numbers in tri state format, contains the on-command; this number is added to the housecode to form the 12-number sending command.
• <off-code> 4 numbers in tri state format, contains the off-command; this number is added to the housecode to get the 12-number sending command.

HE800

• <Transmitter ID> unique transmitter ID (1..65535)
• <Receiver ID> receiver ID [0]1..15, 0=Broadcast 1-15 (HE844A button# 1-4 & MASTER=0, HE850 UNIT# 1-15, HE853 = 1)

Examples:
define lamp IT 01FF010101 11 00 01 10
define roll1 IT 111111111F 11 00 01 10
define otherlamp IT 000000000F 11 10 00 00
define otherroll1 IT FFFFFFF00F 11 10
define IT_1527xe0fec IT 1527xe0fec 1001 0000
define SBC_FreeTec_Steck1 IT FFF00FFF 000F 0000
define itswitch1 IT A1
define lamp IT J10
define flsswitch1 IT IV1
define lamp IT II2
define HE800_TID1_SW1 IT HE800 1 1


For Intertechno protocol 3 the <housecode> is a 26-digits number. Additionaly there is a 4-digits <unit code> and a 1-digit <group code>.
• <address> is a 26 digit number (0/1)
• <group> is a 1 digit number (0/1)
• <unit> is a 4 digit number (0/1)

Examples:
define myITSwitch IT 00111100110101010110011111 0 0000

Set
set <name> <value> [<time>]

where value is one of:


    dimdown
    dimup
    off
    on
    on-till           # Special, see the note
    dim06% dim12% dim18% dim25% dim31% dim37% dim43% dim50%
    dim56% dim62% dim68% dim75% dim81% dim87% dim93% dim100%

    
set extensions are supported.

Examples:
set lamp on
set lamp1,lamp2,lamp3 on
set lamp1-lamp3 on
set lamp off


Notes:
• on-till requires an absolute time in the "at" format (HH:MM:SS, HH:MM or { <perl code> }, where the perl-code returns a time specification). If the current time is greater than the specified time, the command is ignored, else an "on" command is generated, and for the given "till-time" an off command is scheduleld via the at command.

Get
N/A

Attributes
• IODev
  Set the IO device which will be used to send signals for this device. An example for the physical device is a CUL or the SIGNALduino. Note: On startup, fhem WILL NOT automatically assign an IODevice to the Intertechno device! The attribute IODev needs ALLWAYS to be set manually!


• eventMap
  Replace event names and set arguments. The value of this attribute consists of a list of space separated values. Each value is a colon separated pair. The first part specifies the value to be replaced, the second the new/desired value. In order to use spaces in the new/desired values it is necessary to inform Fhem about the new separating character. This is done by using a slash(/) or comma(,) as first character, then the values are not separated by space but by this character. Examples:
  attr store eventMap on:open off:closed
attr store eventMap /on-for-timer 10:open/off:closed/
set store open


• do_not_notify


• dummy
  Set the device attribute dummy to define devices which should not output any radio signals. Associated notifys will be executed if the signal is received. Used e.g. to react to a code from a sender, but it will not emit radio signal if triggered in the web frontend.


• loglevel


• showtime


• readingFnAttributes


• model
  The model attribute denotes the type of the device. This attribute will (currently) not be used by Fhem directly. It can be used by e.g. external programs or web interfaces to distinguish classes of devices and send the appropriate commands (e.g. "on" or "off" to a switch, "dim..%" to dimmers etc.). The spelling of the model should match the modelname used in the documentation that comes which the device. The name should consist of lower-case characters without spaces. Valid characters are a-z 0-9 and - (dash), other characters should not be used. Here is a list of "official" devices:
  Sender/Sensor: itremote
  Dimmer: itdimmer
  door/window contact (china): itswitch_CHN (closed:1110 open:1010 tamper:0111)
  Receiver/Actor: itswitch
  EV1527: ev1527


• ignore
  Ignore this device, e.g., if it belongs to your neighbour. The device will not trigger any FileLogs/notifys, issued commands will be silently ignored (no RF signal will be sent out, just like for the dummy attribute). The device will not appear in the list command (only if it is explicitely asked for it), nor will it be affected by commands which use wildcards or attributes as name specifiers (see devspec). You still get them with the "ignored=1" special devspec.


• ITclock
  IT clock is the smallest time length of any pulse while sending the Intertechno V1 protocol.
  Any signal of the IT protocol typically consists of a sequence of HIGHs and LOWs with a particular time length. These lengths usually have a ratio of 1:3 (if, for example, LOW has a pulse length of X then HIGH has a pulse length of 3*X).
  The default value of original IT devices is 250. Other vendors use sometimes a different value; nevertheless ITclock should only be changed if you encounter problems using this device in Fhem.
  - In order to discover the correct ITclock using a SIGNALduino: After pressing a button at a remote the received raw signal can be found in the log as well as in the device view of the IT-device, for example
  MS;P0=357;P2=-1128;P3=1155;P4=-428;P5=-11420;D=05023402020202020202020202020202020202023402340234;CP=0;SP=5;
  The number after "CP=" shows the pattern number of the clock, so e.g. follows from CP=0 --> P0, which defines at the beginning of the message, hence the clock was 357 (microseconds).
  - at the CUL can the ITclock found out from the raw messages (X31).


• ITfrequency
  Sets the frequency of the sender.


• ITrepetition
  Sets the number of repitions (default=6).


• userV1setCodes
  If an ITv1 protocol is used indivual setcodes can be added.
  The setcodes are also used for reception, the userV1setCodes have priority over the XMIT Codes.
  Example:
  attr lamp userV1setCodes red:FD blue:1F
attr lamp userV1setCodes up:1001 down:1000 stop:1011
attr IT_1527x12345 userV1setCodes closed:0111 open:1110 tamper:1011 lowVoltage:1111 # Kerui magnetic contact sensors


• SIGNALduinoProtocolId
  Using this attribute the protocol ID can be choosen if one uses a SIGNALduino.



Generated events:
The IT device generates the following events.
• on
• off
• dimdown
• dimup
  
• dim06% dim12% dim18% dim25% dim31% dim37% dim43% dim50%
  dim56% dim62% dim68% dim75% dim81% dim87% dim93% dim100%
  
Which event is sent dependents on the device and can sometimes configured on the device.

Iluminize

[EN DE]

Define define <name> Iluminize <ip/hostname>

Defines a wifi controlled Iluminize LED light

InfluxDBLogger

[EN DE]

Module for logging to InfluxDB time-series databases. According to the InfluxDB terminology, here is the default mapping, which can be changed via attributes:
• A measurement will be created for each reading name.
• A tag called 'site_name' will be used for each device
• A field called 'value' will be used for each reading value
The default API version is v1. To change this, set the api-attribute. Another way to use this module with InfluxDB 2 is to map the buckets to databases. see here

Define

define <name> InfluxDBLogger [http|https]://IP_or_Hostname:port dbname devspec

For details about devspec see here. If you use a wildcard devspec, the device will be disabled on default in order to let you specify a readings-regex to reduce the log-amount.


Set

• password set <name> password <password>
  Securely stores the password for basic authentication. It is only used if security attribute is set to basic_auth.
• token set <name> token <token>
  Securely stores the token for token based authentication. It is only used if security attribute is set to token.
• resetStatistics set <name> resetStatistics
  Sets all statistical counters to zero and removes the last error message.
• write set <name> write
  Writes the current values of the configured readings(readingInclude,readingExclude) of the configured devices(devspec) to the database. This is useful e.g. for clean start of the day and end of the day values. Note that the timestamp of the readings are not stored in the database, but the timestamp of the write operation.

Attributes

• disable attr <name> disable [0|1]
  If disabled no readings will be written to the database
• security attr <name> security [basic_auth|none|token]
  If basic_auth is used, you have to define an user attribute and set a password
  If token is used, you have to set a token
  
• username attr <name> username <username>
  Only used if security attribute is set to basic_auth
  
• readingInclude attr <name> readingInclude <regex>
  Only reading events that match the regex will be logged. Note that readings usually have the format: 'state: on'
  
• readingExclude attr <name> readingInclude <regex>
  Only reading events that do not match the regex will be logged. Note that readings usually have the format: 'state: on'
  
• deviceTagName attr <name> deviceTagName <deviceTagName>
  This will be the name of the device tag. default is 'site_name'
• conversions attr <name> conversions <conv1,conv2>
  Comma seperated list of replacements e.g. open=1,closed=0,tilted=2 or true|on|yes=1,false|off|no=0 Right side can be any perl expression and thus used to replace regular expression groups like this: ([0-9]+)%=$1 which extract the number out of a percentage value.
• measurement attr <name> measurement <string>
  Name of the measurement to use. This can be any string. The keyword $DEVICE will be replaced by the device-name. The keyword $READINGNAME will be replaced by the reading-name Default is $READINGNAME. Perl-Expressions can be used in curly braces. $name, $device, $reading, $value are available as variables. attr influx measurement { AttrVal($device, "influx_measurement", $reading)}
• tags attr <name> tags <x,y>
  This is the list of tags that will be sent to InfluxDB. The keyword $DEVICE will be replaced by the device-name. If this attribute is set it will override the attribute deviceTagName. If the attribute is set to "-" no tags will be written (useful if measurement is set to $DEVICE and fields to $READINGNAME=$READINGVALUE) Default is site_name=$DEVICE. Perl-Expressions can be used in curly braces to evaluate the alias-attribute as a tag for example. $name, $device, $reading, $value are available as variables. attr influx tags device={AttrVal($device, "alias", "fallback")}
• fields attr <name> fields <val=$READINGVALUE>
  This is the list of fields that will be sent to InfluxDB. The keyword $READINGNAME will be replaced by the reading-name. The keyword $READINGVALUE will be replaced by the reading-value. Default is value=$READINGVALUE.
• api attr <name> api [v1|v2]
  The api-Version to use. Default is v1. Using API Version v2 the database name is used as the bucket-name.
• org attr <name> org <org>
  Using API Version v2 the organisation is specified by this. Default is "privat".
• precision attr <name> precision [ms|s|us|ns]
  The time precision is specified by this. Default is none.
• stringValuesAllowed attr <name> stringValuesAllowed [0|1]
  If enabled (1) it allows to write strings as value, if disabled(0) non-numeric values will be blocked (dropped). Conversions are always processed first. Put conversion to string in double quotes like: 1="open" Note: InfluxDB cannot change the datatype of a field. Changing this attribute after some data is already written might lead to error messages. Default: 0 (non-numeric values are blocked)
• readingTimeStamps attr <name> readingTimeStamps [0|1]
  If enabled(1) the ReadingTimestamp from FHEM is send to InfluxDB, Default is off(0). This is useful for devices that publish the values later with the original timestamp delayed. Default: 0 (InfluxDB determines the timestamp on its own)

Readings

• total_writes
  Total number of initiated log events. These are the attempts to write, not the completed ones.
• succeeded_writes
  Total number of successfully completed log events. These are the writes that you will find in the database.
• failed_writes
  Total number of failed log events. These are failed due to some error which is captured in the log and in the reading failed_writes_last_error
• failed_writes_last_error
  The last captured error. This is very useful for systematic problems, like wrong DNS or a wrong port, aso.
• dropped_writes
  Total number of dropped writes due to non numeric value. See conversions to fix.
• state
  Statistics: t=total_writes s=succeeded_writes f=failed_writes e=events

InfoPanel

[EN DE]

InfoPanel is an extension to FHEMWEB. You must install FHEMWEB to use InfoPanel.


Prerequesits


• InfoPanel is an extension to FHEMWEB. You must install FHEMWEB to use InfoPanel.


• Module uses following additional Perl modules:
  
  
  MIME::Base64 Image::Info
  
  If not already installed in your environment, please install them using appropriate commands from your environment.
  
  Package installation in debian environments: apt-get install libmime-base64-perl libimage-info-perl


• You can use this module without the two additional perl modules, but in this case, you have to accept some limitations:
  
  
  • layout tag img can not be used
  • layout tag plot can only handle scale = 1 and inline = 0


Define


define <name> InfoPanel layout=layoutFileName

Example:


define myInfoPanel InfoPanel layout=./FHEM/panel.layout



Set-Commands


• set <name> reread
  
  Rereads the layout definition from the file.
  
  Important:
  
  Layout will be reread automatically if edited via fhem's "Edit files" function.
  Autoread can be disabled via attribute.


• set <name> ovEnable <xconditionName>
  
  set an override "1" to named xcondition


• set <name> ovDisable <xconditionName>
  
  set an override "0" to named xcondition


• set <name> ovClear <xconditionName>|all;
  
  delete an existing overrides to named xcondition. "all" will clear all overrides.
  


Get-Commands


• get <name> counter
  
  return value from internal counter
  


• get <name> layout
  
  return complete layout definition
  


• get <name> overrides
  
  return list of defined overrides
  





Attributes


• autoreread - disables automatic layout reread after edit if set to 1
• refresh - time (in seconds) after which the HTML page will be reloaded automatically.
  Any values below 60 seconds will not become valid.
• showTime - disables generation timestamp in state if set to 0
• size - The dimensions of the picture in the format <width>x<height>
• useViewPort - add viewport meta tag to fit mobile displays
• mobileApp - add support for mobile fullscreen experience
• title - webpage title to be shown in Browser


• bgcenter - background images will not be centered if attribute set to 0. Default: show centered
• bgcolor - defines the background color, use html-hexcodes to specify color, eg 00FF00 for green background. Default color is black. You can use bgcolor=none to disable use of any background color
• bgdir - directory containing background images
• bgopacity - set opacity for background image, values 0...1.0
• tmin - background picture will be shown at least tmin seconds, no matter how frequently the feed consumer accesses the page.

Important: bgcolor and bgdir will be evaluated by { <perl special> } use quotes for absolute values!



Generated Readings/Events:


• state - show time and date of last layout evaluation


Layout definition


All parameters in curly brackets can be evaluated by { <perl special> }


• area <id> <x1> <y1> <x2> <y2> <{link}>
  
  
  create a responsive area which will call a link when clicked.
  
  id = element id
  x1,y1 = upper left corner
  x2,y2 = lower right corner
  link = url to be called
  



• boxcolor <{rgba}>
  
  
  define an rgb color code to be used for filling button and textbox
  



• button <id> <x1> <y1> <x2> <y2> <r1> <r2> <link> <text>
  
  
  create a responsive colored button which will call a link when clicked.
  
  id = element id
  x1,y1 = upper left corner
  x2,y2 = lower right corner
  r1,r2 = radius for rounded corners
  link = url to be called
  text = text that will be written onto the button
  
  button will be filled with color defined by "boxcolor"
  text color will be read from "rgb" value
  



• buttonpanel
  
  
  needed once in your layout file if you intend to use buttons in the same layout.
  



• circle <id> <x> <y> <r> [<fill>] [<stroke-width>] [<link>]
  
  
  create a circle
  
  id = element id
  x,y = center coordinates of circle
  r = radius
  fill = circle will be filled with "rgb" color if set to 1. Default = 0
  stroke-width = defines stroke width to draw around the circle. Default = 0
  link = URL to be linked to item
  



• counter <id> <x> <y>
  
  
  print internal counter
  
  id = element id
  x,y = position
  



• date <id> <x> <y>
  
  
  print date
  
  id = element id
  x,y = position
  



• embed <id> <x> <y> <width> <height> <{object}>
  
  
  embed any object
  
  id = element id
  x,y = position
  width,height = containers's dimension
  object = object to embed
  



• ellipse <id> <x> <y> <r1> <r2> [<fill>] [<stroke-width>] [<link>]
  
  
  create an ellipse
  
  id = element id
  x,y = center coordinates of ellipse
  r1,r2 = radius
  fill = ellipse will be filled with "rgb" color if set to 1. Default = 0
  stroke-width = defines stroke width to draw around the ellipse. Default = 0
  link = URL to be linked to item
  



• font <font-family>
  
  
  define font family used for text elements (text, date, time, seconds ...)
  
  Example: font arial
  



• group <id> open <x> <y>
group - close  (id will not be evaluated, just give any value)
  
  
  group items
  
  open|close = define start and end of group
  x,y = upper left corner as reference for all grouped items, will be inherited to all elements.
  
  Examples:
  group - open 150 150
rect ...
img ...
group - close




• img <id> <x> <y> <scale> <link> <sourceType> <{dataSource}>s
  
  
  embed an image into InfoPanel
  
  id = element id
  x,y = upper left corner
  scale = scale to be used for resizing; may be factor or defined by width or height
  link = URL to be linked to item, use "" if not needed
  sourceType = file | url | data
  dataSource = where to read data from, depends on sourceType
  



• line <id> <x1> <y1> <x2> <y2> [<stroke>]
  
  
  draw a line
  
  id = element id
  x1,y1 = coordinates (start)
  x2,y2 = coordinates (end)
  stroke = stroke width for line; if omitted, default = 0
  



• moveby <x> <y>
  
  
  move most recently x- and y-coordinates by given steps
  



• movecalculated <{perlSpecial x}> <{perlSpecial y}>
  
  
  calculate x- and y-coordinates by perlSpecials
  



• moveto <x> <y>
  
  
  move x- and y-coordinates to the given positon
  



• padding <width>
  
  
  border width (in pixel) to be used in textboxes
  



• plot <id> <x> <y> <scale> <inline> <{plotName}>
  
  
  embed an SVG plot into InfoPanel
  
  id = element id
  x,y = upper left corner
  scale = scale to be used for resizing; may be factor or defined by width or height
  inline = embed plot as data (inline=1) or as link (inline=0)
  plotName = name of desired SVG device from your fhem installation
  



• pop
  
  
  fetch last parameter set from stack and set it actice
  



• pt <[+-]font-size>
  
  
  define font size used for text elements (text, date, time, seconds ...)
  can be given as absolute or relative value.
  
  Examples:
  pt 12
pt +3
pt -2
  



• push
  
  
  push active parameter set onto stack
  



• rect <id> <x1> <y1> <x2> <y2> <r1> <r2> [<fill>] [<stroke-width>] [<link>]
  
  
  create a rectangle
  
  id = element id
  x1,y1 = upper left corner
  x2,y2 = lower right corner
  r1,r2 = radius for rounded corners
  fill = rectangle will be filled with "rgb" color if set to 1. Default = 0
  stroke-width = defines stroke width to draw around the rectangle. Default = 0
  link = URL to be linked to item
  



• rgb <{rgb[a]}>
  
  
  define rgba value (hex digits!) used for text, lines, circles, ellipses
  
  r = red value
g = green value
b = blue value
a = alpha value used for opacity; optional
  



• seconds <id> <x> <y> [<format>]
  
  
  print seconds
  
  id = element id
  x,y = position
  format = seconds will be preceeded by ':' if set to 'colon'; optional
  



• text <id> <x> <y> <{text}>
  
  
  print text
  
  id = element id
  x,y = position
  text = text content to be printed
  



• textbox <id> <x> <y> <boxWidth> <boxHeight> <{link}> <{text}>
  
  
  create a textbox to print text with auto wrapping
  
  id = element id
  x,y = upper left corner
  boxWidth,boxHeight = dimensions of textbox
  link = url to be used when clicked; use "" if not needed
  text = text to be printed in textbox
  
  Important: textboxes are not responsive via area tag. Use optional link parameter in textbox tag
  



• textboxalign <align>
  
  
  define horizontal alignment for text inside textboxes
  
  valid values: left center right justify
  



• textdesign <align>
  
  
  define comma-separated list for text design and decoration
  
  valid values: underline overline line-through bold italic oblique clear
  
  Examples:
  textdesign underline
textdesign bold,italic,underline
  
  Important: "clear" resets all to default values!
  



• thalign <align>
  
  
  define horizontal alignment for text output
  
  valid values: start middle end
  



• ticker <id> <x> <y> <width> <items> <speed> <{data}>
  
  
  create a vertical ticker
  
  id = element id
  x,y = position
  width = width
  items = number of items to be displayed simultanously
  speed = scroll speed
  data = list of text items, separated by \n
  



• time <id> <x> <y>
  
  
  print time
  
  id = element id
  x,y = position
  



• tvalign <align>
  
  
  define vertical alignment for text output
  
  valid values: auto baseline middle center hanging
  




Author's notes


• Have fun!

Installer

[EN DE]

Installer - Module to update FHEM, install 3rd-party FHEM modules and manage system prerequisites


Define

define <name> Installer

Example:

define fhemInstaller Installer





Get
• checkPrereqs - list all missing prerequisites. If no parameter was given, the running live system will be inspected. If the parameter is a FHEM cfg file, inspection will be based on devices from this file. If the parameter is a list of module names, those will be used for inspection.
• search - search FHEM for device names, module names, package names, keywords, authors and Perl package names.
• showModuleInfo - list information about a specific FHEM module
• showPackageInfo - list information about a specific FHEM package
• zzGetModuleMETA.json - prints raw meta information of a FHEM module in JSON format
• zzGetPackageMETA.json - prints raw meta information of a FHEM package in JSON format


Attributes
• disable - disables the device
• disabledForIntervals - disable device for interval time (13:00-18:30 or 13:00-18:30 22:00-23:00)
• installerMode - sets the installation mode. May be update, developer or install with update being the default setting. Some get and/or set commands may be hidden or limited depending on this.

Itach_IR

[EN DE]

Defines a device representing a physical Itach IR. Serves as communication layer for Itach_IRDevice.
For more information, check the Wiki page.

Define
define <name> Itach_IR <IP-address>
Example:
define Itach Itach_IR 192.168.1.2

Set

N/A


Get

N/A


Attributes
• verbose
• timeout
  Can be used to change the timeout-value for tcp-communication. Default is 2.0.

Itach_IRDevice

[EN DE]

Itach IR is a physical device that serves to emit Infrared (IR) commands, hence it is a general IR remote control that can be controlled via WLAN (WF2IR) or LAN (IP2IR).
Using the iLearn-Software that ships with every Itach IR, record the IR-squences per original remotecontrol-button and store all these IR-codes as an IR-config-file. This IR-config-file can then be used directly with this module. All commands stored in the IR-config-file will be available immediately for use.
For more information, check the Wiki page.

Define
define <name> Itach_IRDevice <IR-config-file>
Store the IR-config-file in the same directory where fhem.cfg resides.
Hint: define an Itach_IR device first!
Example:
define IR_mac Itach_IRDevice IR-codes-mac.txt
define IR_amp Itach_IRDevice IR-codes-media-amplifier.txt

Set
set <name> <command> [<parameter>]

The list of available commands depends on the content of the IR-config-file.
There are only two module specific commands:
• set <name> rereadIRfile
  For performance reasons, the IR-config-File is read into memory upon definition of the device. If you change the configuration within that file, use this set-command to read its content into fhem once again.
• set <name> seqsingle <parameter>
  Will send the digits of a sequence one after the other. Useful when you have a sequence of digits to be sent, e.g. 123. Each digit must be a valid command in your IR-config-file.

Get
• get <name> validcommands
  Lists the valid commands for this device according to your IR-config-file.

Attributes
• verbose
• IODev
  Needs to be stated if more than one ItachIR-device is part of your fhem-configuration.

JSONMETER

[EN DE]

This module reads data from a measurement unit (so called smart meters for electricity, gas or heat)
that provides OBIS compliant data in JSON format on a webserver or on the FHEM file system.
It assumes normally, that the structure of the JSON data do not change.
 
Define

define <name> JSONMETER <deviceType> [<ip address>] [poll-interval]
Example: define powermeter JSONMETER ITF 192.168.178.20 300
 
• <deviceType>
  Mandatory. Used to define the path and port to extract the json file.
  The attribute 'pathString' can be used to add login information to the URL path of predefined devices.
   
  • ITF - FROETEC Simplex ME one tariff electrical meter (N-ENERGY) (ITF Fröschl)
  • EFR - EFR Smart Grid Hub for electrical meter (EON, N-ENERGY and EnBW)
          use the 'pathstring' attribute to specifiy your login information
          attr pathString ?LogName=user&LogPSWD=password
  • LS110 - YouLess LS110 network sensor (counter) for electro mechanical electricity meter
  • LS120 - YouLess LS120 new model
  • url - use the URL defined via the attributes 'pathString' and 'port'
  • file - use the file defined via the attribute 'pathString' (positioned in the FHEM file system)


• [<ip address>]
  IP address of the phyisical device. (not needed for 'url' and 'file')


• [poll-interval]
  Optional. Default is 300 seconds. Smallest possible value is 10. With 0 it will only update on "manual" request.

Set
• activeTariff < 0 - 9 >
  Allows the separate measurement of the consumption (doStatistics = 1) within different tariffs for all gages that miss this built-in capability (e.g. LS110). Also the possible gain of a change to a time-dependent tariff can be evaluated with this.
  This value must be set at the correct point of time in accordance to the existing or planned tariff by the FHEM command "at".
  0 = without separate tariffs


• INTERVAL <polling interval>
  Polling interval in seconds


• resetStatistics <statReadings>
  Deletes the selected statistic values: all, statElectricityConsumed..., statElectricityConsumedTariff..., statElectricityPower...


• restartJsonAnalysis
  Restarts the analysis of the json file for known readings (compliant to the OBIS standard).
  This analysis happens normally only once if readings have been found.


• statusRequest
  Update device information

Get
• jsonFile
  extracts and shows the json data


• jsonAnalysis
  extracts the json data and shows the result of the analysis

Attributes
• alwaysAnalyse < 0 | 1 >
  Repeats by each update the json analysis - use if structure of json data changes
  Normally the once analysed structure is saved to reduce CPU load.


• doStatistics < 0 | 1 >
  Builds daily, monthly and yearly statistics for certain readings (average/min/max or cumulated values).
  Logging and visualisation of the statistics should be done with readings of type 'statReadingNameLast'.


• pathString <string>
  • if deviceType = 'file': specifies the local file name and path
  • if deviceType = 'url': specifies the url path
  • other deviceType: can be used to add login information to the url path of predefined devices


• port <number>
  Specifies the IP port for the deviceType 'url' (default is 80)


• timeOut <seconds>
  Specifies the timeout for the reading of the raw data. (default is 10)
  The run time of the reading process can be measured via "get jsonFile".


• readingFnAttributes

Jabber

[EN DE]

This Module allows FHEM to connect to the Jabber Network, send and receiving messages from and to a Jabber server.

Jabber is another description for (XMPP) - a communications protocol for message-oriented middleware based on XML and - depending on the server - encrypt the communications channels.
For the user it is similar to other instant messaging Platforms like Facebook Chat, ICQ or Google's Hangouts but free, Open Source and by default encrypted between the Jabber servers.

You need an account on a Jabber Server, you can find free services and more information on jabber.org
Discuss the module in the specific thread here.

This Module requires the following perl Modules to be installed (using SSL):

• Net::Jabber
• Net::XMPP
• Authen::SASL
• XML::Stream
• Net::SSLeay

Since version 1.5 it allows FHEM also to join MUC (Multi-User-Channels) and the use of OTR for end to end encryption
If you want to use OTR you must compile and install Crypt::OTR from CPAN on your own.


Define
define <name> Jabber <server> <port> <username> <password> <TLS> <SSL>

You have to create an account on a free Jabber server or setup your own Jabber server.

Example:
define JabberClient1 Jabber jabber.org 5222 myusername mypassword 1 0



Set
• set <name> msg <username> <msg>
  sends a message to the specified username
  Examples:
  set JabberClient1 msg myname@jabber.org It is working!
  


• set <name> msgmuc <channel> <msg>
  sends a message to the specified MUC group channel
  Examples:
  set JabberClient1 msgmuc roomname@jabber.org Woot!
  


• set <name> msgotr <username> <msg>
  sends an Off-the-Record encrypted message to the specified username, if no OTR session is currently established it is being tried to esablish an OTR session with the specified user.
  If the user does not have OTR support the message is discarded.
  Examples:
  set JabberClient1 msgotr myname@jabber.org Meet me at 7pm at the place today :*
  


• set <name> subscribe <username>
  asks the username for authorization (not needed normally)
  Example:
  set JabberClient1 subscribe myname@jabber.org
  

Get
N/A

Attributes
• OnlineStatus available|unavailable
  Sets the online status of the client, available (online in Clients) or unavailable (offline in Clients)
  It is possible, on some servers, that FHEM can even recieve messages if the status is unavailable
  
  Default: available


• ResourceName <name>
  In XMPP/Jabber you can have multiple clients connected with the same username.
  The resource name finally makes the Jabber-ID unique to each client.
  Here you can define the resource name.
  
  Default: FHEM


• PollTimer <seconds>
  This is the interval in seconds at which the jabber server get polled.
  Every interval the client checks if there are messages waiting and checks the connection to the server.
  Don't set it over 10 seconds, as the client could get disconnected.
  
  Default: 2


• RecvWhitelist <Regex>
  Only if the Regex match, the client accepts and interpret the message. Everything else will be discarded.
  
  Default: .*
  Examples:
  
  myname@jabber.org
(myname1@jabber.org|myname2@xmpp.de)
  


• MucJoin channel1@server.com/mynick[:password]
  Allows you to join one or more MUC's (Multi-User-Channel) with a specific Nick and a optional Password
  
  Default: empty (no messages accepted)
  Examples:
  
  Join a channel: channel1@server.com/mynick
  Join more channels: channel1@server.com/mynick,channel2@server.com/myothernick
  Join a channel with a password set: channel1@server.com/mynick:password
  


• MucRecvWhitelist <Regex>
  Same as RecvWhitelist but for MUC: Only if the Regex match, the client accepts and interpret the message. Everything else will be discarded.
  
  Default: empty (no messages accepted)
  Examples:
  
  All joined channels allowed: .*
  Specific channel allowed only: mychannel@jabber.org
  Specific Nick in channel allowed only: mychannel@jabber.org/NickOfFriend
  


• OTREnable 1|0
  Enabled the use of Crypt::OTR for end to end encryption between a device and FHEM
  You must have Crypt::OTR installed and a private key is being generated the first time you enable this option
  Key generation can take more than 2 hours on a quiet system but will not block FHEM instead it will inform you if it has been finished
  Key generation is a one-time-task
  
  Default: empty (OTR disabled)


• OTRSharedSecret aSecretKeyiOnlyKnow@@*
  Optional shared secret to allow the other end to start a trust verification against FHEM with this shared key.
  If the user starts a trust verification process the fingerprint of the FHEM private key will be saved at the user's device and the connection is trusted.
  This will allow to inform the user if the private key has changed (ex. in Man-in-the-Middle attacks)
  
  Default: empty, please define a shared secret on your own.



Generated Readings/Events:
• Private Messages
  • Message - Complete message including JID and text
  • LastMessage - Only text portion of the Message
  • LastSenderJID - Only JID portion of the Message


• Encrypted Private Messages (if OTREnable=1)
  • OTRMessage - Complete decrypted message including JID and text
  • OTRLastMessage - Only text portion of the Message
  • OTRLastSenderJID - Only JID portion of the Message


• MUC Room Messages (if MUCJoin is set)
  • MucMessage - Complete message including room's JID and text
  • MucLastMessage - Only text portion of the Message
  • MucLastSenderJID - Only JID portion of the Message

Author's Notes:
• You can react and reply on incoming private messages with a notify like this:
  

  define Jabber_Notify notify JabberClient1:Message.* {
    my $lastsender=ReadingsVal("JabberClient1","LastSenderJID","0");
    my $lastmsg=ReadingsVal("JabberClient1","LastMessage","0");
    my $temperature=ReadingsVal("BU_Temperatur","temperature","0");
    fhem("set JabberClient1 msg ". $lastsender . " Temp: ".$temperature);
  }
          

• You can react and reply on MUC messages with a notify like this, be aware that the nickname in $lastsender is stripped off in the msgmuc function
  

  define Jabber_Notify notify JabberClient1:MucMessage.* {
    my $lastsender=ReadingsVal("JabberClient1","LastSenderJID","0");
    my $lastmsg=ReadingsVal("JabberClient1","LastMessage","0");
    my $temperature=ReadingsVal("BU_Temperatur","temperature","0");
    fhem("set JabberClient1 msgmuc ". $lastsender . " Temp: ".$temperature);
  }
          

• You can react and reply on OTR private messages with a notify like this:
  

  define Jabber_Notify notify JabberClient1:OTRMessage.* {
    my $lastsender=ReadingsVal("JabberClient1","LastSenderJID","0");
    my $lastmsg=ReadingsVal("JabberClient1","LastMessage","0");
    my $temperature=ReadingsVal("BU_Temperatur","temperature","0");
    fhem("set JabberClient1 msgotr ". $lastsender . " Temp: ".$temperature);
  }
          

JawboneUp

[EN DE]

This module supports the Jawbone Up[24] fitness tracker. The module collects calories, steps and distance walked (and a few other metrics) on a given day.

All communication with the Jawbone services is handled as background-tasks, in order not to interfere with other FHEM services.

Installation Among the perl modules required for this module are: LWP::UserAgent, IO::Socket::SSL, WWW::Jawbone::Up.
At least WWW:Jawbone::Up doesn't seem to have a debian equivalent, so you'll need CPAN to install the modules.
Example: cpan -i WWW::Jawbone::Up should install the required perl modules for the Jawbone up.
Unfortunately the WWW::Jawbone::Up module relies on quite a number of dependencies, so in case of error, check the CPAN output for missing modules.
Some dependent modules might fail during self-test, in that case try a forced install: cpan -i -f module-name

Error handling If there are more than three consecutive API errors, the module disables itself. A "get update" re-enables the module.
API errors can be caused by wrong credentials or missing internet-connectivity or by a failure of the Jawbone server.

Configuration Define
define <name> JawboneUp <user> <password> [<interval>]

Defines a JawboneUp device.
Parameters
• name
  A name for your jawbone device.
• user
  Username (email) used as account-name for the jawbone service.
• password
  The password for the jawbone service.
• interval
  Optional polling intervall in seconds. Default is 3600, minimum is 300 (=5min). It is not recommended to go below 900sec.

Example:
define myJawboneUp JawboneUp me@foo.org myS3cret 3600
attr myJawboneUp room Jawbone


Readings
• active_time
  (Active time (seconds))
• bg_steps
  (Step count)
• bmr_calories
  (Resting calories)
• bmr_calories_day
  (Average daily calories (without activities))
• calories
  (Activity calories)
• distance
  (Distance in km)
• longest_idle
  (Inactive time in seconds)
  
• sleep_awake
  (Awake time during sleep in seconds)
• sleep_asleep
  (Actual sleep during sleep period, time in seconds)
• awakenings
  (Awakenings)
• light
  (Light sleep during sleep period, time in seconds)
• time_to_sleep
  (Time to fall asleep in seconds)
• bedtime
  (Time in bed)
• deep
  (Deep sleep in seconds)
• awake
  (Time awake in seconds)
• sleep_mode
  (0: sleep mode inactive, 1: sleep mode active) Note: this is not real-time since updates depend on the module's poll-intervall
• stopwatch_mode
  (0: not in stopwatch mode, 1: stopwatch mode active) Note: not suitable for real-time measurements for the reasons above.

Get
• update
  trigger an update

Attributes
• interval
  the interval in seconds for updates. the default ist 3600 (=1h), minimum is 300 (=5min). It is not recommended to go below 900sec.
• disable
  1 -> disconnect and stop polling

JeeLink

[EN DE]

The JeeLink is a family of RF devices sold by jeelabs.com. It is possible to attach more than one device in order to get better reception, fhem will filter out duplicate messages.

This module provides the IODevice for:
• PCA301 modules that implement the PCA301 protocol.
• LaCrosse modules that implement the IT+ protocol (Sensors like TX29DTH, TX35, ...).
• LevelSender for measuring tank levels
• EMT7110 energy meter
• Other Sensors like WT440XH (their protocol gets transformed to IT+)

Note: this module may require the Device::SerialPort or Win32::SerialPort module if you attach the device via USB and the OS sets strange default parameters for serial devices.

Define
define <name> JeeLink <device>

USB-connected devices:

<device> specifies the serial port to communicate with the JeeLink. The name of the serial-device depends on your distribution, under linux the cdc_acm kernel module is responsible, and usually a /dev/ttyACM0 device will be created. If your distribution does not have a cdc_acm module, you can force usbserial to handle the JeeLink by the following command:
modprobe usbserial vendor=0x0403 product=0x6001
In this case the device is most probably /dev/ttyUSB0.

You can also specify a baudrate if the device name contains the @ character, e.g.: /dev/ttyACM0@57600

If the baudrate is "directio" (e.g.: /dev/ttyACM0@directio), then the perl module Device::SerialPort is not needed, and fhem opens the device with simple file io. This might work if the operating system uses sane defaults for the serial parameters, e.g. some Linux distributions and OSX.



Set
• raw <data>
  send <data> to the JeeLink. Depending on the sketch running on the JeeLink, different commands are available. Most of the sketches support the v command to get the version info and the ? command to get the list of available commands.


• reset
  force a device reset closing and reopening the device.


• LaCrossePairForSec <sec> [ignore_battery]
  enable autocreate of new LaCrosse sensors for <sec> seconds. If ignore_battery is not given only sensors sending the 'new battery' flag will be created.


• flash [firmwareName]
  The JeeLink needs the right firmware to be able to receive and deliver the sensor data to fhem. In addition to the way using the arduino IDE to flash the firmware into the JeeLink this provides a way to flash it directly from FHEM.
  
  The firmwareName argument is optional. If not given, set flash checks the firmware type that is currently installed on the JeeLink and updates it with the same type.
  
  There are some requirements:
  • avrdude must be installed on the host
    On a linux systems like Cubietruck or Raspberry Pi this can be done with: sudo apt-get install avrdude
  • the flashCommand attribute must be set.
    This attribute defines the command, that gets sent to avrdude to flash the JeeLink.
    The default is: avrdude -p atmega328P -c arduino -P [PORT] -D -U flash:w:[HEXFILE] 2>[LOGFILE]
    It contains some place-holders that automatically get filled with the according values:
    
    • [PORT]
      is the port the JeeLink is connectd to (e.g. /dev/ttyUSB0)
    • [HEXFILE]
      is the .hex file that shall get flashed. There are three options (applied in this order):
      - passed in set flash
      - taken from the hexFile attribute
      - the default value defined in the module
      
    • [LOGFILE]
      The logfile that collects information about the flash process. It gets displayed in FHEM after finishing the flash process


• led <on|off>
  Is used to disable the blue activity LED


• beep
  ...


• setReceiverMode
  ...


Get

Attributes
• Clients
  The received data gets distributed to a client (e.g. LaCrosse, EMT7110, ...) that handles the data. This attribute tells, which are the clients, that handle the data. If you add a new module to FHEM, that shall handle data distributed by the JeeLink module, you must add it to the Clients attribute.
• MatchList
  can be set to a perl expression that returns a hash that is used as the MatchList
  attr myJeeLink MatchList {'5:AliRF' => '^\\S+\\s+5 '}
• initCommands
  Space separated list of commands to send for device initialization.
  This can be used e.g. to bring the LaCrosse Sketch into the data rate toggle mode. In this case initCommands would be: 30t
• flashCommand
  See "Set flash"
• timeout
  format: <timeout, checkInterval> Checks every 'checkInterval' seconds if the last data reception is longer than 'timout' seconds ago.
  If this is the case, a reset is done for the IO-Device.

JsonList2

[EN DE]

jsonlist2 [<devspec>] [<value1> <value2> ...]

This is a command, to be issued on the command line (FHEMWEB or telnet interface). Can also be called via HTTP by
http://fhemhost:8083/fhem?cmd=jsonlist2&XHR=1
Returns an JSON tree of the internal values, readings and attributes of the requested definitions.
If valueX is specified, then output only the corresponding internal (like DEF, TYPE, etc), reading (actuator, measured-temp) or attribute for all devices from the devspec.

Note: the old command jsonlist (without the 2 as suffix) is deprecated and will be removed in the future

JsonMod

[EN DE]

JsonMod provides a generic way to load and parse json files from HTTP sources periodically. Elements within the json files can be selected and displayed in a targeted manner.

JsonMod uses the JsonPath syntax to access elements or lists within the json file. The well-known cron syntax is used for the periodic retrieval of the files.

Define
define <name> JsonMod <http[s]:example.com:/somepath/somefile.json>

defines the device and set the source (file:|http:|https:|system://).

files example:
• file:[//]/path/file (absolute)
• file:[//]path/file (realtive)

system example:
• system://curl -X POST "https://httpbin.org/anything" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"login":"my_login","password":"my_password"}'

Set
• reread
  set <name> reread
  
  Trigger a load and processing of the json source manually.
• secret
  set <name> secret <identifier> <value>
  
  To prevent the leakage of sensitive information, like credentials or api keys, they can be stored separate and thus are not shown neither in the config file nor in listings. Access to that information is provided by putting square brackets and the identifier [identifier] into the http source within the definition or in a http header (see attribute).

Get
N/A

Attributes
• interval
  attr <name> interval <*/15 * * * *>
  utilize a cron expression to define the interval at which the source file will be loaded. Default is one hour.
#
• onEmptyResponse
  # Controls the module behaviour if an empty response is received. #
  #
  • # not set or empty (default):
    # the device will be updated to no computed readings and an event is triggered () #
  #
  #
• readingList
  Specifies the access to json elements and their representation as well as formatting as reading. In its conventions, the syntax follows normal perl expression but uitlies a special set of instructions. This means that an expression must end with a semicolon, parentheses must be equal, and be of the correct type. When using double quotes, the content is interpolated. Since Jsonpath uses the '$' and '@' characters as part of the syntax, they must be escaped in expressions within double quotes. It is therefore preferable to use single quotes wherever possible.
  
  Recognized expressions (where '$.' is a placeholder for a valid json path expression):
  • single(jsonPath('$.'), 'readingname', 'default value');
    creates one reading. The json path expression must translate into a value (not into an array or an object)
  • multi(jsonPath('$.'), <Instructions for creating the reading name>, <property>);
    creates multiple (0..n) readings. Jsonpath expression must translate into an array of objects or values. Because the number of readings is variable, a function is used to generate the reading names. Typically, this is based on the index of the array element and / or a property of the addressed objects.
  • complete();
    Automatically creates readings for the entire JSON source. The readings ​​are named after their JSON path.
  • jsonPath('$.')
    Creates a jsonpath expression as part of a 'single' or 'multi' expression.
  • jsonPathf('$.', 'format')
    Creates a jsonpath expression as part of a 'single' expression and format its result. The syntax of the expression 'format' match to the syntax of printf.
  • property('expression')
    Is used to access properties of the json objects within a multi() statement.
  • propertyf('expression', 'format')
    Is used to access properties of the json objects within a multi() statement and format its result. The syntax of the expression 'format' match to the syntax of printf.
  • concat('expression', 'expression', ...)
    Concatenates the expressions to one result. Can be used in a 'multi()' statement to create a reading name from one or more object properties or the index.
  • count|count()
    Contains the index number of the current list element. Within 'multi()' instructions for generating reading names, eg by using concat('item_', count) or similar.
  • node|node()
    Contains the normalized path expression of the current node. Required to access the keys of an object when iterating over a keys/value structure of an object. Within 'multi()' instructions eg for generating reading names from object keys.
  
  within the expresiions single() and multi(), additional perl expressions may be used if required.
  
  Since the reading names are typically generated from the content of the JSON, it is the responsibility of the user to ensure that the fhem naming conventions are followed. JsonMod will make the following adjustments to the readings name if necessary and possible:
  • All non-ACSII characters are converted to an ASCII equivalent if possible
  • All forbidden characters are removed from the name
  • if a conversion fails, the name is set as "__CONVERSATION_ERROR__"
  • in case of multiple same reading names, the last one overwrites the previous one

KM271

[EN DE]

KM271 is the name of the communication device for the Buderus Logamatic 2105 or 2107 heating controller. It is connected via a serial line to the fhem computer. The fhem module sets the communication device into log-mode, which then will generate an event on change of the inner parameters. There are about 20.000 events a day, the FHEM module ignores about 90% of them, if the all_km271_events attribute is not set.


Note: this module requires the Device::SerialPort or Win32::SerialPort module.

Define
define <name> KM271 <serial-device-name>

Example:
define KM271 KM271 /dev tyS0@2400


Set
set KM271 <param> [<value> [<values>]]

where param is one of:
• hk1_tagsoll <temp>
  sets the by day temperature for heating circuit 1
  0.5 celsius resolution - temperature between 10 and 30 celsius
• hk2_tagsoll <temp>
  sets the by day temperature for heating circuit 2
  (see above)
• hk1_nachtsoll <temp>
  sets the by night temperature for heating circuit 1
  (see above)
• hk2_nachtsoll <temp>
  sets the by night temperature for heating circuit 2
  (see above)
• hk1_urlaubsoll <temp>
  sets the temperature during holiday mode for heating circuit 1
  (see above)
• hk2_urlaubsoll <temp>
  sets the temperature during holiday mode for heating circuit 2
  (see above)
• hk1_aussenhalt_ab <temp>
  sets the threshold for working mode Aussenhalt for heating circuit 1
  1.0 celsius resolution - temperature between -20 and 10 celsius
• hk2_aussenhalt_ab <temp>
  sets the threshold for working mode Aussenhalt for heating circuit 2
  (see above)
• hk1_betriebsart [automatik|nacht|tag]
  sets the working mode for heating circuit 1
  
  • automatik: the timer program is active and the summer configuration is in effect
  • nacht: manual by night working mode, no timer program is in effect
  • tag: manual by day working mode, no timer program is in effect
• hk2_betriebsart [automatik|nacht|tag]
  sets the working mode for heating circuit 2
  (see above)
• ww_soll <temp>
  sets the hot water temperature
  1.0 celsius resolution - temperature between 30 and 60 celsius
• ww_betriebsart [automatik|nacht|tag]
  sets the working mode for hot water
  
  • automatik: hot water production according to the working modes of both heating circuits
  • nacht: no hot water at all
  • tag: manual permanent hot water
• ww_on-till [localtime]
  start hot water production till the given time is reached
  localtime must have the format HH:MM[:SS]
  ww_betriebsart is set according to the attribut ww_timermode. For switching-off hot water a single one-time at command is automatically generated which will set ww_betriebsart back to nacht
• ww_zirkulation [count]
  count pumping phases for hot water circulation per hour
  count must be between 0 and 7 with special meaning for
  
  • 0: no circulation at all
  • 7: circulation is always on
• sommer_ab <temp>
  temp defines the threshold for switching between summer or winter mode of the heater
  1.0 celsius resolution - temp must be between 9 and 31 with special meaning for
  
  • 9: fixed summer mode (only hot water and frost protection)
  • 31: fixed winter mode
• frost_ab <temp>
  temp defines the threshold for activation of frost protection of the heater
  1.0 celsius resolution - temp must be between -20 and 10 celsius
• urlaub [count]
  sets the duration of the holiday mode to count days
  count must be between 0 and 99 with special meaning for
  
  • 0: holiday mode is deactivated
• hk1_programm [eigen|familie|frueh|spaet|vormittag|nachmittag|mittag|single|senior]
  sets the timer program for heating circuit 1
  
  • eigen: the custom program defined by the user (see below) is used
  • all others: predefined programs from Buderus for various situations (see Buderus manual for details)
• hk2_programm [eigen|familie|frueh|spaet|vormittag|nachmittag|mittag|single|senior]
  sets the timer program for heating circuit 2
  (see above)
• hk1_timer [<position> delete|<position> <on-day> <on-time> <off-day> <off-time>]
  sets (or deactivates) a by day working mode time interval for the custom program of heating circuit 1
  
  • position: addresses a slot of the custom timer program and must be between 1 and 21
    The slot will be set to the interval specified by the following on- and off-timepoints or is deactivated when the next argument is delete.
  • on-day: first part of the on-timepoint
    valid arguments are [mo|di|mi|do|fr|sa|so]
  • on-time: second part of the on-timepoint
    valid arguments have the format HH:MM (supported resolution: 10 min)
  • off-day: first part of the off-timepoint
    (see above)
  • off-time: second part of the off-timepoint
    valid arguments have the format HH:MM (supported resolution: 10 min)
  As the on-timepoint is reached, the heating circuit is switched to by day working mode and when the off-timepoint is attained, the circuit falls back to by night working mode. A program can be build up by chaining up to 21 of these intervals. They are ordered by the position argument. There's no behind the scene magic that will automatically consolidate the list. The consistency of the program is in the responsibility of the user.
  
  Example:
  set KM271 hk1_timer 1 mo 06:30 mo 08:20
  
  
  This will toogle the by day working mode every Monday at 6:30 and will fall back to by night working mode at 8:20 the same day.
• hk2_timer [<position> delete|<position> <on-day> <on-time> <off-day> <off-time>]
  sets (or deactivates) a by day working mode time interval for the custom program of heating circuit 2
  (see above)
• logmode
  set to logmode / request all readings again
• datetime
  send the current date and time to the controller

Get
get KM271 <param>

where param is one of:
• l_fehler
  gets the latest active error (code and message)
• l_fehlerzeitpunkt
  gets the timestamp, when the latest active error occured (format of Perl-function 'time')
• l_fehleraktualisierung
  gets the timestamp, of the latest update of an error status (format of Perl-function 'time')

Attributes
• do_not_notify
• all_km271_events
  If this attribute is set to 1, do not ignore following events:
  HK1_Vorlaufisttemperatur, HK1_Mischerstellung, HK2_Vorlaufisttemperatur, HK2_Mischerstellung, Kessel_Vorlaufisttemperatur, Kessel_Integral, Kessel_Integral1
  These events account for ca. 92% of all events.
  All UNKNOWN events are ignored too, most of them were only seen directly after setting the device into logmode.
• ww_timermode [automatik|tag]
  Defines the working mode for the ww_on-till command (default is tag).
  ww_on-till will set the ww_betriebsart of the heater according to this attribute.
• readingsFilter
  Regular expression for selection of desired readings.
  Only readings which will match the regular expression will be used. All other readings are suppressed in the device and even in the logfile.
• additionalNotify
  Regular expression for activation of notify for readings with normally suppressed events.
  Useful for *_Vorlaufisttemperatur readings if notification should be activated only for a specific reading and not for all like all_km271_events.

Generated events:
• Abgastemperatur
• Aussentemperatur
• Aussentemperatur_gedaempft
• Brenner_Ansteuerung
• Brenner_Ausschalttemperatur
• Brenner_Einschalttemperatur
• Brenner_Laufzeit1_Minuten2
• Brenner_Laufzeit1_Minuten1
• Brenner_Laufzeit1_Minuten
• Brenner_Laufzeit2_Minuten2
• Brenner_Laufzeit2_Minuten1
• Brenner_Laufzeit2_Minuten
• Brenner_Mod_Stellglied
• ERR_Fehlerspeicher1
• ERR_Fehlerspeicher2
• ERR_Fehlerspeicher3
• ERR_Fehlerspeicher4
• ERR_Alarmstatus
• HK1_Ausschaltoptimierung
• HK1_Aussenhalt_ab
• HK1_Betriebswerte1
• HK1_Betriebswerte2
• HK1_Einschaltoptimierung
• HK1_Heizkennlinie_10_Grad
• HK1_Heizkennlinie_-10_Grad
• HK1_Heizkennlinie_0_Grad
• HK1_Mischerstellung
• HK1_Pumpe
• HK1_Raumisttemperatur
• HK1_Raumsolltemperatur
• HK1_Vorlaufisttemperatur
• HK1_Vorlaufsolltemperatur
• HK2_Ausschaltoptimierung
• HK2_Aussenhalt_ab
• HK2_Betriebswerte1
• HK2_Betriebswerte2
• HK2_Einschaltoptimierung
• HK2_Heizkennlinie_10_Grad
• HK2_Heizkennlinie_-10_Grad
• HK2_Heizkennlinie_0_Grad
• HK2_Mischerstellung
• HK2_Pumpe
• HK2_Raumisttemperatur
• HK2_Raumsolltemperatur
• HK2_Vorlaufisttemperatur
• HK2_Vorlaufsolltemperatur
• Kessel_Betrieb
• Kessel_Fehler
• Kessel_Integral
• Kessel_Integral1
• Kessel_Vorlaufisttemperatur
• Kessel_Vorlaufsolltemperatur
• Modulkennung
• NoData
• Versionsnummer_NK
• Versionsnummer_VK
• WW_Betriebswerte1
• WW_Betriebswerte2
• WW_Einschaltoptimierung
• WW_Isttemperatur
• WW_Pumpentyp
• WW_Solltemperatur

As I cannot explain all the values, I logged data for a period and plotted each received value in the following logs:
• Aussentemperatur
• Betriebswerte
• Brenneransteuerung
• Brennerlaufzeit
• Brennerschalttemperatur
• Heizkennlinie
• Kesselbetrieb
• Kesselintegral
• Ladepumpe
• Raumsolltemperatur_HK1
• Vorlauftemperatur
• Warmwasser
All of these events are reported directly after initialization (or after requesting logmode), along with some 60 configuration records (6byte long each). Most parameters from these records are reverse engeneered, they all start with CFG_ for configuration and PRG_ for timer program information.

KM273

[EN DE]

KM273 implements the can bus communication with the buderus logatherm wps heat pump
The software expect an SLCAN compatible module like USBtin It is also possible to communicate over TCP/IP with a socketcand interface can0

Define
define <name> KM273 <device>

Example SLCAN USB: define myKM273 KM273 /dev/ttyACM0@115200
Example socketcand: define myKM273 KM273 192.168.178.74:29536



Set

set <name> <option> <value>

Example:
set myKM273 DHW_TIMEPROGRAM 1
set myKM273 DHW_TIMEPROGRAM Always_On

You can set any value to any of the following options.

Options:
• DHW_CALCULATED_SETPOINT_TEMP
  preset for hot water temperature
• DHW_TIMEPROGRAM
  select: '0' or 'Always_On', '1' or 'Program_1', '2' or 'Program_2'
• DHW_PROGRAM_MODE
  select: '0' or 'Automatic', '1' or 'Always_On', '2' or 'Always_Off'
• DHW_PROGRAM_1_1MON .. ROOM_PROGRAM_1_7SUN
  value: 06:00 on 21:00 off
• DHW_PROGRAM_2_1MON .. ROOM_PROGRAM_2_7SUN
  value: 06:00 on 21:00 off
• PUMP_DHW_PROGRAM1_START_TIME .. PUMP_DHW_PROGRAM4_STOP_TIME
  dayly program for switching on and off the hot water circulation pump
  you can set 4 time ranges where the pump should be switched on value: xx:xx
• HEATING_SEASON_MODE
  select: '0' or 'Automatic', '1' or 'Always_On', '2' or 'Always_Off'
• ROOM_TIMEPROGRAM
  time program for circuit 1
  select: '0' or 'HP_Optimized', '1' or 'Program_1', '2' or 'Program_2', '3' or 'Family', '4' or 'Morning', '5' or 'Evening', '6' or 'Seniors'
• ROOM_PROGRAM_MODE
  room program for circuit 1
  select: '0' or 'Automatic', '1' or 'Normal', '2' or 'Exception', '3' or 'HeatingOff'
• ROOM_PROGRAM_1_1MON .. ROOM_PROGRAM_1_7SUN
  times of Program_1 for circuit 1
  value: 06:00 on 21:00 off
• ROOM_PROGRAM_2_1MON .. ROOM_PROGRAM_2_7SUN
  times of Program_2 for circuit 1
  value: 06:00 on 21:00 off
• MV_E12_EEPROM_TIME_PROGRAM
  time program for circuit 2
  select: '0' or 'HP_Optimized', '1' or 'Program_1', '2' or 'Program_2', '3' or 'Family', '4' or 'Morning', '5' or 'Evening', '6' or 'Seniors'
• MV_E12_EEPROM_ROOM_PROGRAM_MODE
  room program for circuit 2
  select: '0' or 'Automatic', '1' or 'Normal', '2' or 'Exception', '3' or 'HeatingOff'
• MV_E12_EEPROM_TIME_PROGRAM_1_1MON .. MV_E12_EEPROM_TIME_PROGRAM_1_7SUN
  times of Program_1 for circuit 2
  value: 06:00 on 21:00 off
• MV_E12_EEPROM_TIME_PROGRAM_2_1MON .. MV_E12_EEPROM_TIME_PROGRAM_2_7SUN
  times of Program_2 for circuit 2
  value: 06:00 on 21:00 off
• XDHW_STOP_TEMP
  extra hot water temperature
• XDHW_TIME
  hours for extra hot water

Special Options:
• ReadAll
  read once all 2000..2600 paramater of the heatpump
  the values will be logged into standard fhem log
  on second read, only the changed values are logged
• RAW
  Send CAN RAW message in USBTin/SLCAN format: read Riiiiiiii0, write TiiiiiiiiLvv...
• StoreElementList
  The parameter table read from heatpump is stored to file ./log/KM237ElementList.json

Get

get <name> <option>

You can get the value of any of the options described in paragraph "Set" above. See commandref#get for more info about the get command.

Attributes
attr <name> <attribute> <value>

See commandref#attr for more info about the attr command.

Attributes:
• DoNotPoll 0|1
  When you set DoNotPoll to "1", the module is only listening to the telegrams on CAN bus. The Parameter table is still read from heatpump! Default is "0".
  
• ListenOnly 0|1
  When you set ListenOnly to "1", the module is only listening to the telegrams on CAN bus. Also the Parameter table isn't read from heatpump. Default is "0".
  
• LoadElementList 0|1
  When you set LoadElementList to "1", the module load the Parameter table from file ./log/KM237ElementList.json. The Parameter table isn't read from heatpump, then. Default is "0".
  
• HeatCircuit2Active 0|1
  When you set HeatCircuit2Active to "1", the module read and set also the values for the second heating circuit E12. Default is "0".
  
• AddToReadings List of Variables
  additional variables, which are not polled by the module can by added here
  Example: attr myKM273 AddToReadings GT3_STATUS GT5_STATUS GT5_ANSLUTEN
  
• AddToGetSet List of Variables
  additional variables, which are not in get/set list definded by the module can by added here
  Example: attr myKM273 AddToGetSet ACCESS_LEVEL GT3_KORRIGERING GT5_KVITTERAD
  

KNX

[EN DE]

• Introduction
  

  KNX is a standard for building automation / home automation. It is mainly based on a twisted pair wiring, but also other mediums (ip, wireless) are specified.

  For getting started, please refer to this document: KNX for your home - knx.org web-site.

  While the TUL-module, KNXTUL-module, or KNXIO-module represent the connection to the KNX network, the KNX module represent a individual KNX device.
  This module provides a basic set of operations (on, off, toggle, on-until, on-for-timer) to switch on/off KNX devices and to send values to the bus. 

  Sophisticated setups can be achieved by combining multiple KNX-groupaddresses:datapoints (GAD's:dpt's) in one KNX device instance.

  KNX defines a series of Data-Point-Types (dpt) as standard data types to allow interpretation/encoding of messages from/to devices manufactured by different vendors. These datatypes are used to interpret the status of a device, so the readings in FHEM will show the correct value and optional unit.

  The KNX-Bus protocol defines three basic commands, any KNX-device, including FHEM, has to support:

  1. write - send a msg to KNX-bus - FHEM implementation: set cmd
  2. read  - send request for a msg to another KNX-device - FHEM implementation: get cmd
  3. reply - send answer when receiving a read-cmd from KNX-Bus - FHEM implementation: putCmd attribute

  For each received message there will be a reading containing the received value and the sender address.
  For every set, there will be a reading containing the sent value.
  The reading <state> will be updated with the last sent or received value. 

  A (german) wiki page is avaliable here: FHEM Wiki

• Define
  

  define <name> KNX <group>:<dpt>[:[<gadName>]:[set|get|listenonly]:[nosuffix]] [<group>:<dpt> ..] [IODev]

  The <group> parameter is either a group name notation (0-31/0-7/0-255) or the hex representation of it ([00-1f][0-7][00-ff]) (5 digits). All of the defined groups can be used for bus-communication. It is not allowed to have the same group-address more then once in one device. You can have multiple FHEM-devices containing the same group-adresses.

  Important: a KNX device needs at least one valid DPT matching the dpt-spec of the KNX-Hardware. The system cannot en- or de-code messages without a valid dpt defined.
  

  If <gadName> not specified, the default is "g<number>". The corresponding reading-names are getG<number> and setG<number>.
  The optional parameteter <gadName> may contain an alias for the GAD. The following gadNames are not allowed: state, on, off, on-for-timer, on-until, off-for-timer, off-until, toggle, raw, rgb, string, value, set, get, listenonly, nosuffix - because of conflict with cmds & parameters.
  If you supply <gadName> this name is used instead as cmd prefix. The reading-names are <gadName>-get and <gadName>-set. The synonyms <getName> and <setName> are used in this documentation.
  If you add the option "nosuffix", <getName> and <setName> have the identical name - <gadName>. Both sent and received bus messages will be stored in the same reading <gadName>
  If you want to restrict the GAD, use the options "get", "set", or "listenonly". The usage is described in Set/Get-cmd chapter. It is not possible to combine the options.
  

  Specifying an IO-Device in define is deprecated! Use attribute IODev instead, but only if absolutely required!

  If enabled, the module autocreate is creating a new definition for each not already defined group-address. However, the new device will be disabled until you added a DPT to the definition and delete the disable attribute. The device name will be KNX_<llaaddd> where ll is the line-, aa the area- and ddd the device-address. No FileLog or SVG definition is created for KNX-devices by autocreate. Use for example:
  define <name> FileLog <filename> KNX_.*
  to create a single FileLog-definition for all KNX-devices created by autocreate. Another option is to disable autocreate for KNX-devices in production environments (when no changes / additions are expected) by using: attr <autocreate> ignoreTypes KNX_.*

  Examples:
     define lamp1 KNX 0/7/11:dpt1
     attr lamp1 webCmd on:off
     attr lamp1 devStateIcon on:li_wht_on:off off:li_wht_off:on
  
     define lamp2 KNX 0/7/12:dpt1:switch:set 0/7/13:dpt1.001:status:listenonly
  
     define lamp3 KNX 0070E:dpt1.001 # equivalent to 0/7/14:dpt1.001
  

• Set
  

  set <deviceName> [<gadName>] on|off|toggle
set <deviceName> <gadName> blink <nr of blinks> <duration seconds>
set <deviceName> <gadName> on-for-timer|off-for-timer <duration seconds>
set <deviceName> <gadName> on-until|off-until <timespec (HH:MM[:SS])>


  Set sends the given value to the bus.
  If <gadName> is omitted, the first listed GAD of the device definition is used. If you want to send to a different group, you have to address it (see Examples). Without additional attributes, all incoming and outgoing messages are in addition copied into reading <state>.
  If the GAD is restricted in the definition with "get" or "listenonly", the set-command will be refused.
  For dpt1 and dpt1.001 valid values are on, off, toggle and blink. Also the timer-functions can be used. A running timer-function will be cancelled if a new set cmd (on,off,on-for-,....) for this GAD is issued.
  For all other dpt1.<xxx> the min- and max-values can be used for en- and de-coding alternatively to on/off.
  All DPTs: allowed values or range of values are specified here: KNX-dpt
  After successful sending, the value is stored in readings <setName> and state.
  Do not use wildcards for <deviceName>, the KNX-GW/Bus might be not perfomant enough to handle that. The last sentence is not true for definitions that use module KNXIO as IO-device. The KNXIO Module implements a queing mechanism to prevent KNX-bus overload.

  Examples:
     set lamp2 on  # gadName omitted
     set lamp2 off # gadName omitted
     set lamp2 switch on
     set lamp2 switch off
     set lamp2 switch on-for-timer 10 # seconds - seconds > 86400 are supported, fractions of seconds if seconds < 10
     set lamp2 switch on-until 13:15:00 # if timestamp is earlier than "now", device will be switched off tomorrow !
     set lamp2 switch on-till 13:15:00  # if timestamp is earlier than "now", cmd will be rejected (same function as in SetExtensions) 
     set lamp2 status on # will be refused - status has option "listenonly" set 
  
     set lamp3 g1 off-for-timer 86460 # switch off until tomorrow, same time + 60 seconds
     set lamp3 g1 off-until 13:15:00   
     set lamp3 g1 off-till 13:15:00  # if timestamp is earlier than "now", cmd will be rejected (same function as in SetExtensions)
     set lamp3 g1 toogle    # lamp3 change state
     set lamp3 g1 blink 2 4 # lamp3 on for 4 seconds, off for 4 seconds, 2 repeats
  
     set myThermoDev g1 23.44
  
     set myMessageDev g1 Hello World! # dpt16 def
  

  More complex examples can be found on the (german) Wiki

• Get
  

  If you execute "get" for a KNX-Element the status will be requested from the KNX-device. The device has to be able to respond to a read - this might not be supported by the target KNX-device.
  If the GAD is restricted in the definition with "set" or "listenonly", the execution will be refused.
  The answer from the bus-device updates the readings <getName> and state.
  Do not use wildcards for <deviceName>, the KNX-GW/Bus might be not perfomant enough to handle that. The last sentence is not true for definitions that use module KNXIO as IO-device. The KNXIO Module implements a queing mechanism to prevent KNX-bus overload, but you can also use KNX_scan cmd instead.

• Common attributes
  
  
  1. DbLogInclude
  2. DbLogExclude
  3. DbLogValueFn
  4. alias
  5. cmdIcon
  6. comment
  7. devStateIcon
  8. devStateStyle
  9. disable
  10. event-aggregator
  11. event-min-interval
  12. event-on-change-reading
  13. event-on-update-reading
  14. eventMap
  15. group
  16. icon
  17. oldreadings
  18. room
  19. showtime
  20. sortby
  21. stateFormat
  22. timestamp-on-change-reading
  23. userReadings
  24. suppressReading
  25. userattr
  26. verbose
  27. webCmd
  28. webCmdLabel
  29. widgetOverride
  30.  
  
  
• Special attributes
  
  • stateRegex
    This function modifies the value of reading state. It is executed directly after replacing the reading-names and processing "format" Attr, but before stateCmd.
    You can pass mutiple pairs of regex-patterns and strings to replace, separated by a space. A regex-pair is always in the format /<readingName>[:<value>]/[2nd part]/. The first part is not handled as regex, have to be exactly equal the readingname, and optional (separated by a colon) the readingValue. If first part match, the matching part will be replaced by the 2nd part of the regex. If the 2nd part is empty, the value is ignored and reading state will not get updated. The substitution is done every time a reading is updated. You can use this function for converting, adding units, having more fun with icons, ...

    Examples:
       attr <device> stateRegex /position:0/aus/ # on update of reading "position" and value=0, reading state value will be "aus"
       attr <device> stateRegex /position/pos-/  # on update of reading "position" reading state value will be prepended with "pos-".
       attr <device> stateRegex /desired-pos//   # reading state will NOT get updated when reading "desired-pos" is updated.
    

  • stateCmd
    Unlike stateFormat the stateCmd modifies the value of the reading state, not only the hash-content for visualization.
    You can supply a perl-command for modifying the value of reading state. This command is executed directly before updating the reading - so after renaming, format and stateRegex.
    You can access the device-hash ( e.g: $hash{IODev} ) in yr. perl-cmd. In addition the variables "$name", "$gadName" and "$state" are avaliable. A return value must be set and overrides reading state value. More examples - see Wiki

    Examples:
       attr <device> stateCmd {return sprintf("%.1f",ReadingsNum($name,'g1',0)*3.6);} # multiply reading value 'g1' and set value into state-reading
       attr <device> stateCmd {my99Utilssub($name,$gadName,$state);} # call subroutine (99_myUtils.pm ?) and use return value as state value
       attr <device> stateCmd {return 123 if ($gadName eq 'position' && $state eq 'off'); return $state;} # on change of GadName position and value = off ..., else no change  
    

  • putCmd
    Every time a KNX-value is requested from the bus to FHEM, the content of putCmd is evaluated before the answer is sent. You can use a perl-command for modifying content. This command is executed directly before sending the data. A copy is stored in the reading <putName>.
    Each device only knows one putCmd, so you have to take care about the different GAD's/readings in the perl string.
    Like in stateCmd you can access the device hash ("$hash") in yr. perl-cmd. In addition the variables "$name", "$gadName" and "$state" are avaliable. On entry, "$state" contains the current value of reading "state". The return-value will be sent to KNX-bus unless the the return value is undefined. The value has to be in the allowed range and format for the corresponding dpt, else the send is rejected. The reading "state" will NOT get updated.

    Examples:
       attr <device> putCmd {return $state if($gadName eq 'status'); return;} #returns value of reading state on request from bus for gadName "status".
       attr <device> putCmd {return ReadingsVal('dummydev','state','error') if(...); return;}         #returns value of device "dummydev" reading "state".
       attr <device> putCmd {return (split(/[\s]/xms,TimeNow()))[1] if ($gadName eq 'time'); return;} #returns system timestamp (dpt10 format) ...
    

  • format
    The content of this attribute is appended to every sent/received value before readings are set, it replaces the default unit-value! "format" will be appied to ALL readings, it is better to use the (more complex) "stateCmd" or "stateRegex" attributes if you have more than one GAD in your device.
    
  • disable
    Disable the device if set to 1. No send/receive from bus and no set/get possible. Delete this attr to enable device again. Deleting this attribute is prevented in case the definition is incomplete or contains errors!
    As an aid for debugging, an additional INTERNAL: "RAWMSG" will show any message received from bus while the device is disabled.
    
  • KNX_toggle
    As there is no direct support in KNX devices for toggle cmd, we have to lookup the current value before issuing set <device> <gadName> toggle cmd.
    This attribute is used to define the source of the current value.
    Format is: <devicename>:<readingname>. If you want to use a reading from own device, you can use "$self" as devicename. Be aware that only on and off are supported as valid values when defining <device>:<readingname>.
    If this attribute is not defined, the current value will be taken from <owndevice>:<readingName-get> or, if <readingName-get> is not defined, the value will be taken from <readingName-set>.
    
  • IODev
    Due to changes in IO-Device handling, (default IO-Device will be stored in reading IODev), setting this Attribute is no longer required, except in cases where multiple IO-devices (of type TUL/KNXTUL/KNXIO) exist in your config. Defining more than one IO-device is NOT recommended unless you take special care with yr. knxd or KNX-router definitions - to prevent multiple path from KNX-Bus to FHEM resulting in message loops.
    
  • widgetOverride
    This is a standard FHEMWEB-attribute, the recommendation for use in KNX-module is to specify the following form: <gadName>@set:<widgetName,parameter> This avoids overwriting the GET pulldown in FHEMWEB detail page. For details, pls see FHEMWEB-attribute.
    
  
  
• Events
  

  Events are generated for each reading sent or received to/from KNX-Bus unless restricted by event-xxx attributes or modified by eventMap, stateRegex attributes.
  KNX-events have this format:

     <device> <readingName>: <value> # reading event
     <device> <value>                # state event

• DPT - data-point-types
  

  The following dpt are implemented and have to be assigned within the device definition. The values right to the dpt define the valid range of Set-command values and Get-command return values and units.

  1. dpt1 off, on, toggle - see Note 1
  2. dpt1.000 0, 1
  3. dpt1.001 off, on, toggle
  4. dpt1.002 false, true
  5. dpt1.003 disable, enable
  6. dpt1.004 no_ramp, ramp
  7. dpt1.005 no_alarm, alarm
  8. dpt1.006 low, high
  9. dpt1.007 decrease, increase
  10. dpt1.008 up, down
  11. dpt1.009 open, close
  12. dpt1.010 stop, start
  13. dpt1.011 inactive, active
  14. dpt1.012 not_inverted, inverted
  15. dpt1.013 start/stop, ciclically
  16. dpt1.014 fixed, calculated
  17. dpt1.015 no_action, reset
  18. dpt1.016 no_action, acknowledge
  19. dpt1.017 trigger_0, trigger_1
  20. dpt1.018 not_occupied, occupied
  21. dpt1.019 closed, open
  22. dpt1.021 logical_or, logical_and
  23. dpt1.022 scene_A, scene_B
  24. dpt1.023 move_up/down, move_and_step_mode
  25. dpt1.024 day, night
  26. dpt1.100 cooling, heating
  27. dpt2 off, on, forceOff, forceOn
  28. dpt2.000 0,1,2,3
  29. dpt3 -100..+100
  30. dpt3.007 -100..+100 %
  31. dpt3.008 -100..+100 %
  32. dpt4 single ASCII char
  33. dpt4.001 single ASCII char
  34. dpt4.002 single ISO-8859-1 char
  35. dpt5 0..255
  36. dpt5.001 0..100 %
  37. dpt5.003 0..360 °
  38. dpt5.004 0..255 %
  39. dpt5.005 0..255 (decimal factor)
  40. dpt5.006 0..255 (tariff info)
  41. dpt5.010 0..255 p (pulsecount)
  42. dpt6 -128..+127
  43. dpt6.001 -128 %..+127 %
  44. dpt6.010 -128..+127 p (pulsecount)
  45. dpt7 0..65535
  46. dpt7.001 0..65535 p (pulsecount)
  47. dpt7.002 0..65535 ms
  48. dpt7.003 0..655.35 s
  49. dpt7.004 0..6553.5 s
  50. dpt7.005 0..65535 s
  51. dpt7.006 0..65535 min
  52. dpt7.007 0..65535 h
  53. dpt7.011 0..65535 mm
  54. dpt7.012 0..65535 mA
  55. dpt7.013 0..65535 lux
  56. dpt7.600 0..12000 K
  57. dpt8 -32768..32767
  58. dpt8.001 -32768..32767 p (pulsecount)
  59. dpt8.002 -32768..32767 ms
  60. dpt8.003 -327.68..327.67 s
  61. dpt8.004 -3276.8..3276.7 s
  62. dpt8.005 -32768..32767 s
  63. dpt8.006 -32768..32767 min
  64. dpt8.007 -32768..32767 h
  65. dpt8.010 -32768..32767 %
  66. dpt8.011 -32768..32767 °
  67. dpt8.012 -32768..32767 m
  68. dpt9 -671088.64..+670433.28
  69. dpt9.001 -273.15..+670433.28 °C
  70. dpt9.002 -671088.64..+670433.28 K
  71. dpt9.003 -671088.64..+670433.28 K/h
  72. dpt9.004 0..+670433.28 lux
  73. dpt9.005 0..+670433.28 m/s
  74. dpt9.006 0..+670433.28 Pa
  75. dpt9.007 0..+670433.28 %
  76. dpt9.008 0..+670433.28 ppm
  77. dpt9.009 -671088.64..+670433.28 m³/h
  78. dpt9.010 -671088.64..+670433.28 s
  79. dpt9.011 -671088.64..+670433.28 ms
  80. dpt9.020 -671088.64..+670433.28 mV
  81. dpt9.021 -671088.64..+670433.28 mA
  82. dpt9.022 -671088.64..+670433.28 W/m²
  83. dpt9.023 -671088.64..+670433.28 K/%
  84. dpt9.024 -671088.64..+670433.28 kW
  85. dpt9.025 -671088.64..+670433.28 l/h
  86. dpt9.026 -671088.64..+670433.28 l/m²
  87. dpt9.027 -459.6..+670433.28 °F
  88. dpt9.028 0..+670433.28 km/h
  89. dpt9.029 0..+670433.28 g/m³
  90. dpt9.030 0..+670433.28 μg/m³
  91. dpt10.001 HH:MM:SS (Time)
  92. dpt11.001 DD.MM.YYYY (Date)
  93. dpt12 0..+4294967295
  94. dpt12.001 0..+4294967295 p (pulsecount)
  95. dpt12.100 0..+4294967295 s
  96. dpt12.101 0..+4294967295 min
  97. dpt12.102 0..+4294967295 h
  98. dpt13 -2147483648..2147483647
  99. dpt13.001 -2147483648..2147483647 p (pulsecount)
  100. dpt13.002 -2147483648..2147483647 m³/h
  101. dpt13.010 -2147483648..2147483647 Wh
  102. dpt13.011 -2147483648..2147483647 VAh
  103. dpt13.012 -2147483648..2147483647 VARh
  104. dpt13.013 -2147483648..2147483647 kWh
  105. dpt13.014 -2147483648..2147483647 kVAh
  106. dpt13.015 -2147483648..2147483647 kVARh
  107. dpt13.016 -2147483648..2147483647 MWh
  108. dpt13.100 -2147483648..2147483647 s
  109. dpt14 -1.4e-45..+1.7e+38 (IEE754 floatingPoint)
  110. dpt14.000 -1.4e-45..+1.7e+38 m/s² (acceleration)
  111. dpt14.001 -1.4e-45..+1.7e+38 rad/s² (acceleration) angular
  112. dpt14.002 -1.4e-45..+1.7e+38 J/mol (activation energy)
  113. dpt14.003 -1.4e-45..+1.7e+38 1/s (activity - radioactive)
  114. dpt14.004 -1.4e-45..+1.7e+38 mol (amount of substance)
  115. dpt14.005 -1.4e-45..+1.7e+38 - (amplitude)
  116. dpt14.006 -1.4e-45..+1.7e+38 rad (angle radiant)
  117. dpt14.007 -1.4e-45..+1.7e+38 ° (angle degree)
  118. dpt14.008 -1.4e-45..+1.7e+38 Js (angular momentum)
  119. dpt14.009 -1.4e-45..+1.7e+38 rad/s (angular velocity)
  120. dpt14.010 -1.4e-45..+1.7e+38 m² (area)
  121. dpt14.011 -1.4e-45..+1.7e+38 F (capacitance)
  122. dpt14.012 -1.4e-45..+1.7e+38 C/m² (charge density - surface)
  123. dpt14.013 -1.4e-45..+1.7e+38 C/m³ ((charge density - volume)
  124. dpt14.014 -1.4e-45..+1.7e+38 m²/N (compressibility)
  125. dpt14.015 -1.4e-45..+1.7e+38 S (conductance - 1/Ω)
  126. dpt14.016 -1.4e-45..+1.7e+38 S/m (conductivity - electrical)
  127. dpt14.017 -1.4e-45..+1.7e+38 kg/m³ (density)
  128. dpt14.018 -1.4e-45..+1.7e+38 C (electric charge)
  129. dpt14.019 -1.4e-45..+1.7e+38 A (electric current)
  130. dpt14.020 -1.4e-45..+1.7e+38 A/m² (electric current density)
  131. dpt14.021 -1.4e-45..+1.7e+38 C*m (dipole moment)
  132. dpt14.022 -1.4e-45..+1.7e+38 C/m² (electric displacement)
  133. dpt14.023 -1.4e-45..+1.7e+38 V/m (electric field strenght)
  134. dpt14.024 -1.4e-45..+1.7e+38 c (electric flux)
  135. dpt14.025 -1.4e-45..+1.7e+38 C/m² (electric flux density)
  136. dpt14.026 -1.4e-45..+1.7e+38 C/m² (electric polarization)
  137. dpt14.027 -1.4e-45..+1.7e+38 V (electric potential)
  138. dpt14.028 -1.4e-45..+1.7e+38 V (electric potential difference)
  139. dpt14.029 -1.4e-45..+1.7e+38 A/m² (electromagnetic moment)
  140. dpt14.030 -1.4e-45..+1.7e+38 V (electromotive force)
  141. dpt14.031 -1.4e-45..+1.7e+38 J (energy)
  142. dpt14.032 -1.4e-45..+1.7e+38 N (force)
  143. dpt14.033 -1.4e-45..+1.7e+38 Hz (frequency)
  144. dpt14.034 -1.4e-45..+1.7e+38 rad/s (angular frequency)
  145. dpt14.035 -1.4e-45..+1.7e+38 J/K (heat capacity)
  146. dpt14.036 -1.4e-45..+1.7e+38 W (heat flow rate)
  147. dpt14.037 -1.4e-45..+1.7e+38 J (heat quantity)
  148. dpt14.038 -1.4e-45..+1.7e+38 Ω (impedance)
  149. dpt14.039 -1.4e-45..+1.7e+38 m (length)
  150. dpt14.040 -1.4e-45..+1.7e+38 J (light quantity)
  151. dpt14.041 -1.4e-45..+1.7e+38 cd/m² (luminance)
  152. dpt14.042 -1.4e-45..+1.7e+38 lm (luminous flux)
  153. dpt14.043 -1.4e-45..+1.7e+38 cd (luminous intensity)
  154. dpt14.044 -1.4e-45..+1.7e+38 A/m (magnetic field strength)
  155. dpt14.045 -1.4e-45..+1.7e+38 Wb (magnetic flux)
  156. dpt14.046 -1.4e-45..+1.7e+38 T (magnetic flux density)
  157. dpt14.047 -1.4e-45..+1.7e+38 A/m² (magnetic moment)
  158. dpt14.048 -1.4e-45..+1.7e+38 T (magnetic polarization)
  159. dpt14.049 -1.4e-45..+1.7e+38 A/m (magnetization)
  160. dpt14.050 -1.4e-45..+1.7e+38 A (magneto motive force)
  161. dpt14.051 -1.4e-45..+1.7e+38 kg (mass)
  162. dpt14.052 -1.4e-45..+1.7e+38 kg/s (mass flux)
  163. dpt14.053 -1.4e-45..+1.7e+38 N/s (momentum)
  164. dpt14.054 -1.4e-45..+1.7e+38 rad (phase angle radiant)
  165. dpt14.055 -1.4e-45..+1.7e+38 ° (phase angle degrees)
  166. dpt14.056 -1.4e-45..+1.7e+38 W (power)
  167. dpt14.057 -1.4e-45..+1.7e+38 cosφ (power factor)
  168. dpt14.058 -1.4e-45..+1.7e+38 Pa (pressure)
  169. dpt14.059 -1.4e-45..+1.7e+38 Ω (reactance)
  170. dpt14.060 -1.4e-45..+1.7e+38 Ω (resistance)
  171. dpt14.061 -1.4e-45..+1.7e+38 Ω/m (resistivity)
  172. dpt14.062 -1.4e-45..+1.7e+38 H (self inductance)
  173. dpt14.063 -1.4e-45..+1.7e+38 sr (solid angle)
  174. dpt14.064 -1.4e-45..+1.7e+38 W/m² (sound intensity)
  175. dpt14.065 -1.4e-45..+1.7e+38 m/s (speed)
  176. dpt14.066 -1.4e-45..+1.7e+38 N/m² (stress)
  177. dpt14.067 -1.4e-45..+1.7e+38 N/m (surface tension)
  178. dpt14.068 -1.4e-45..+1.7e+38 °C (temperature)
  179. dpt14.069 -1.4e-45..+1.7e+38 K (temperature absolute)
  180. dpt14.070 -1.4e-45..+1.7e+38 K (temperature difference)
  181. dpt14.071 -1.4e-45..+1.7e+38 J/K (thermal capacity)
  182. dpt14.072 -1.4e-45..+1.7e+38 W/m (thermal conductivity)
  183. dpt14.073 -1.4e-45..+1.7e+38 V/K (thermoelectric power)
  184. dpt14.074 -1.4e-45..+1.7e+38 s (time)
  185. dpt14.075 -1.4e-45..+1.7e+38 Nm (torque)
  186. dpt14.076 -1.4e-45..+1.7e+38 m³ (volume)
  187. dpt14.077 -1.4e-45..+1.7e+38 m³/s (volume flux)
  188. dpt14.078 -1.4e-45..+1.7e+38 N (weight)
  189. dpt14.079 -1.4e-45..+1.7e+38 J (work)
  190. dpt14.080 -1.4e-45..+1.7e+38 VA (apparent power)
  191. dpt15.000 Access-code (readonly)
  192. dpt16 14 char ASCII string
  193. dpt16.000 14 char ASCII string
  194. dpt16.001 14 char ISO-8859-1 string (Latin1)
  195. dpt17.001 0..63 (scene nr)
  196. dpt18 1..64 (szene nr)
  197. dpt18.001 [(activate|learn),]1..64
  198. dpt19 DD.MM.YYYY_HH:MM:SS (Date&Time combined)
  199. dpt19.001 DD.MM.YYYY_HH:MM:SS (Date&Time combined)
  200. dpt20.102 HVAC mode
  201. dpt22.101 HVAC RHCC Status (readonly)
  202. dpt217.001 dpt version (readonly)
  203. dpt221 MFGCode.SerialNr (readony)
  204. dpt221.001 MFGCode.SerialNr (readony)
  205. dpt232 RRGGBB RGB-Value (hex)
  206. dpt251 RRGGBBWW RGBW-Value (hex)
  207. dpt251.600 RRGGBBWW RGBW-Value (hex)
  208. dptRAW testing/debugging - see Note 2
  
  Note 1: A toggle cmd is translated to on/off, as there is no direct support for toggle in KNX-devices. See also Attr KNX_toggle.
  Note 2: dptRAW is for testing/debugging only! You can send/receive hex strings of unlimited length (assuming the KNX-HW supports it). No conversion, limit-, plausibility-check is done, the hex values are sent unmodified to the KNX bus.

    syntax: set <device> <gadName> <hex-string>
      Examples of valid / invalid hex-strings:
        00..3f # valid, single byte range x00-x3f
        40..ff # invalid, only values x00-x3f allowed as first byte
        006b   # valid, 1st byte > x3f and multiple bytes have to be prefixed with x00
        001a2b3c4e5f.. # valid, any length as long as even number of hex-digits are used
        00112233445    # invalid, odd number of digits 
  

• KNX Utility Functions
   
  • KNX_scan Function to be called from scripts or FHEM cmdline.
    Selects all KNX-definitions (specified by the argument) that support a "get" from the device. Issues a get <device> <gadName> cmd to each selected device/GAD. The result of the "get" cmd will be stored in the respective readings. The command is supported only if the IO-device is of TYPE KNXIO!
    Useful after a fhem-start to syncronize the readings with the status of the KNX-device.
    The "get" cmds are scheduled asynchronous, with a delay of 200ms between each get. (avoid overloading KNX-bus) If called as perl-function, returns number of "get" cmds issued.

    Examples:
    syntax when used as perl-function (eg. in at, notify,...)
       KNX_scan()                    - scan all possible devices
       KNX_scan('dev-A')             - scan device-A only
       KNX_scan('dev-A,dev-B,dev-C') - scan device-A, device-B, device-C
       KNX_scan('room=Kueche')       - scan all KNX-devices in room Kueche
       KNX_scan('EG_.*')             - scan all KNX-devices where device-names begin with EG_
    syntax when used from FHEM-cmdline
       KNX_scan                      - scan all possible devices
       KNX_scan dev-A                - scan device-A only
       KNX_scan dev-A,dev-B,dev-C    - scan device-A, device-B, device-C
       KNX_scan room=Kueche          - scan all KNX-devices in room Kueche
       KNX_scan EG_.*                - scan all KNX-devices where device-names begin with EG_
    

    Do not use KNX_scan or any 'set or get <KNX-device> ...' in a global:INITIALIZED notify, the IO-device will not be ready for communication at that time!
    A better solution is available:
       defmod initializedKNXIO_nf notify <KNXIO-deviceName>:INITIALIZED set KNX_date now;; set KNX_time now;; KNX_scan;;
    This event is triggered 30 seconds after FHEM init complete and the KNXIO-device status is "connected".
    
    See also help KNXIO how to start KNX_scan by using KNXIO-Attribute enableKNXscan, without using any notify,doif,...

KNXIO

• This is a IO-module for KNX-devices. It provides an interface between FHEM and a KNX-Gateway. The Gateway can be either a KNX-Router/KNX-GW or the KNXD-daemon. FHEM KNX-devices use this module as IO-Device. This Module does NOT support the deprecated EIB-Module!

  A (german) wiki page is avaliable here: FHEM Wiki

• Define

  define <name> KNXIO (H|M|T) <(ip-address|hostname):port> <phy-adress>
  define <name> KNXIO S <UNIX socket-path> <phy-adress>
  define <name> KNXIO X

  Connection Type (mode) (first parameter):
  • H Host Mode - connect to a KNX-router with UDP point-point protocol.
    This is the mode also used by ETS when you specify KNXNET/IP as protocol. You do not need a KNXD installation. The protocol is complex and timing critical! If you have delays in FHEM processing close to 1 sec, the protocol may disconnect. It should recover automatically, however KNX-messages could have been lost!
    The benefit of this protocol: every sent and received msg has to be acknowledged within 1 second by the communication partner, msg delivery is verified!
  • M Multicast mode - connect to KNXD's or KNX-router's multicast-tree.
    This is the mode also used by ETS when you specify KNXNET/IP Routing as protocol. If you have a KNX-router that supports multicast, you do not need a KNXD installation. Default address:port is 224.0.23.12:3671
    Pls. ensure that you have only one GW/KNXD in your LAN that feed the multicast tree!
    If you run FHEM in Docker, note that multicast is not supported in network-mode bridge, but macvlan supports multicast.
  • T TCP mode - uses a TCP-connection to KNXD (default port: 6720).
    This mode is the successor of the TUL-modul, but does not support direct Serial/USB connection to a TPUart-USB Stick. If you want to use a TPUart-USB Stick or any other serial KNX-GW, connect the USB-Stick to KNXD and use modes M,S or T to connect to KNXD.
  • S Socket mode - communicate via KNXD's UNIX-socket on localhost. default Socket-path: /var/run/knx
    Path might be different, depending on knxd-version or -config specification! This mode is tested ok with KNXD version 0.14.30. It does NOT work with ver. 0.10.0!
  • X Special mode - for details see KNXIO-wiki!
  
  ip-address:port or hostname:port
  • Hostname is supported for mode H and T. Port definition is mandatory.
  
  phy-address
  • The physical address is used as the source address of messages sent to KNX network. Valid range: <0-15.0-15.0-255>. 15.15.255 should not be used, is used as mfg-default for "non-configured". This address should be one of the defined client pool-addresses of KNXD (-E parameter) or Router.
  
  All parameters are mandatory. Pls. ensure that you only have one path between your KNX-Installation and FHEM! Do not define multiple KNXIO- or KNXTUL- or TUL-definitions at the same time.

  Examples:
      define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
      define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51 
      define myKNXGW KNXIO S /var/run/knx 0.0.51
      define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
  
  Suggested parameters for KNXD (Version >= 0.14.30), with systemd:
      KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:"                 # knxd acts as multicast client - do NOT use -R !
      KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy"           # connect to a knx-router with ip-addr
      KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW  
    The -e and -E parameters must match the definitions in the KNX-router (set by ETS)!
  

• Set
  
  • disconnect - Stop any communication with KNX-bus.
    Difference to attr <device> disable 1: set cmds are volatile, attributes are saved in config!
  • connect or restart - Start or Stop->5 seconds delay->Start KNX-bus communication.
    
  
  
• Get - No Get command implemented
  
  
• Attributes
  
  • disable - Disable the device if set to 1. No send/receive from bus possible. Delete this attr to enable device again.
  • verbose - increase verbosity of Log-Messages, system-wide default is set in "global" device. For a detailed description see: global-attr verbose
    
  • enableKNXscan - trigger a KNX_scan cmd at fhemstart or at every connected event. A detailed description of the KNX_scan cmd is here!

       0 - never         (default if Attr not defined)
       1 - on fhem start (after <device>:INITIALIZED event)
       2 - on fhem start and on every <device>:connected event

  • KNXIOdebug - Log specific events/conditions independent of verbose Level. - use only on developer advice. Parameters are numeric (1-9), usage may change with every new version!
    
  
  
• Events
  
  • <device>:INITIALIZED - The first <device>:connected event after fhem start is suppressed and replaced (after 30 sec delay) with this event. It can be used (in a notify,doif,...) to syncronize the status of FHEM-KNX-devices with the KNX-Hardware. Do not use the global:INITIALIZED event for this purpose, the KNX-GW is not ready for communication at that time!
    Example:
    defmod KNXinit_nf notify <device>:INITIALIZED get <KNX-device> <gadName> # or even simpler, just use Attribute:
    attr <device> enableKNXscan 1 # to scan all KNX-devices which have this device defined as their IO-device.
  • <device>:connected - triggered if connection to KNX-GW/KNXD is established.
  • <device>:disconnected - triggered if connection to KNX-GW/KNXD failed.

KNXTUL

[EN DE]

The KNXTUL module is the representation of a EIB / KNX connector in FHEM without the need for knxd or similar. KNX instances represent the EIB / KNX devices and will need a KNXTUL as IODev to communicate with the EIB / KNX network.
The TUL module is designed to connect to KNX network via Standard Multicast Address (224.0.23.12) Note: This module requires Perl Module IO::Socket::Multicast which needs to be installed before use. Define
define <name> KNXTUL <physical address>




Example:
define tul KNXTUL 1.1.249

The physical address is used as the source address of telegrams sent to EIB network.

Attributes
• do_not_notify


• dummy


• showtime


• verbose

KNX_scan

[EN DE]

• KNX_scan is a utility funtion to syncronize the status of KNX-hardware with FHEM.
  Syntax:
     KNX_scan <KNX-device> or
   KNX_scan <KNX-devspec>

  A detailed description and examples of the KNX_scan cmd is here.

KODI

[EN DE]

Define
define <name> KODI <ip[:port]> <http|tcp> [<username>] [<password>]

This module allows you to control Kodi and receive events from Kodi. It can also be used to control Plex (see attribute compatibilityMode).

Prerequisites
• Requires XBMC "Frodo" 12.0.
• To use this module you will have to enable JSON-RPC. See here.
• The Perl module JSON is required.
  On Debian/Raspbian: apt-get install libjson-perl
  Via CPAN: cpan install JSON To get it working on a Fritzbox the JSON module has to be installed manually.
To receive events it is necessary to use TCP. The default TCP port is 9090. Username and password are optional for TCP. Be sure to enable JSON-RPC for TCP. See here.

If you just want to control Kodi you can use the HTTP instead of tcp. The username and password are required for HTTP. Be sure to enable JSON-RPC for HTTP. See here.

Example:


define htpc KODI 192.168.0.10 tcp

define htpc KODI 192.168.0.10:9000 tcp # With custom port

define htpc KODI 192.168.0.10 http # Use HTTP instead of TCP - Note: to receive events use TCP!

define htpc KODI 192.168.0.10 http kodi passwd # Use HTTP with credentials - Note: to receive events use TCP!


Remote control:
There is an simple remote control layout for Kodi which contains the most basic buttons. To add the remote control to the webinterface execute the following commands:


define <rc_name> remotecontrol #adds the remote control

set <rc_name> layout KODI_RClayout #sets the layout for the remote control

set <rc_name> makenotify <KODI_device> #links the buttons to the actions


Known issues:
Kodi sometimes creates events twices. For example the Player.OnPlay event is created twice if play a song. Unfortunately this is a issue of Kodi. The fix of this bug is included in future version of Kodi (> 12.2).


Get
• update_channels - fetches all channel groups and all channels from Kodi. The readings "channel_..." and "channelgroup_..." will be filled. Channels will also be automatically updated when the connection is established.
• channelid [<channel_name>] - resolves a channel name and returns its ID. Returns -1 for unknown channels.


Set
set <name> <command> [<parameter>]

This module supports the following commands:
Player related commands:

• play [<all|audio|video|picture>] - starts the playback (might only work if previously paused). The second argument defines which player should be started. By default the active players will be started
• pause [<all|audio|video|picture>] - pauses the playback
• playpause [<all|audio|video|picture>] - toggles between play and pause for the given player
• stop [<all|audio|video|picture>] - stop the playback
• next [<all|audio|video|picture>] - jump to the next track
• prev [<all|audio|video|picture>] - jump to the previous track or the beginning of the current track.
• goto <position> [<audio|video|picture>] - Goes to the in the playlist. has to be a number.
• shuffle [<toggle|on|off>] [<audio|video|picture>] - Enables/Disables shuffle mode. Without furhter parameters the shuffle mode is toggled.
• repeat <one|all|off> [<audio|video|picture>] - Sets the repeat mode.
• open <URI> - Plays the resource located at the URI (can be a url or a file)
• opendir <path> - Plays the content of the directory
• openmovieid <path> - Plays a movie by id
• openepisodeid <path> - Plays an episode by id
• openchannel <path> - Switches to channel by name.
• openchannelid <path> - Switches to channel by id
• addon <addonid> <parametername> <parametervalue> - Executes addon with one Parameter, for example set kodi addon script.json-cec command activate
• seek <hh:mm:ss> - seek to the specified time

Input related commands:

• back - Back-button
• down - Down-button
• up - Up-button
• left - Left-button
• right - Right-button
• home - Home-button
• select - Select-button
• info - Info-button
• showosd - Opens the OSD (On Screen Display)
• showcodec - Shows Codec information
• exec <action> - Execute an input action. All available actions are listed here
• send <text> - Sends <text> as input to Kodi
• jsonraw - Sends raw JSON data to Kodi

Libary related commands:

• videolibrary clean - Removes non-existing files from the video libary
• videolibrary scan - Scan for new video files
• audiolibrary clean - Removes non-existing files from the audio libary
• audiolibrary scan - Scan for new audio files

Application related commands:

• activatewindow <name> - activates the window "name" of the following list:
  • AddonSearch
  • Addons
  • Albums
  • AndroidApps
  • Artists
  • Compilations
  • EventLog
  • FileManager
  • Genres
  • InProgressTvShows
  • MovieActors
  • MovieCountries
  • MovieDirectors
  • MovieGenres
  • MovieInformation
  • MovieSets
  • MovieStudios
  • MovieTags
  • MovieTitles
  • MovieYears
  • Movies
  • MusicAddons
  • MusicFiles
  • MusicPlaylists
  • MusicRoot
  • MusicVideoAlbums
  • MusicVideoArtists
  • MusicVideoDirectors
  • MusicVideoGenres
  • MusicVideoStudios
  • MusicVideoTitles
  • MusicVideoYears
  • MusicVideos
  • ProgramAddons
  • RecentlyAddedAlbums
  • RecentlyAddedEpisodes
  • RecentlyAddedMovies
  • RecentlyAddedMusicVideos
  • RecentlyPlayedAlbums
  • Settings
  • Singles
  • Song
  • SubTitles
  • Top100
  • Top100Albums
  • Top100Songs
  • TvShowActors
  • TvShowGenres
  • TvShowStudios
  • TvShowTitles
  • TvShowYears
  • TvShows
  • VideoAddons
  • VideoFiles
  • VideoPlaylists
  • VideoRoot
  • Years
• mute [<0|1>] - 1 for mute; 0 for unmute; by default the mute status will be toggled
• volume <n> - sets the volume to <n>. <n> must be a number between 0 and 100
• volumeDown <n> - volume down
• volumeUp <n> - volume up
• quit - closes Kodi
• off - depending on the value of the attribute "offMode" Kodi will be closed (see quit) or the system will be shut down, put into hibernation or stand by. Default is quit.

System related commands:

• eject - will eject the optical drive
• shutdown - the Kodi host will be shut down
• suspend - the Kodi host will be put into stand by
• hibernate - the Kodi host will be put into hibernation
• reboot - the Kodi host will be rebooted
• connect - try to connect to the Kodi host immediately


Messaging
To show messages on Kodi (little message PopUp at the bottom right egde of the screen) you can use the following commands:
set <KODI_device> msg <title> <msg> [<duration>] [<icon>]
The default duration of a message is 5000 (5 seconds). The minimum duration is 1500 (1.5 seconds). By default no icon is shown. Kodi provides three different icon: error, info and warning. You can also use an uri to define an icon. Please enclose title and/or message into quotes (" or ') if it consists of multiple words.

Generated Readings/Events:

• audiolibrary - Possible values: cleanfinished, cleanstarted, remove, scanfinished, scanstarted, update
• currentAlbum - album of the current song/musicvideo
• currentArtist - artist of the current song/musicvideo
• currentAudioStream_* - information about currently active audio stream
• currentMedia - file/URL of the media item being played
• currentTitle - title of the current media item
• currentTrack - track of the current song/musicvideo
• episode - episode number
• episodeid - id of the episode in the video library
• fullscreen - indicates if Kodi runs in fullscreen mode (on/off)
• label - label of the current media item
• movieid - id of the movie in the video library
• musicvideoid - id of the musicvideo in the video library
• mute - indicates if Kodi is muted (on/off)
• name - software name (e.g. Kodi)
• originaltitle - original title of the movie being played
• partymode - indicates if Kodi runs in party mode (on/off) (not available for Plex)
• playlist - Possible values: add, clear, remove
• playStatus - Indicates the player status: playing, paused, stopped
• repeat - current repeat mode (one/all/off)
• season - season of the current episode
• showtitle - title of the show being played
• shuffle - indicates if the playback is shuffled (on/off)
• skin - current skin of Kodi
• songid - id of the song in the music library
• system - Possible values: lowbattery, quit, restart, sleep, wake
• time - current position in the playing media item (only updated on play/pause)
• totaltime - total run time of the current media item
• type - type of the media item. Possible values: episode, movie, song, musicvideo, picture, unknown
• version - version of Kodi
• videolibrary - Possible values: cleanfinished, cleanstarted, remove, scanfinished, scanstarted, update
• volume - value between 0 and 100 stating the current volume setting
• year - year of the movie being played
• 3dfile - is a 3D movie according to filename
• sd_<type><n>_<reading> - stream details of the current medium. type can be video, audio or subtitle, n is the stream index (a stream can have multiple audio/video streams)


Remarks on the events


The event playStatus = playing indicates a playback of a media item. Depending on the event type different events are generated:
• type = song generated events are: album, artist, file, title and track
• type = musicvideo generated events are: album, artist, file and title
• type = episode generated events are: episode, file, season, showtitle, and title
• type = movie generated events are: originaltitle, file, title, and year
• type = picture generated events are: file
• type = unknown generated events are: file


Attributes
• compatibilityMode
  This module can also be used to control Plex, since the JSON Api is mostly the same, but there are some differences. If you want to control Plex set the attribute compatibilityMode to plex.
• offMode
  Declares what should be down if the off command is executed. Possible values are quit (closes Kodi), hibernate (puts system into hibernation), suspend (puts system into stand by), and shutdown (shuts down the system). Default value is quit
• updateInterval
  The interval which is used to check if Kodi is still alive (by sending a JSON ping) and also it is used to update current player item.
• disable
  Disables the device. All connections will be closed immediately.
• jsonResponseReading
  When enabled then every received JSON message from Kodi will be saved into the reading jsonResponse so the last received message is always available. Also an event is triggered upon each update.
• pvrEnabled
  Defaults to 1. Disable to indicate that PVR is not available on your Kodi device. Basically meant to avoid error messages when trying to access PVR functions.

Kopp Free Control protocol

[EN DE]

Please take into account: this protocol is under construction. Commands may change

The Kopp Free Control protocol is used by Kopp receivers/actuators and senders. This module is able to send commands to Kopp actuators and receive commands from Kopp transmitters. Currently supports devices: dimmers, switches and blinds. The communication is done via a CUL or compatible device (e.g. CCD...). This devices must be defined before using this protocol.

Assign the Kopp Free Control protocol to a CUL or compatible device
define CUL_0 CUL /dev/ttyAMA0@38400 1234
attr CUL_0 rfmode KOPP_FC
This attribute ("rfmode KOPP_FC") assigns the Kopp protocol to device CUL_0
You may not assign/use a second protocol on this device


Define
define <name> KOPP_FC <Keycode> <Transmittercode1> <Transmittercode2> [<Keycode2>] [<Keycode3>]


• <name>
name is the identifier (name) you plan to assign to your specific device (actuator) as done for any other FHEM device


• <Keycode>
Keycode is a 2 digit hex code (1Byte) which reflects the transmitters key


• <Transmittercode1>
Transmittercode1 is a 4 digit hex code. This code is specific for the transmitter itself.


• <Transmittercode2>
Transmittercode2 is a 2 digit hex code and also specific for the transmitter, but I didn't see any difference while modifying this code. (seems this code don't matter the receiver).
Both codes (Transmittercode1/2) are also used to pair the transmitter with the receivers (remote switch, dimmer, blind..)


• [<Keycode2>]
Keycode2 is an opional 2 digit hex code (1Byte) which reflects a second transmitters key


• [<Keycode3>]
Keycode3 is an opional 2 digit hex code (1Byte) which reflects a third transmitters key
Some receivers like dimmers can be paired with two addional keys, which allow to switch the dimmer directly on or off. That means FHEM will always know the current state, which is not the case in one key mode (toggling between on and off)

Pairing is done by setting the receiver in programming mode by pressing the program button at the receiver
(small buttom, typically inside a hole).
Once the receiver is in programming mode send a command (or two, see dimmer above) from within FHEM to complete the pairing. For more details take a look to the data sheet of the corresponding receiver type.
You are now able to control the receiver from FHEM, the receiver handles FHEM just linke another remote control.

Set
set <name> <value>


• <value>
value is one of:
on
off
dimm
stop


Examples:
    set Dimmer on          # will toggle dimmer device on/off for 1Key remote control, 
                             will switch on for 3 key remote control
    set Dimmer off         # will switch dimmer device off (3 key remote control)
    set Dimmer dimm        # will start dimming process
    set Dimmer stop        # will stop dimming process
   	

Attributes
attr <name> model <value>


• <value>
value is one of:
Switch_8080_01
Switch_8080_01_2Key
Blind_8080_02
Timer_8080_04
Dimm_8011_00
Dimm_8011_00_3Key


Examples

FHEM Config for Dimmer via 1 Key remote control:
define Dimmer KOPP_FC 65 FA5E 02
attr Dimmer IODev CUL_0
attr Dimmer devStateIcon OnOff:toggle:dimm dimm:dim50%:stop stop:on:dimm off:toggle:dimm
attr Dimmer eventMap on:OnOff dimm:dimm stop:stop
attr Dimmer group TestGroup
attr Dimmer model Dimm_8011_00
attr Dimmer room TestRoom
attr Dimmer webCmd OnOff:dimm:stop


FHEM Config for Dimmer via 3 Key remote control:
define SDimmer KOPP_FC 65 FA5E 02 55 75
attr SDimmer IODev CUL_0
attr SDimmer devStateIcon dimm:dim50%:stop stop:on:off on:on:off off:off:on
attr SDimmer group TestGroup
attr SDimmer icon light_pendant_light
attr SDimmer model Dimm_8011_00_3Key
attr SDimmer room TestRoom
attr SDimmer webCmd on:dimm:stop:off



Additional Information you can find in corresponding FHEM Wiki
• Kopp Allgemein

KOSTALPIKO

[EN DE]

Define

define <name> KOSTALPIKO <ip-address> <user> <password>

The module reads the current values from web page of a Kostal Piko inverter.
It can also be used, to capture the values of global radiation, UV-index and sunshine duration
from a special web-site (proplanta) regardless of the existence of the inverter.

Parameters:

• <ip-address> - the ip address of the inverter
• <user> - the login-user for the inverter's web page
• <password> - the login-password for the inverter's web page

Example:

define Kostal KOSTALPIKO 192.168.2.4 pvserver pvwr

Set-Commands

set <name> captureGlobalRadiation

The values for global radiation, UV-index and sunshine duration are immediately polled.

set <name> captureKostalData

All values of the inverter are immediately polled.

Attributes

• readingFnAttributes
• BAEnable - if 1, data from ../BA.fhtml site is captured
• GR.Interval - poll interval for global radiation in seconds
• GR.Link - regionalised link the to the proplanta web page (global radiation, UV-index and sunshine duration)
  (see Wiki for further information)
• delay - poll interval for the values of the inverter in seconds
• delayCounter - delay counter for poll of invert's values beside AC.Power;
  needed for fast acquisition scenarios to limit the log-output.
• disable - if disable=1, the poll of inverter's values is disabled,
  ut not the the poll of proplanta-values

Generated Readings/Events

• AC.Power - the current power, captured only if the internal delayCounter = 0
• AC.Power.Fast - the current power, on each poll cycle; used for fast acquisition scenarios
• Daily.Energie - the current procduced energie of the day
• Daily.Energie.Last - the value of daily energy at 23:00 clock
• Global.Radiation - the value of global radiation (proplanta);useful for determing the expected energy amount of the day
• ModeNum - the current processing state of the inverter (1=off 2=idle 3=active)
• Mode - the german term for the current ModeNum
• Total.Energy - the total produced energie
• generator.1.current - the electrical current at string 1
• generator.2.current - the electrical current at string 2
• generator.3.current - the electrical current at string 3
• generator.1.voltage - the voltage at string 1
• generator.2.voltage - the voltage at string 2
• generator.3.voltage - the voltage at string 3
• output.1.voltage - the voltage at output 1
• output.2.voltage - the voltage at output 2
• output.3.voltage - the voltage at output 3
• output.1.power - the power at output 1
• output.2.power - the power at output 2
• output.3.power - the power at output 3
• sensor.1 - the voltage at analog input 1
• sensor.2 - the voltage at analog input 2
• sensor.3 - the voltage at analog input 3
• sensor.4 - the voltage at analog input 4
• UV.Index - the UV Index (proplanta)
• sunshine.duration - the sunshine duration (proplanta)

Additional Readings/Events, if BAEnable=1

• Battery.CycleCount - count of charge cycles
• Battery.StateOfCharge - State of charge for the battery in percent
• Battery.Voltage - the voltage of the battery
• Battery.ChargeCurrent - the charge current of the battery
• Battery.Temperature - the temperature of the battery
• Power.Solar - the sum of the power produced by the solarinverter
• Power.Battery - the power drawn from the battery
• Power.Net - the power drawn from the main
• Power.Phase1 - the power used on phase L1
• Power.Phase2 - the power used on phase L2
• Power.Phase3 - the power used on phase L3

Additional information

• Discussion in FHEM forum
• Information in FHEM Wiki

KS300

[EN DE]

Fhem can receive the KS300 or KS555 radio messages through the FHZ, WS300 or CUL, so one of them must be defined first.
This module services messages received by the FHZ or CUL.

Define
define <name> KS300 <housecode> [ml/raincounter [wind-factor]]

<housecode> is a four digit hex number, it must be specified foir historic reasons, and it is ignored. The ml/raincounter defaults to 255 ml, and it must be specified if you wish to set the wind factor, which defaults to 1.0.
Examples:
define ks1 KS300 1234


Set
N/A

Get
N/A

Attributes
• ignore
• IODev
• eventMap


• do_not_notify
• showtime
• model (ks300)
• strangeTempDiff DIFFVAL
  If set, the module will only accept temperature values when the difference between the reported temperature and the last recorded value is less than DIFFVAL.
• rainadjustment
  If this attribute is set, fhem automatically considers rain counter resets after a battery change and random counter switches as experienced by some users. Default is 0 (off).

KeyValueProtocol

[EN DE]

A generic module to receive key-value-pairs from an IODevice like JeeLink.
The data source can send any key/value pairs, which will get converted into readings.
The protocol that the sketch must send is: OK VALUES Key1=Value1,Key2=Value2, ...

Define
define <name> KeyValueProtocol <Type> <ID>


Set

Get

Attributes
• Mapping
  The Mapping attribute can optionally be used to translate the Keys.
  The format is: ReceivedKey1=NewKey1,ReceivedKey2=NewKey2, ...
  The Sketch can then send short Keys, which will get translated to long names.
  Example: attr myKVP Mapping T=Temperature,H=Humidity
  If the sketch then sends: OK VALUES T=12,H=70
  you will get the readings Temperature and Humidity with the Values 12 and 70
  

Readings

Depending on the received data

Klafs Sauna control

[EN DE]

The module receives data and sends commands to the Klafs app.
In the current version, the sauna can be turned on and off, and the parameters can be set.

Requirements

The SaunaID must be known. This can be found in the URL directly after logging in to the app (http://sauna-app.klafs.com).
The ID is there with the parameter ?s=xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx.
In addition, the user name and password must be known, as well as the PIN that was defined on the sauna module.

Definition and use

The module is defined without mandatory parameters.
User name, password, refresh interval, saunaID and pin defined on the sauna module are set as attributes.

Definition of the module


define <name> Klafs <Intervall>
attr <name> <saunaid> <xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx>
attr <name> <username> <xxxxxx>
attr <name> <pin> <1234>
attr <name> <interval> <60>

set <name> <password> <secret>

Example of a module definition:


define mySauna Klafs
attr mySauna saunaid ab0c123d-ef4g-5h67-8ij9-k0l12mn34op5
attr mySauna username user01
attr mySauna pin 1234
attr mySauna interval 60

set mySauna password secret

Set


ResetLoginFailures	If the login fails, the Reading LoginFailures is set to 1. This locks the automatic login from this module. Klafs locks the account after 3 failed attempts. So that not automatically 3 wrong logins are made in a row. ResetLoginFailures resets the reading to 0. Before this, you should have successfully logged in to the app or sauna-app.klafs.com or reset the password. Successful login resets the number of failed attempts in the Klafs cloud.
off	Turns off the sauna|sanarium - without parameters.
on	set <name> on without parameters - start with last used values set <name> on Sauna 90 - 3 parameters possible: "Sauna" with temperature [10-100]; Optional time [19:30]. set <name> on Saunarium 65 5 - 4 parameters possible: "Sanarium" with temperature [40-75]; Optional HumidtyLevel [0-10] and time [19:30]. Infrared is not supported because no test environment is available.
Update	Refreshes the readings and performs a login if necessary.


Get


SaunaID	Reads out the available SaunaIDs.
help	Displays the help for the SET commands.


Readings



Mode	Sauna, Sanarium
LoginFailures	Failed login attempts to the app. If the value is set to 1, no login attempts are made by the module. See set <name> ResetLoginFailures
Restzeit	Remaining bathing time. Value from remainingBathingHours and remainingBathingMinutes
antiforgery_date	Date of the antiforgery cookie. This is generated when the program is switched on.
remainingBathingHours	Hour of remaining bath time
remainingBathingMinutes	Minute of remaining bath time
cookieExpire	Logincookie runtime. 2 days
currentHumidity	In sanarium mode. Percentage humidity
currentHumidityStatus	undefined reading
currentTemperature	Temperature in the sauna. 0 When the sauna is off
currentTemperatureStatus	undefined reading
firstname	Defined first name in the app
irSelected	true/false - Currently set operating mode Infrared
isConnected	true/false - Sauna connected to the app
isPoweredOn	true/false - Sauna is on/off
langcloud	Language set in the app
last_errormsg	Last error message. Often that the safety check door contact was not performed. Safety check must be performed with the reed contact on the door
lastname	Defined last name in the app
mail	Defined mail address in the app
sanariumSelected	true/false - Currently set operating mode Sanarium
saunaId	SaunaID defined as an attribute
saunaSelected	true/false - Currently set operating mode Sauna
selectedHour	Defined switch-on time. Here hour
selectedHumLevel	Defined humidity levels in sanarium operation
selectedIrLevel	Defined intensity in infrared mode
selectedIrTemperature	Defined infrotemperature
selectedMinute	Defined switch-on time. Here minute
selectedSanariumTemperature	Defined sanarium temperature
selectedSaunaTemperature	Defined sauna temperature
showBathingHour	true/false - not further defined. true, if sauna is on.
standbytime	Defined standby time in the app.
power	on/off
statusCode	undefined reading
statusMessage	undefined reading
username	Username defined as an attribute

LGTV_IP12

[EN DE]

This module controls LG SmartTV's which were released between 2012 - 2014 via network connection. You are able to switch query it's power state, control the TV channels, open and close apps and send all remote control commands.

For a list of supported models see the compatibility list for LG TV Remote smartphone app.

Define
define <name> LGTV_IP12 <ip-address> [<status_interval>]

define <name> LGTV_IP12 <ip-address> [<off_status_interval>] [<on_status_interval>]

Defining a LGTV_IP12 device will schedule an internal task (interval can be set with optional parameter <status_interval> in seconds, if not set, the value is 30 seconds), which periodically reads the status of the TV (power state, current channel, input, ...) and triggers notify/FileLog commands.

Different status update intervals depending on the power state can be given also. If two intervals are given to the define statement, the first interval statement represents the status update interval in seconds in case the device is off. The second interval statement is used when the device is on. Example:


define TV LGTV_IP12 192.168.0.10

# With custom status interval of 60 seconds
define TV LGTV_IP12 192.168.0.10 60

# With custom "off"-interval of 60 seconds and "on"-interval of 10 seconds
define TV LGTV_IP12 192.168.0.10 60 10


Set
set <name> <command> [<parameter>]

Currently, the following commands are defined.


• channel   -   set the current channel
• channelUp   -   switches to next channel
• channelDown   -   switches to previous channel
• removePairing   -   deletes the pairing with the device
• showPairCode   -   requests the TV to display the pair code on the TV screen. This pair code must be set in the attribute pairingcode
• startApp   -   start a installed app on the TV
• stopApp   -   stops a running app on the TV
• statusRequest   -   requests the current status of the device
• remoteControl up,down,...   -   sends remote control commands


Get
get <name> <reading>

Currently, the get command only returns the reading values. For a specific list of possible values, see section "Generated Readings/Events".




Attributes
• do_not_notify
• readingFnAttributes


• disable
Optional attribute to disable the internal cyclic status update of the TV. Manual status updates via statusRequest command is still possible.

Possible values: 0 => perform cyclic status update, 1 => don't perform cyclic status updates.


• disabledForIntervals HH:MM-HH:MM HH:MM-HH-MM...
Optional attribute to disable the internal cyclic status update of the TV during a specific time interval. The attribute contains a space separated list of HH:MM tupels. If the current time is between any of these time specifications, the cyclic update will be disabled. Instead of HH:MM you can also specify HH or HH:MM:SS.

To specify an interval spawning midnight, you have to specify two intervals, e.g.:

23:00-24:00 00:00-01:00

Default Value is empty (no intervals defined, cyclic update is always active)


• request-timeout
Optional attribute change the response timeout in seconds for all queries to the TV.

Possible values: 1-5 seconds. Default value is 4 seconds.


• pairingcode
This attribute contains the pairing code to authenticate FHEM as trusted controller. The pairing code can be displayed via set command showPairCode


Generated Readings/Events:

• 3D - The status of 3D playback (can be "true" or "false")
• channel - The number of the current channel
• channelName - The name of the current channel
• currentProgram - The name of the running program of the current channel
• input - The current input source (e.g. Antenna, Sattelite, HDMI1, ...)
• inputLabel - The user defined name of the current input source
• mute - Reports the current mute state (can be "on" or "off")
• power - The power status (can be "on" or "off")
• volume - Reports the volume state.

LGTV_WebOS

[EN DE]

This module controls SmartTVs from LG based on WebOS as operation system via network. It offers to swtich the TV channel, start and switch applications, send remote control commands, as well as to query the actual status.



Definition define <name> LGTV_WebOS <IP-Address>

When an LGTV_WebOS-Module is defined, an internal routine is triggered which queries the TV's status every 15s and triggers respective Notify / FileLog Event definitions.
Example:
define TV LGTV_WebOS 192.168.0.10




Set-Commands set <Name> <Command> [<Parameter>]

The following commands are supported in the actual version:
• connect  -  Connects to the TV at the defined address. When triggered the first time, a pairing is conducted
• pairing  -   Sends a pairing request to the TV which needs to be confirmed by the user with remote control
• screenMsg <Text>  -   Displays a message for 3-5s on the TV in the top right corner of the screen
• mute on, off  -  Turns volume to mute. Depending on the audio connection, this needs to be set on the AV Receiver (see volume)
• volume 0-100, Slider -   Sets the volume. Depending on the audio connection, this needs to be set on the AV Receiver (see mute)
• volumeUp  -   Increases the volume by 1
• volumeDown  -   Decreases the volume by 1
• channelUp   -   Switches the channel to the next one
• channelDown   -   Switches the channel to the previous one
• getServiceList  -  Queries the running services on WebOS (in beta phase)
• on - Turns the TV on, depending on type of device. Only working when LAN or Wifi connection remains active during off state.
• off - Turns the TV off, when an active connection is established
• launchApp <Application>  -   Activates an application out of the following list (Maxdome, AmazonVideo, YouTube, Netflix, TV, GooglePlay, Browser, Chili, TVCast, Smartshare, Scheduler, Miracast, TV) 
  Note: TV is an application in LG's terms and not an input connection
• 3D on,off  -  3D Mode is turned on and off. Depending on type of TV there might be different modes (e.g. Side-by-Side, Top-Bottom)
• stop  -   Stop command (depending on application)
• play  -   Play command (depending on application)
• pause  -   Pause command (depending on application)
• rewind  -   Rewind command (depending on application)
• fastForward  -   Fast Forward command (depending on application)
• clearInputList  -   Clears list of Inputs
• input  - Selects the input connection (depending on the actual TV type and connected devices)
  e.g.: extInput_AV-1, extInput_HDMI-1, extInput_HDMI-2, extInput_HDMI-3)




Get-Command get <Name> <Readingname>


Currently, GET reads back the values of the current readings. Please see below for a list of Readings / Generated Events.


Attributes

• disable
Optional attribute to deactivate the recurring status updates. Manual trigger of update is alsways possible.
Valid Values: 0 => recurring status updates, 1 => no recurring status updates.

• channelGuide
Optional attribute to deactivate the recurring TV Guide update. Depending on TV and FHEM host, this causes significant network traffic and / or CPU load
Valid Values: 0 => no recurring TV Guide updates, 1 => recurring TV Guide updates.
• pingPresence
current state of ping presence from TV. create a reading presence with values absent or present.
• keepAliveCheckTime
value in seconds - keepAliveCheck is check read data input from tcp socket and prevented FHEM freeze.
• wakeOnLanMAC
Network MAC Address of the LG TV Networkdevice.
• wakeOnLanBroadcast
Broadcast Address of the Network - wakeOnLanBroadcast <network>.255
• wakeupCmd
Set a command to be executed when turning on an absent device. Can be an FHEM command or Perl command in {}.

LIGHTIFY

[EN DE]

Module to integrate a OSRAM LIGHTIFY gateway into FHEM;.

The actual LIGHTIFY lights are defined as HUEDevice devices.

All newly found devices and groups are autocreated at startup and added to the room LIGHTIFY.

Notes:
• Autocreate only works for the first gateway. Devices on other gateways have to be manualy defined.


Define
define <name> LIGHTIFY <host>

Defines a LIGHTIFY gateway device with address <host>.

Examples:
define gateway LIGHTIFY 10.0.1.100


Get

Set
• on
• off
• goToScene <sceneId>
• setSoftOn <addr> <transitiontime>
• setSoftOff <addr> <transitiontime>
• reconnect
  Closes and reopens the connection to the gateway.
• statusRequest
  Update light status.

Attributes
• disable
• disabledForIntervals

LIRC

[EN DE]

Generate FHEM-events when an LIRC device receives infrared signals.

Note: this module needs the Lirc::Client perl module.

Define
define <name> LIRC <lircrc_file>
Example:

define Lirc LIRC /etc/lirc/lircrc
Note: In the lirc configuration file you have to define each possible event. If you have this configuration

    begin
      prog = fhem
      button = pwr
      config = IrPower
    end

and you press the pwr button the IrPower toggle event occures at fhem.

    define IrPower01 notify Lirc:IrPower set lamp toggle

turns the lamp on and off. If you want a faster reaction to keypresses you have to change the defaultvalue of readytimeout from 5 seconds to e.g. 1 second in fhem.pl

Set
N/A

Get
N/A

Attributes

LUXTRONIK2

[EN DE]

Luxtronik 2.0 and 2.1 is a heating controller from Alpha InnoTec (AIT) used in heat pumps of Alpha InnoTec, Buderus (Logamatic HMC20, HMC20 Z), CTA All-In-One (Aeroplus), Elco, Nibe (AP-AW10), Roth (ThermoAura®, ThermoTerra), Novelan (WPR NET) and Wolf Heiztechnik (BWL/BWS).
It has a built-in Ethernet (RJ45) port, so it can be directly integrated into a local area network (LAN).
The module is reported to work with firmware: V1.51, V1.54C, V1.60, V1.64, V1.69, V1.70, V1.73, V1.77, V1.80, V1.81.
More Info on the particular page of FHEM-Wiki (in German).
 
Define
define <name> LUXTRONIK2 <IP-address[:Port]> [poll-interval]
If the pool interval is omitted, it is set to 300 (seconds). Smallest possible value is 10.
Usually, the port needs not to be defined.
Example: define Heizung LUXTRONIK2 192.168.0.12 600

Set
A firmware check assures before each set operation that a heat pump with untested firmware is not damaged accidentally.
• activeTariff < 0 - 9 >
  Allows the separate measurement of the consumption (doStatistics = 1 or 2) within different tariffs.
  This value must be set at the correct point of time in accordance to the existing or planned tariff by the FHEM command "at".
  0 = without separate tariffs


• INTERVAL <polling interval>
  Polling interval in seconds


• heatingCurveEndPoint <Temperature>
  Sets the heating curve parameter. Adjustable in 0.1 steps.


• heatingCurveOffset <Temperature>
  Sets the heating curve parameter. Adjustable in 0.1 steps.


• heatingSystemCircPumpDeaerate <on | off>
  Switches the heating circuit circulation pump on or off. So, also in summer all (open) heating circuits have the same temperature. So, heat and coolness spread slightly between rooms.
  NOTE! It uses the deaerate function of the controller. So, the pump alternates always 5 minutes on and 5 minutes off.


• hotWaterCircPumpDeaerate <on | off>
  Switches the external circulation pump for the hot water on or off. The circulation prevents a cool down of the hot water in the pipes but increases the heat consumption drastically.
  NOTE! It uses the deaerate function of the controller. So, the pump alternates always 5 minutes on and 5 minutes off.


• ventBOSUPCircPumpDeaerate <on | off>
  Switches the BOSUP circuit circulation pump on or off.
  NOTE! It uses the deaerate function of the controller. So, the pump alternates always 5 minutes on and 5 minutes off.


• hotWaterTemperatureTarget <temperature>
  Target temperature of domestic hot water boiler in °C


• opModeHotWater <Mode>
  Operating Mode of domestic hot water boiler (Auto | Party | Off)


• opModeVentilation <Mode>
  Operating Mode of Ventilation (Auto | Off)


• opModeHeating <Mode>
  Operating Mode of Heating (Auto | Off)


• resetStatistics <statReadings>
  Deletes the selected statistic values all, statBoilerGradientCoolDownMin, statAmbientTemp..., statElectricity..., statHours..., statHeatQ...


• returnTemperatureHyst <Temperature>
  Hysteresis of the returnTemperatureTarget of the heating controller. 0.5 K till 3 K. Adjustable in 0.1 steps.


• returnTemperatureSetBack <Temperature>
  Decreasing or increasing of the returnTemperatureTarget by -5 K till + 5 K. Adjustable in 0.1 steps.


• statusRequest
  Update device information


• synchClockHeatPump
  Synchronizes controller clock with FHEM time. !! This change is lost in case of controller power off!!

Get
• heatingCurveParameter <OutsideTemp1 SetTemp1 OutsideTemp2 SetTemp2>
  Determines based on two points on the heating curve the respective heat curve parameter heatingCurveEndPoint and heatingCurveOffset.
  These parameter can be set via the respective set commands.


• rawData
  Shows a table with all parameter and operational values returned by the controller.
  They can be assigned to device readings via the attributes userHeatpumpParameters und userHeatpumpValues.



Attributes
• allowSetParameter < 0 | 1 >
  The parameters of the heat pump controller can only be changed if this attribute is set to 1.


• autoSynchClock <delay>
  Corrects the clock of the heatpump automatically if a certain delay (10 s - 600 s) against the FHEM time is exceeded. Does a firmware check before.
  (A 'delayDeviceTimeCalc' <= 2 s can be caused by the internal calculation interval of the heat pump controller.)


• compressor2ElectricalPowerWatt
  Electrical power of the 2nd compressor to calculated the COP and estimate electrical consumption (calculations not implemented yet)


• doStatistics < 0 | 1 | 2 >
  1 or 2: Calculates statistic values: statBoilerGradientHeatUp, statBoilerGradientCoolDown, statBoilerGradientCoolDownMin (boiler heat loss)
  1: Builds daily, monthly and yearly statistics for certain readings (average/min/max or cumulated values).
  Logging and visualization of the statistic should be done with readings of type 'statReadingNameLast'.


• heatPumpElectricalPowerWatt
  Electrical power of the heat pump by a flow temperature of 35°C to calculated efficiency factor and estimate electrical consumption


• heatPumpElectricalPowerFactor
  Change of electrical power consumption per 1 K flow temperature difference to 35°C (e.g. 2% per 1 K = 0,02)


• heatRodElectricalPowerWatt
  Electrical power of the heat rods (2nd heat source) to estimate electrical consumption


• ignoreFirmwareCheck < 0 | 1 >
  A firmware check assures before each set operation that a heatpump controller with untested firmware is not damaged accidentally.
  If this attribute is set to 1, the firmware check is ignored and new firmware can be tested for compatibility.


• statusHTML
  If set, a HTML-formatted reading named "floorplanHTML" is created. It can be used with the FLOORPLAN module.
  Currently, if the value of this attribute is not NULL, the corresponding reading consists of the current status of the heat pump and the temperature of the water.


• userHeatpumpParameters <Index [Name][,Index2 [Name2],Index3 [Name3] ...]>
  Allows to continuously read the value of certain controller parameters. The index number of the parameter can be determined with the get command rawData
  In the attribute definition, a name can be written behind the index number separated by a space. The respective parameter value will either be shown with the prefix "userParameter..." or under the given name.
  Multiple indexes are separated by a comma.
  If the readings are not used anymore the can be deleted with the FHEM command deleteReading.


• userHeatpumpValues <Index Name[,Index2 Name2,Index3 Name3 ...]>
  Allows to read out specific operational values. Proceed as with userHeatpumpParameters.


• readingFnAttributes

LaCrosse

[EN DE]

FHEM module for LaCrosse Temperature and Humidity sensors and weather stations like WS 1600 (TX22 sensor).

It can be integrated in to FHEM via a JeeLink as the IODevice.

The JeeNode sketch required for this module can be found in .../contrib/36_LaCrosse-pcaSerial.zip.

Define
define <name> LaCrosse <addr> [corr1...corr2]

addr is a 2 digit hex number to identify the LaCrosse device.
corr1..corr2 are up to 2 numerical correction factors (corr1 for the temperature and corr2 for the humidity), which will be added to the respective value to calibrate the device.

Note: devices are autocreated only if LaCrossePairForSec is active for the JeeLink IODevice device.


Set
• replaceBatteryForSec <sec> [ignore_battery]
  sets the device for <sec> seconds into replace battery mode. the first unknown address that is received will replace the current device address. this can be partly automated with a readings group configured to show the battery state of all LaCrosse devices and a link/command to set replaceBatteryForSec on klick.

Get

Readings
• battery[]
  ok or low
• temperature (°C)
  Notice: see the filterThreshold attribute.
• humidity (%rH)
• Wind speed (m/s), gust (m/s) and direction (degree)
• Rain (mm)

Attributes
• doAverage
  use an average of the last 4 values for temperature and humidity readings
• doDewpoint
  calculate dewpoint
• filterThreshold
  if the difference between the current and previous temperature is greater than filterThreshold degrees the readings for this channel are not updated. the default is 10.
• resolution
  the resolution in 1/10 degree for the temperature reading
• ignore
  1 -> ignore this device.

Logging and autocreate

• If autocreate is not active (not defined or disabled) and LaCrosse is not contained in the ignoreTypes attribute of autocreate then the Unknown device xx, please define it messages will be logged with loglevel 3. In all other cases they will be logged with loglevel 4.
• The autocreateThreshold attribute of the autocreate module (see autocreate) is respected. The default is 2:120, means, that autocreate will create a device for a sensor only, if the sensor was received at least two times within two minutes.

LaCrosseGateway

[EN DE]

For more information about the LaCrosseGateway see here: FHEM wiki

Define
define <name> LaCrosseGateway <device>

USB-connected devices:

<device> specifies the serial port to communicate with the LaCrosseGateway. The name of the serial-device depends on your distribution, under linux it is something like /dev/ttyACM0 or /dev/ttyUSB0.


Network-connected devices:

<device> specifies the network device
Normally this is the IP-address and the port in the form ip:port
Example: 192.168.1.100:81
You must define the port number on the setup page of the LaCrosseGateway and use the same number here.
The default is 81




Set
• raw <data>
  send <data> to the LaCrosseGateway. The possible command can be found in the wiki.


• connect
  tries to (re-)connect to the LaCrosseGateway. It does not reset the LaCrosseGateway but only try to get a connection to it.


• reboot
  Reboots the ESP8266. Works only if we are connected (state is opened or initialized)


• LaCrossePairForSec <sec> [ignore_battery]
  enable autocreate of new LaCrosse sensors for <sec> seconds. If ignore_battery is not given only sensors sending the 'new battery' flag will be created.


• flash
  The LaCrosseGateway needs the right firmware to be able to receive and deliver the sensor data to fhem.
  This provides a way to flash it directly from FHEM.


• nextionUpload
  Requires LaCrosseGateway V1.24 or newer.
  Sends a Nextion firmware file (.tft) to the LaCrosseGateway. The LaCrosseGateway then distributes it to a connected Nextion display.
  You can define the .tft file that shall be uploaded in the tftFile attribute. If this attribute does not exists, it will try to use FHEM/firmware/nextion.tft


Get
---

Attributes
• Clients
  The received data gets distributed to a client (e.g. LaCrosse, EMT7110, ...) that handles the data. This attribute tells, which are the clients, that handle the data. If you add a new module to FHEM, that shall handle data distributed by the LaCrosseGateway module, you must add it to the Clients attribute.


• MatchList
  Can be set to a perl expression that returns a hash that is used as the MatchList


• initCommands
  Space separated list of commands to send for device initialization.


• timeout
  format: <timeout>
  Asks the LaCrosseGateway every timeout seconds if it is still alive. If there is no response it reconnects to the LaCrosseGateway.
  Can be combined with the watchdog attribute. If the watchdog attribute is set, the LaCrosseGateway also will check if it gets a request within watchdog seconds and if not, it will reboot. watchdog must be longer than timeout and does only work in combination with timeout.
  Both should not be too short because the LaCrosseGateway needs enough time to boot before the next check.
  Good values are: timeout 60 and watchdog 300
  This mode needs LaCrosseGateway V1.24 or newer.
  
  Old version (still working):
  format: <timeout, checkInterval>
  Checks every 'checkInterval' seconds if the last data reception is longer than 'timeout' seconds ago.
  If this is the case, a new connect will be tried.


• watchdog
  see timeout attribute.


• disable
  if disabled, it does not try to connect and does not dispatch data


• kvp
  defines how the incoming KVP-data of the LaCrosseGateway is handled
  dispatch: (default) dispatch it to a KVP device
  readings: create readings (e.g. RSSI, ...) in this device
  both: dispatch and create readings


• ownSensors
  defines how the incoming data of the internal LaCrosseGateway sensors is handled
  dispatch: (default) dispatch it to a LaCrosse device
  readings: create readings (e.g. temperature, humidity, ...) in this device
  both: dispatch and create readings


• mode
  USB, WiFi or Cable
  Depending on how the LaCrosseGateway is connected, it must be handled differently (init, ...)


• tftFile
  defines the .tft file that shall be used by the Nextion firmware upload (set nextionUpload)


• filter
  defines a filter (regular expression) that is applied to the incoming data. If the regex matches, the data will be discarded.
  This allows to suppress sensors, for example those of the neighbour.
  The data of different kinds of sensors starts with (where xx is the ID):
  LaCrosse sensor: OK 9 xx
  EnergyCount 3000: OK 22 xx xx
  EMT7110: OK EMT7110 xx xx
  LevelSender: OK LS xx
  Example: set lgw filter ^OK 22 117 196|^OK 9 49
  will filter the LaCrosse sensor with ID "49" and the EC3000 with ID "117 196"

LaMetric2

[EN DE]

LaMetric is a smart clock with retro design. It may be used to display different information and can receive notifications.
A a developer account is required to use this module.
Visit developer.lametric.comfor further information.


Define
define <name> LaMetric2 <ip> <apikey> [<port>]

Please create an accountto receive the API key.
You will find the api key in the account menu My Devices

The attribute port is optional. Port 4343 will be used by default and connection will be encrypted.
Examples:
define lametric LaMetric2 192.168.2.31 a20205cb7eace9c979c27fd55413296b8ac9dafbfb5dae2022a1dc6b77fe9d2d
define lametric LaMetric2 192.168.2.31 a20205cb7eace9c979c27fd55413296b8ac9dafbfb5dae2022a1dc6b77fe9d2d 4343
define lametric LaMetric2 192.168.2.31 a20205cb7eace9c979c27fd55413296b8ac9dafbfb5dae2022a1dc6b77fe9d2d 8080

Set
msg
set <LaMetric2_device> msg <text> [<option1>=<value> <option2>="<value with space in it>" ...]

The following options may be used to adjust message content and notification behavior:

message   - type: text - Your message text. Using this option takes precedence; non-option text content will be discarded.
title     - type: text - This text will be the first part of the notification. It will normally replace the first frame defined as 'icontype' if 'forceicontype' was not explicitly set.
icon     - type: text - Icon for the message frame. Icon can be defined as ID or in binary format. Icon ID looks like <prefix>XXX, where <prefix> is “i” (for static icon) or “a” (for animation). XXX is the number of the icon and can be found at developer.lametric.com/icons
icontype     - type: text - Represents the nature of notification. Defaults to 'info'. +++ [none] no notification icon will be shown. +++ [info] “i” icon will be displayed prior to the notification. Means that notification contains information, no need to take actions on it. +++ [alert] “!!!” 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.
forceicontype    - type: boolean - Will display the icontype before the title frame. Otherwise the title will be the first frame. Defaults to 0.
lifetime - type: text - The time notification lives in queue to be displayed in seconds. If notification stayed in queue for longer than lifetime seconds – it will not be displayed. Defaults to 120.
priority  - type: info,warning,critical - Priority of the message +++ [info] 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. +++ [warning] 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. +++ [critical] 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.
sound     - type: text - Name of the sound to play. See attribute notificationSound for full list.
repeat    - type: integer - Defines the number of times sound must be played. If set to 0 sound will be played until notification is dismissed. Defaults to 1.
cycles - type: integer - The number of times message should be displayed. If cycles is set to 0, notification will stay on the screen until user dismisses it manually at the device.
If cycles is set to a text string, a sticky notification is created that may also be dismissed using 'set msgCancel' command (find its description below). By default it is set to 1.

chart - type: integer-array - Adds a frame to display a chart. Must contain a comma separated list of numbers.

goal - type: float - Add a goal frame to display the status within a measuring scale.
goal* - type: n/a - All other options described for the goal-setter can be used here by adding the prefix 'goal' to it.

metric - type: float - The number to be shown.
metric* - type: n/a - All other options described for the metric-setter can be used here by adding the prefix 'metric' to it.

app - type: text - app_name to push this message to that particular app. Requires matching token parameter (see below).
token - type: text - Private access token to be used when pushing data to an app. Can be retrieved from developer.lametric.com/applications/app/<app_number> of the corresponding app.

Examples:
set lametric msg My first LaMetric message.
set lametric msg My second LaMetric message.\nThis time with two text frames.
set lametric msg Message with own frame icon. icon=i334
set lametric msg "Another LaMetric message in double quotes."
set lametric msg 'Another LaMetric message in single quotes.'
set lametric msg message="LaMetric message using explicit option for text content." This part of the text will be ignored.
set lametric msg This is a message with a title. title="This is a subject"
set lametric msg title="This is a subject, too!" This is another message with a title set at the beginning of the command.

set lametric msg chart=1,2,3,4,5,7 title='Some Data'

set lametric msg goal=97.8765 title='Goal to 100%'
set lametric msg goal=45.886 goalend=50 title='Goal to 50%'
set lametric msg goal=45.886 goalend=50 goaltype=m title='Goal to 50 meters' using FHEM RType auto format and symbol
set lametric msg goal=45.886 goalend=50 goalunit=m title='Goal to 50 meters' using manual unit symbol and format

set lametric msg metric=21.87 title='Temperature' without unit
set lametric msg metric=21.87 metrictype=c title='Temperature' using FHEM RType auto format and symbol
set lametric msg metric=21.87 metricunit='°C' title='Temperature' using manual unit symbol and format

set lametric msg app=MyPrivateFHEMapp token=ASDFGHJKL23456789 Show this message to my app.
set lametric msg app=MyPrivateFHEMapp token=ASDFGHJKL23456789 icon=i334 Show this message to my app and use my icon.
set lametric msg app=MyPrivateFHEMapp token=ASDFGHJKL23456789 Show this message to my app.\nThis is a second frame.
set lametric msg app=MyPrivateFHEMapp token=ASDFGHJKL23456789 title="This is the head frame" This text goes to the 2nd frame.






msgCancel
set <LaMetric2_device> msgCancel '<cancelID>'



set LaMetric21 msgCancel 'cancelID'



Note: Setter will only appear when a notification was sent using the cycles parameter like cycles=<cancelID> while candelID may be any custom string you would like to use for cancellation afterwards.



chart
set <LaMetric2_device> chart <1,2,3,4,5,6> [<option1>=<value> <option2>="<value with space in it>" ...]

Any option from the msg-setter can be used to modify the chart notification.

Examples:
set lametric chart 1,2,3,4,5,7 title='Some Data'




goal
set <LaMetric2_device> goal <number> [<option1>=<value> <option2>="<value with space in it>" ...]

In addition to any option from the msg-setter, the following options may be used to further adjust a goal notification:

start - type: text - The beginning of the measuring scale. Defaults to '0'.
end - type: text - The end of the measuring scale. Defaults to '100'.
unit - type: text - The unit value to be displayed after the number. Defaults to '%'.
type - type: text - Defines this number as a FHEM readings type (RType). Can be either a reading name or an actual RType (e.g. 'c', 'f', 'temperature' or 'temperaturef' will result in '°C' resp. '°F'). The number will be automatically re-formatted based on SI definition. An appropriate frame icon will be set. It may be explicitly overwritten by using the respective option in the message.

Examples:
set lametric goal 97.8765 title='Goal to 100%'
set lametric goal 45.886 end=50 title='Goal to 50%'
set lametric goal 45.886 end=50 type=m title='Goal to 50 meters' using FHEM RType auto format and symbol
set lametric goal 45.886 end=50 unit=m title='Goal to 50 meters' using manual unit symbol and format






metric
set <LaMetric2_device> metric <number> [<option1>=<value> <option2>="<value with space in it>" ...]

In addition to any option from the msg-setter, the following options may be used to further adjust a metric notification:

old - type: text - when set to the old number, a frame icon for higher, lower, or equal will be set automatically.
unit - type: text - The unit value to be displayed after the number. Defaults to ''.
type - type: text - Defines this number as a FHEM readings type (RType). Can be either a reading name or an actual RType (e.g. 'c', 'f', 'temperature' or 'temperaturef' will result in 'xx.x °C' resp. 'xx.x °F'). The number will be automatically re-formatted based on SI definition. The correct unit symbol as well as and an appropriate frame icon will be set. They may be explicitly overwritten by using the respective other options in the message.
lang - type: text - The base language to be used when 'type' is evaluating the number. Defaults to 'en'.
long - type: boolean - When set and used together with 'type', the unit name will be added in text format instead of using the unit symbol. Defaults to '0'.

Examples:
set lametric metric 21.87 title='Temperature' without unit

set lametric metric 21.87 type=c title='Temperature' using FHEM RType auto format and symbol
set lametric metric 21.87 type=temperature title='Temperature' using FHEM RType auto format and symbol
set lametric metric 21.87 unit='°C' title='Temperature' using manual unit symbol and format

set lametric metric 81.76 type=f title='Temperature' using FHEM RType auto format and symbol
set lametric metric 81.76 type=temperaturef title='Temperature' using FHEM RType auto format and symbol
set lametric metric 81.76 unit='°F' title='Temperature' using manual unit symbol and format





app
set <LaMetric2_device> app <app_name> <action_id> [param1=value param2=value]

Some apps can be controlled by specific actions. Those can be controlled by pre-defined actions and might have optional or mandatory parameters as well.
Examples:
set lametric app clock alarm enabled=true time=10:00:00 wake_with_radio=false
set lametric app clock alarm enabled=false

set lametric app clock clockface icon='data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAYAAADED76LAAAAOklEQVQYlWNUVFBgwAeYcEncv//gP04FMEmsCmCSiooKjHAFMEF0SRQTsEnCFcAE0SUZGBgYGAl5EwA+6RhuHb9bggAAAABJRU5ErkJggg=='

set lametric app stopwatch start
set lametric app stopwatch pause
set lametric app stopwatch reset

set lametric app countdown configure duration=1800 start_now=true
set lametric app countdown start
set lametric app countdown pause
set lametric app countdown reset




To send data to a private/shared app, use 'push' as action_id. It will require the access token as parameter so that the device will accept data for that particular app:

token - type: text - Private access token to be used when pushing data to an app. Can be retrieved from developer.lametric.com/applications/app/<app_number> of the corresponding app.

Examples:
set lametric app MyPrivateFHEMapp push token=ASDFGHJKL23456789 Show this message to my app.
set lametric app MyPrivateFHEMapp push token=ASDFGHJKL23456789 icon=i334 Show this message to my app and use my icon.
set lametric app MyPrivateFHEMapp push token=ASDFGHJKL23456789 Show this message to my app.\nThis is a second frame.
set lametric app MyPrivateFHEMapp push token=ASDFGHJKL23456789 title="This is the head frame" This text goes to the 2nd frame.



If you have configured channels for your app and would like to address a specific one, you may add the parameter 'channels' accordingly:
set lametric app MyPrivateFHEMapp push token=ASDFGHJKL23456789 channels=ch1,ch3 Show this message in 2 of 3 channels in my app.




play
set <LaMetric2_device> play

Will switch to the Radio app and start playback.



stop
set <LaMetric2_device> stop

Will stop Radio playback.



channelDown
set <LaMetric2_device> channelDown

When the Radio app is active, it will switch to the previous radio station.



channelUp
set <LaMetric2_device> channelUp

When the Radio app is active, it will switch to the next radio station.



bluetooth
set <LaMetric2_device> bluetooth <on|off>




brightness
set <LaMetric2_device> brightness <1-100>




brightnessMode
set <LaMetric2_device> brightness <auto|manual>



input
set <LaMetric2_device> input <input_name>

Will switch to a specific app. <input_name> may either be a display name, app ID or package ID.



inputDown
set <LaMetric2_device> inputDown

Will switch to the previous app.



inputUp
set <LaMetric2_device> inputUp

Will switch to the next app.



mute
set <LaMetric2_device> mute <on|off>



muteT
set <LaMetric2_device> muteT




on
set <LaMetric2_device> on




off
set <LaMetric2_device> off




power
set <LaMetric2_device> power <on|off>




screensaver
set <LaMetric2_device> screensaver <off|when_dark|time_based> [<begin hh:mm or hh:mm:ss> <end hh:mm or hh:mm:ss>]




statusRequest
set <LaMetric2_device> statusRequest




toggle
set <LaMetric2_device> toggle




volume
set <LaMetric2_device> volume <0-100>




volumeDown
set <LaMetric2_device> volumeDown




volumeUp
set <LaMetric2_device> volumeUp

Get

• N/A

Attributes

• defaultOnStatus
  When the device is turned on, this will be the screensaver status to put it in to. Defaults to 'illumination'.
• defaultScreensaverStartTime
  When FHEM was rebooted, it will not know the last status of the device before the screensaver was enabled. This will be the fallback value for 'start'. Defaults to '00:00'.
• defaultScreensaverEndTime
  When FHEM was rebooted, it will not know the last status of the device before the screensaver was enabled. This will be the fallback value for 'start'. Defaults to '06:00'.
• defaultVolume
  When FHEM was rebooted, it will not know the last status of the device before volume was muted. This will be the fallback value. Defaults to '50'.
• https
  Set this to 0 to disable encrypted connectivity and enforce unsecure connection via port 8080. When a port was set explicitly when defining the device, this attribute controls explicit enable/disable of encryption.
• notificationIcon
  Fallback value for icon when sending text notifications.
• notificationIconType
  Fallback value for icontype when sending text notifications. Defaults to 'info'.
• notificationLifetime
  Fallback value for lifetype when sending text notifications. Defaults to '120'.
• notificationPriority
  Fallback value for priority when sending text notifications. Defaults to 'info'.
• notificationSound
  Fallback value for sound when sending text notifications. Defaults to 'off'.
• notificationChartIconType
  Fallback value for icontype when sending chart notifications. Defaults to 'info'.
• notificationChartLifetime
  Fallback value for lifetype when sending chart notifications. Defaults to '120'.
• notificationChartPriority
  Fallback value for priority when sending chart notifications. Defaults to 'info'.
• notificationChartSound
  Fallback value for sound when sending text notifications. Defaults to 'off'.
• notificationGoalIcon
  Fallback value for icon when sending goal notifications.
• notificationGoalIconType
  Fallback value for icontype when sending goal notifications. Defaults to 'info'.
• notificationGoalLifetime
  Fallback value for lifetime when sending goal notifications. Defaults to '120'.
• notificationGoalPriority
  Fallback value for priority when sending goal notifications. Defaults to 'info'.
• notificationGoalSound
  Fallback value for sound when sending goal notifications. Defaults to 'off'.
• notificationGoalStart
  Fallback value for measuring scale start when sending goal notifications. Defaults to '0'.
• notificationGoalEnd
  Fallback value for measuring scale end when sending goal notifications. Defaults to '100'.
• notificationGoalUnit
  Fallback value for unit when sending goal notifications. Defaults to '%'.
• notificationMetricIcon
  Fallback value for icon when sending metric notifications.
• notificationMetricIconType
  Fallback value for icontype when sending metric notifications. Defaults to 'info'.
• notificationMetricLang
  Default language when evaluating metric notifications. Defaults to 'en'.
• notificationMetricLifetime
  Fallback value for lifetime when sending metric notifications. Defaults to '120'.
• notificationMetricPriority
  Fallback value for priority when sending metric notifications. Defaults to 'info'.
• notificationMetricSound
  Fallback value for sound when sending metric notifications. Defaults to 'off'.
• notificationMetricUnit
  Fallback value for unit when sending metric notifications. Defaults to ''.

Generated events:

• N/A

Level

[EN DE]

FHEM module for Level.

It can be integrated in to FHEM via a JeeLink as the IODevice.

The JeeNode sketch required for this module can be found in .../contrib/36_LaCrosse-LaCrosseITPlusReader.zip. It must be at least version 10.0c

For more information see: http://forum.fhem.de/index.php/topic,23217.msg165163.html#msg165163

Define
define <name> Level <addr>
addr is a 1 digit hex number (0 .. F) to identify the Level device.


Readings
• liters
  Calculated liters based on distanceToBottom, distance and litersPerCm
• temperature
  Measured temperature
• voltage
  Measured battery voltage
• distance
  Measured distance from the sensor to the fluid
• level
  Calculated level based on the distanceToBottom attribute

Attributes
• distanceToBottom
  Distance from the ultra sonic sensor to the bottom of the tank
• litersPerCm
  Liters for each cm level. Only used if the attribute formula is not set
• formula
  Own calculation of the content, e.g for a lying ton
  Get the variabl $level for the current level and must provide the result in $litres
  Example:
  my $tankRadius = 0.6;
  my $tankLength = 2.35;
  my $levelMtr = $level / 100;
  $litres = int((($tankRadius ** 2) * acos(($tankRadius - $levelMtr) / $tankRadius) - ($tankRadius - $levelMtr)
  * sqrt(($tankRadius ** 2) - (($tankRadius - $levelMtr) * ($tankRadius - $levelMtr)))) * $tankLength * 1000 + 0.5);

LightScene

[EN DE]

Allows to store the state of a group of lights and other devices and recall it later. Multiple states for one group can be stored.

Define
define <name> LightScene [<dev1>] [<dev2>] [<dev3>] ...

Examples:
define light_group LightScene Lampe1 Lampe2 Dimmer1
define kino_group LightScene LampeDecke LampeFernseher Fernseher Verstaerker
define Wohnzimmer LightScene Leinwand Beamer TV Leselampe Deckenlampe


The device detail view will show an html overview of the current state of all included devices and all configured scenes with the device states for each. The column heading with the device names is clickable to go to detail view of this device. The first row that displays the current device state is clickable and should react like a click on the device icon in a room overview would. this can be used to interactively configure a new scene and save it with the command menu of the detail view. The first column of the table with the scene names ic clickable to activate the scene.

A weblink with a scene overview that can be included in any room or a floorplan can be created with:
define wlScene weblink htmlCode {LightScene_2html("LightSceneName")}
Set
• all <command>
  execute set <command> for alle devices in this LightScene
• save <scene_name>
  save current state for alle devices in this LightScene to <scene_name>
• scene <scene_name>
  shows scene <scene_name> - all devices are switched to the previously saved state
• nextScene [nowrap]
  activates the next scene in alphabetical order after the current scene or the first if no current scene is set.
• previousScene [nowrap]
  activates the previous scene in alphabetical order before the current scene or the last if no current scene is set.
• set <scene_name> <device> [<cmd>]
  set the saved state of <device> in <scene_name> to <cmd>
• setcmd <scene_name> <device> [<cmd>]
  set command to be executed for <device> in <scene_name> to <cmd>. <cmd> can be any commandline that fhem understands including multiple commands separated by ;;
  • set kino_group setcmd allOff LampeDecke sleep 30 ;; set LampeDecke off
  • set light_group setcmd test Lampe1 sleep 10 ;; set Lampe1 on ;; sleep 5 ;; set Lampe1 off
• clear [<regex>]
  clears all scenes or all scenes matching <regex> from list of saved scenes
• remove <scene_name>
  remove <scene_name> from list of saved scenes
• rename <scene_old_name> <scene_new_name>
  rename <scene_old_name> to <scene_new_name>

Get
• scenes
• scene <scene_name>

Attributes
• async_delay
  If this attribute is defined, unfiltered set commands will not be executed in the clients immediately. Instead, they are added to a queue to be executed later. The set command returns immediately, whereas the clients will be set timer-driven, one at a time. The delay between two timercalls is given by the value of async_delay (in seconds) and may be 0 for fastest possible execution.
• lightSceneParamsToSave
  this attribute can be set on the devices to be included in a scene. it is set to a comma separated list of readings that will be saved. multiple readings separated by : are collated in to a single set command (this has to be supported by the device). each reading can have a perl expression appended with '@' that will be used to alter the $value used for the set command. this can for example be used to strip a trailing % from a dimmer state. this perl expression must not contain spaces,colons or commas.
  in addition to reading names the list can also contain expressions of the form abc -> xyz or get cba -> set uvw to map reading abc to set xyz or get cba to set uvw. the list can be given as a string or as a perl expression enclosed in {} that returns this string.
  attr myReceiver lightSceneParamsToSave volume,channel
attr myHueDevice lightSceneParamsToSave {(Value($DEVICE) eq "off")?"state":"bri : xy"}
attr myDimmer lightSceneParamsToSave state@{if($value=~m/(\d+)/){$1}else{$value}}

• lightSceneRestoreOnlyIfChanged
  this attribute can be set on the lightscene and/or on the individual devices included in a scene. the device settings have precedence over the scene setting.
  1 -> for each device do nothing if current device state is the same as the saved state
  0 -> always set the state even if the current state is the same as the saved state. this is the default
• followDevices
  the LightScene tries to follow the switching state of the devices set its state to the name of the scene that matches.
  1 -> if no match is found state will be unchanged and a nomatch event will be triggered.
  2 -> if no match is found state will be set to unknown. depending on the scene and devices state can toggle multiple times. use a watchdog if you want to handle this.
• showDeviceCurrentState
  show the current state of member devices in weblink
• switchingOrder
  space separated list of <scene>:<deviceList> items that will give a per scene order in which the devices should be switched.
  the devices from <deviceList> will come before all other devices of this LightScene; if the first character of the <deviceList> ist a ! the devices from the list will come after all other devices from this lightScene.
  <scene> and each element of <deviceList> are treated as a regex.
  Example: To switch a master power outlet before every other device at power on and after every device on power off:
  define media LightScene TV,DVD,Amplifier,masterPower
attr media switchingOrder .*On:masterPower,.* allOff:!.*,masterPower
• traversalOrder
  comma separated list of scene names that should be traversed by the prevoiusScene and nextScene commands.
  default not set -> all scenes will be traversed in alphabetical order
• readingFnAttributes

Log2Syslog

[EN DE]

The module sends FHEM systemlog entries and/or FHEM events to an external syslog server or act as an Syslog-Server itself to receive Syslog-messages of other devices which are able to send Syslog.
The syslog protocol has been implemented according the specifications of RFC5424 (IETF), RFC3164 (BSD) and the TLS transport protocol according to RFC5425.

Prerequisits

The additional perl modules "IO::Socket::INET" and "IO::Socket::SSL" (if SSL is used) must be installed on your system.
Install this package from cpan or, on Debian based installations, better by:

sudo apt-get install libio-socket-multicast-perl
sudo apt-get install libio-socket-ssl-perl



Definition and usage

Depending of the intended purpose a Syslog-Server (MODEL Collector) or a Syslog-Client (MODEL Sender) can be defined.
The Collector receives messages in Syslog-format of other Devices and hence generates Events/Readings for further processing. The Sender-Device forwards FHEM Systemlog entries and/or Events to an external Syslog-Server.




The Collector (Syslog-Server)

Definition of a Collector


define <name> Log2Syslog


The Definition don't need any further parameter. In basic setup the Syslog-Server is initialized with Port=1514/UDP and the parsing profil "Automatic". With attribute "parseProfile" another formats (e.g. BSD or IETF) can be selected. The Syslog-Server is immediately ready for use, detect the received messages, try parsing the data according the rules of RFC5424 or RFC3164 and generates FHEM-Events from received Syslog-messages (pls. see Eventmonitor for the parsed data).
If the device cannot detect a valid message format, please use attribute "parseProfile" to select the valid profile.


Example of a Collector:


define SyslogServer Log2Syslog


The generated events are visible in the FHEM-Eventmonitor.

Example of generated Events with attribute parseProfile=IETF:

2018-07-31 17:07:24.382 Log2Syslog SyslogServer HOST: fhem.myds.me || FAC: syslog || SEV: Notice || ID: Prod_event || CONT: USV state: OL
2018-07-31 17:07:24.858 Log2Syslog SyslogServer HOST: fhem.myds.me || FAC: syslog || SEV: Notice || ID: Prod_event || CONT: HMLAN2 loadLvl: low

To separate fields the string "||" is used. The meaning of the fields in the example is:



HOST	the Sender of the dataset
FAC	Facility corresponding to RFC5424
SEV	Severity corresponding to RFC5424
ID	Ident-Tag
CONT	the message part of the received message


The timestamp of generated events is parsed from the Syslog-message. If this information isn't delivered, the current timestamp of the operating system is used.
The reading name in the generated event match the parsed hostname from Syslog-message. If the message don't contain a hostname, the IP-address of the sender is retrieved from the network interface and the hostname is determined if possible. In this case the determined hostname respectively the IP-address is used as Reading in the generated event.
After definition of a Collectors Syslog-messages in IETF-format according to RFC5424 are expected. If the data are not delivered in this record format and can't be parsed, the Reading "state" will contain the message "parse error - see logfile" and the received Syslog-data are printed into the FHEM Logfile in raw-format. The reading "Parse_Err_No" contains the number of parse-errors since module start.
By the attribute "parseProfile" you can try to use another predefined parse-profile or you can create an own parse-profile as well.

To define an own parse function the "parseProfile = ParseFn" has to be set and with attribute "parseFn" a specific parse function has to be provided.
The fields used by the event and their sequential arrangement can be selected from a range with attribute "outputFields". Depending from the used parse-profil all or a subset of the available fields can be selected. Further information about it you can find in description of attribute "parseProfile".

The behavior of the event generation can be adapted by attribute "makeEvent".




The Sender (Syslog-Client)

Definition of a Sender


define <name> Log2Syslog <destination host> [ident:<ident>] [event:<regexp>] [fhem:<regexp>]



<destination host>	host (name or IP-address) where the syslog server is running
[ident:<ident>]	optional program identifier. If not set the device name will be used as default.
[event:<regexp>]	optional regex to filter events for logging
[fhem:<regexp>]	optional regex to filter fhem system log for logging



After definition the new device sends all new appearing fhem systemlog entries and events to the destination host, port=514/UDP format:IETF, immediately without further settings if the regex for "fhem" or "event" is set.
Without setting a regex, no fhem system log entries or events are forwarded.

The verbose level of FHEM system logs are converted into equivalent syslog severity level.
Thurthermore the message text will be scanned for signal terms "warning" and "error" (with case insensitivity). Dependent of it the severity will be set equivalent as well. If a severity is already set by verbose level, it will be overwritten by the level according to the signal term found in the message text.

Lookup table Verbose-Level to Syslog severity level:



verbose-Level	Severity in Syslog
0	Critical
1	Error
2	Warning
3	Notice
4	Informational
5	Debug



Example of a Sender:


define splunklog Log2Syslog fhemtest 192.168.2.49 ident:Test event:.* fhem:.*


All events are forwarded like this exmple of a raw-print of a Splunk Syslog Servers shows:


Aug 18 21:06:46 fhemtest.myds.me 1 2017-08-18T21:06:46 fhemtest.myds.me Test_event 13339 FHEM [version@Log2Syslog version="4.2.0"] : LogDB sql_processing_time: 0.2306
Aug 18 21:06:46 fhemtest.myds.me 1 2017-08-18T21:06:46 fhemtest.myds.me Test_event 13339 FHEM [version@Log2Syslog version="4.2.0"] : LogDB background_processing_time: 0.2397
Aug 18 21:06:45 fhemtest.myds.me 1 2017-08-18T21:06:45 fhemtest.myds.me Test_event 13339 FHEM [version@Log2Syslog version="4.2.0"] : LogDB CacheUsage: 21
Aug 18 21:08:27 fhemtest.myds.me 1 2017-08-18T21:08:27.760 fhemtest.myds.me Test_fhem 13339 FHEM [version@Log2Syslog version="4.2.0"] : 4: CamTER - Informations of camera Terrasse retrieved
Aug 18 21:08:27 fhemtest.myds.me 1 2017-08-18T21:08:27.095 fhemtest.myds.me Test_fhem 13339 FHEM [version@Log2Syslog version="4.2.0"] : 4: CamTER - CAMID already set - ignore get camid
    

The structure of the payload differs dependent of the used logFormat.

logFormat IETF:

"<PRIVAL>IETFVERS TIME MYHOST IDENT PID MID [SD-FIELD] MESSAGE"



PRIVAL	priority value (coded from "facility" and "severity")
IETFVERS	used version of RFC5424 specification
TIME	timestamp according to RFC5424
MYHOST	Internal MYHOST
IDENT	ident-Tag from DEF if set, or else the own device name. The statement will be completed by "_fhem" (FHEM-Log) respectively "_event" (Event-Log).
PID	sequential Payload-ID
MID	fix value "FHEM"
SD-FIELD	contains additional iformation about used module version
MESSAGE	the dataset to transfer


logFormat BSD:

"<PRIVAL>MONTH DAY TIME MYHOST IDENT[PID]: MESSAGE"



PRIVAL	priority value (coded from "facility" and "severity")
MONTH	month according to RFC3164
DAY	day of month according to RFC3164
TIME	timestamp according to RFC3164
MYHOST	Internal MYHOST
TAG	ident-Tag from DEF if set, or else the own device name. The statement will be completed by "_fhem" (FHEM-Log) respectively "_event" (Event-Log).
PID	the message-id (sequence number)
MESSAGE	the dataset to transfer




Set


• reopen
  
  Closes an existing Client/Server-connection and open it again. This command can be helpful in case of e.g. "broken pipe"-errors.


• sendTestMessage [<Message>]
  
  With device type "Sender" a testmessage can be transfered. The format of the message depends on attribute "logFormat" and contains data in BSD- or IETF-format. Alternatively an own <Message> can be set. This message will be sent in im raw-format without any conversion. The attribute "disable = maintenance" determines, that no data except test messages are sent to the receiver.



Get


• certinfo
  
  On a SenderDevice the command shows informations about the server certificate in case a TLS-session was created (Reading "SSL_Version" isn't "n.a.").


• versionNotes [hints | rel | <key>]
  
  Shows realease informations and/or hints about the module. It contains only main release informations for module users.
  If no options are specified, both release informations and hints will be shown. "rel" shows only release informations and "hints" shows only hints. By the <key>-specification only the hint with the specified number is shown.



Attributes


• addTimestamp
  
  The attribute is only usable for device type "Sender". If set, FHEM timestamps will be logged too.
  Default behavior is not log these timestamps, because syslog uses own timestamps.
  Maybe useful if mseclog is activated in FHEM.
  
  Example output (raw) of a Splunk syslog server:
  

  Aug 18 21:26:55 fhemtest.myds.me 1 2017-08-18T21:26:55 fhemtest.myds.me Test_event 13339 FHEM - : 2017-08-18 21:26:55 USV state: OL
  Aug 18 21:26:54 fhemtest.myds.me 1 2017-08-18T21:26:54 fhemtest.myds.me Test_event 13339 FHEM - : 2017-08-18 21:26:54 Bezug state: done
  Aug 18 21:26:54 fhemtest.myds.me 1 2017-08-18T21:26:54 fhemtest.myds.me Test_event 13339 FHEM - : 2017-08-18 21:26:54 recalc_Bezug state: Next: 21:31:59
          



• addStateEvent
  
  The attribute is only usable for device type "Sender". If set, events will be completed with "state" if a state-event appears.
  Default behavior is without getting "state".



• contDelimiter
  
  The attribute is only usable for device type "Sender". You can set an additional character which is straight inserted before the content-field.
  This possibility is useful in some special cases if the receiver need it (e.g. the Synology-Protokollcenter needs the character ":" for proper function).



• disable [1 | 0 | maintenance]
  
  This device will be activated, deactivated respectSeverity set into the maintenance-mode. In maintenance-mode a test message can be sent by the "Sender"-device (pls. see also command "set <name> sendTestMessage").



• exclErrCond <Pattern1,Pattern2,Pattern3,...>
  
  This attribute is only usable for device type "Sender".
  If within an event the text "Error" is identified, this message obtain the severity "Error" automatically. The attribute exclErrCond can contain a list of events separated by comma, whose severity nevertheless has not to be valued as "Error". Commas within the <Pattern> must be escaped by ,, (double comma). The attribute may contain line breaks.
  
  Example

  attr <name> exclErrCond Error: none, 
                          Errorcode: none,
                          Dum.Energy PV: 2853.0,, Error: none,
                          Seek_Error_Rate_,
                          Raw_Read_Error_Rate_,
                          sabotageError:,
          



• logFormat [ BSD | IETF ]
  
  This attribute is only usable for device type "Sender". Set the syslog protocol format.
  Default value is "IETF" if not specified.



• makeEvent [ intern | no | reading ]
  
  The attribute is only usable for device type "Collector". With this attribute the behavior of the event- and reading generation is defined.
  
  

  intern	events are generated by module intern mechanism and only visible in FHEM eventmonitor. Readings are not created.
  no	only readings like "MSG_<hostname>" without event generation are created
  reading	readings like "MSG_<hostname>" are created. Events are created dependent of the "event-on-.*"-attributes




• octetCount
  
  The attribute is only usable for device type "Sender".
  If set, the Syslog Framing is changed from Non-Transparent-Framing (default) to Octet-Framing. The Syslog-Reciver must support Octet-Framing ! For further informations see RFC6587 "Transmission of Syslog Messages over TCP".



• outputFields
  
  The attribute is only usable for device type "Collector". By a sortable list the desired fields of generated events can be selected. The meaningful usable fields are depending on the attribute "parseProfil". Their meaning can be found in the description of attribute "parseProfil". Is "outputFields" not defined, a predefined set of fields for event generation is used.



• parseFn {<Parsefunktion>}
  
  The attribute is only usable for device type "Collector". The provided perl function (has to be set into "{}") will be applied to the received Syslog-message. The following variables are commited to the function. They can be used for programming, processing and for value return. Variables which are provided as blank, are marked as "".
  In case of restrictions the expected format of variables return is specified in "()". Otherwise the variable is usable for free. The function must be enclosed by { }.
  
  

  Variable	Transfer value	expected return format
  $PRIVAL	""	(0 ... 191)
  $FAC	""	(0 ... 23)
  $SEV	""	(0 ... 7)
  $TS	Timestamp	(YYYY-MM-DD hh:mm:ss)
  $HOST	""
  $DATE	""	(YYYY-MM-DD)
  $TIME	""	(hh:mm:ss)
  $ID	""
  $PID	""
  $MID	""
  $SDFIELD	""
  $CONT	""
  $DATA	Raw data of the message	no return evaluation
  $IGNORE	0	(0|1), if $IGNORE==1 the syslog record ignores

  
  The names of the variables corresponding to the field names and their primary meaning denoted in attribute "parseProfile" (explanation of the field data).
  
  
  Example:
  # Source text: '<4> <;4>LAN IP and mask changed to 192.168.2.3 255.255.255.0'
  # Task: The characters '<;4>' are to removed from the CONT-field

  {
  ($PRIVAL,$CONT) = ($DATA =~ /^<(\d{1,3})>\s(.*)$/);
  $CONT = (split(">",$CONT))[1] if($CONT =~ /^<.*>.*$/);
  } 
  




• parseProfile [ Automatic | BSD | IETF | ... | ParseFn | raw ]
  
  Selection of a parse profile. The attribute is only usable for device type "Collector".
  In mode "Automatic" the module attempts to recognize, if the received data are from type "BSD" or "IEFT". If the type is not recognized, the "raw" format is used instead and a warning is generated in the FHEM log.
  
  

  Automatic	try to recognize the BSD or IETF message format and use it for parsing (default)
  BSD	Parsing of messages in BSD-format according to RFC3164
  IETF	Parsing of messages in IETF-format according to RFC5424 (default)
  TPLink-Switch	specific parser profile for TPLink switch messages
  UniFi	specific parser profile for UniFi controller Syslog as well as Netconsole messages
  ParseFn	Usage of an own specific parse function provided by attribute "parseFn"
  raw	no parsing, events are created from the messages as received without conversion

  
  The parsed data are provided in fields. The fields to use for events and their sequence can be defined by attribute "outputFields".
  Dependent from used "parseProfile" the following fields are filled with values and therefor it is meaningful to use only the namend fields by attribute "outputFields". By the "raw"-profil the received data are not converted and the event is created directly.
  
  The meaningful usable fields in attribute "outputFields" depending of the particular profil:
  
  

  BSD	-> PRIVAL,FAC,SEV,TS,HOST,ID,CONT
  IETF	-> PRIVAL,FAC,SEV,TS,HOST,DATE,TIME,ID,PID,MID,SDFIELD,CONT
  ParseFn	-> PRIVAL,FAC,SEV,TS,HOST,DATE,TIME,ID,PID,MID,SDFIELD,CONT
  raw	-> no selection is meaningful, the original message is used for event creation

  
  Explanation of field data:
  
  

  PRIVAL	coded Priority value (coded from "facility" and "severity")
  FAC	decoded Facility
  SEV	decoded Severity of message
  TS	Timestamp containing date and time (YYYY-MM-DD hh:mm:ss)
  HOST	Hostname / Ip-address of the Sender
  DATE	Date (YYYY-MM-DD)
  TIME	Time (hh:mm:ss)
  ID	Device or application what was sending the Syslog-message
  PID	Programm-ID, offen reserved by process name or prozess-ID
  MID	Type of message (arbitrary string)
  SDFIELD	Metadaten about the received Syslog-message
  CONT	Content of the message
  DATA	received raw-data

  
  Note for manual setting:
  The typical record layout of the format "BSD" or "IETF" starts with:
  
  

  <45>Mar 17 20:23:46 ...	-> record start of the BSD message format
  <45>1 2019-03-17T19:13:48 ...	-> record start of the IETF message format




• port <Port>
  
  The used port. For a Sender the default-port is 514. A Collector (Syslog-Server) uses the port 1514 per default.



• protocol [ TCP | UDP ]
  
  Sets the socket protocol which should be used. You can choose UDP or TCP.
  Default value is "UDP" if not specified.



• rateCalcRerun <Zeit in Sekunden>
  
  Rerun cycle for calculation of log transfer rate (Reading "Transfered_logs_per_minute") in seconds (>=60). Default: 60 seconds.



• respectSeverity
  
  Messages are only forwarded (Sender) respectively the receipt considered (Collector), whose severity is included by this attribute. If "respectSeverity" isn't set, messages of all severity is processed.



• sslCertPrefix
  
  Set the prefix for the SSL certificate, default is "certs/server-". Setting this attribute you are able to specify different SSL-certificates for different Log2Syslog devices. See also the TLS attribute.



• ssldebug
  
  Debugging level of SSL messages. The attribute is only usable for device type "Sender".
  
  
  • 0 - No debugging (default).
  • 1 - Print out errors from IO::Socket::SSL and ciphers from Net::SSLeay.
  • 2 - Print also information about call flow from IO::Socket::SSL and progress information from Net::SSLeay.
  • 3 - Print also some data dumps from IO::Socket::SSL and from Net::SSLeay.



• TLS
  
  A client (Sender) establish a secured connection to a Syslog-Server. A Syslog-Server (Collector) provide to establish a secured connection. The protocol will be switched to TCP automatically. Thereby a Collector device can use TLS, a certificate has to be created or available. With following steps a certicate can be created:
  
  1. in the FHEM basis directory create the directory "certs":
  

      sudo mkdir /opt/fhem/certs
      

  2. create the SSL certicate:
  

      cd /opt/fhem/certs
      sudo openssl req -new -x509 -nodes -out server-cert.pem -days 3650 -keyout server-key.pem
      

  3. set file/directory permissions:
  

      sudo chown -R fhem:dialout /opt/fhem/certs
      sudo chmod 644 /opt/fhem/certs/*.pem
      sudo chmod 711 /opt/fhem/certs
      




• timeout
  
  This attribute is only usable for device type "Sender". Timeout für die Verbindung zum Syslog-Server (TCP). Default: 0.5s.



• useParsefilter
  
  If activated, all non-ASCII characters are deleted before parsing the message.



• timeSpec [Local | UTC]
  
  Use of the local or UTC time format in the device. Only received time datagrams that have the specification according to RFC 3339 are converted accordingly. The time specification for data transmission (model Sender) always corresponds to the set time format.
  Default: Local.
  
  
  Examples of supported time specifications
  2019-04-12T23:20:50Z
  2019-12-19T16:39:57-08:00
  2020-01-01T12:00:27+00:20
  2020-04-04T16:33:10+00:00
  2020-04-04T17:15:00+02:00
  



• verbose
  
  Please see global attribute "verbose". To avoid loops, the output of verbose level of the Log2Syslog-Devices will only be reported into the local FHEM Logfile and not forwarded.



• useEOF
  
  Model Sender (protocol TCP):
  After every transmission the TCP-connection will be terminated with signal EOF.
  
  Model Collector:
  No parsing until the sender has send an EOF signal. CRLF is not considered as data separator. If not set, CRLF will be considered as a record separator.
  
  Note:
  If the sender don't use EOF signal, the data parsing is enforced after exceeding a buffer use threshold and the warning "Buffer overrun" is issued in the FHEM Logfile.




Readings



MSG_<Host>	the last successful parsed Syslog-message from <Host>
Parse_Err_LastData	the last record where the set parseProfile could not be applied successfully
Parse_Err_No	the number of parse errors since start
SSL_Algorithm	used SSL algorithm if SSL is enabled and active
SSL_Version	the used TLS-version if encryption is enabled and is active
Transfered_logs_per_minute	the average number of forwarded logs/events per minute

LuftdatenInfo

[EN DE]

LuftdatenInfo is the FHEM module to read particulate matter, temperature and humidity values ​​from the self-assembly particulate matter sensors from Luftdaten.info.
The values ​​can be queried directly from the server or locally.
There is an alternative Firmware to support more sensors.

Prerequisites
The Perl module "JSON" is required.
Under Debian (based) system, this can be installed using "apt-get install libjson-perl".

Define

define <name> LuftdatenInfo remote <SENSORID1> [<SENSORID2> ..]
define <name> LuftdatenInfo local <IP>
define <name> LuftdatenInfo slave <master-name> <sensor1 sensor2 ...>
To query the data from the server, all affected SensorIDs must be specified. The IDs of the SDS01 stands right at http://maps.luftdaten.info/ . The DHT22 SensorID is usually the SDS011 SensorID + 1. While parsing the data the location values from all sensors will be compared and a message will be written into the log if they differ.
For a local query of the data, the IP address or hostname must be specified.
If several similar sensors are used, the duplicate values can be written in another device.

Set

• statusRequest
  Starts a status request.

Get

• sensors
  Lists all senors.

Readings



• airQuality
  1 => good
  2 => moderate
  3 => unhealthy for sensitive groups
  4 => unhealthy
  5 => very unhealthy
  6 => hazardous
  
• altitude
• humidity
  Relative humidity in %
• illuminanceFull
  Illuminace of the full spectrum in lux
• illuminanceIR
  Iilluminace of the IR spectrum in lux
• illuminanceUV
  Iilluminace of the UV spectrum in lux
• illuminanceVisible
  Iilluminace of the visible spectrum in lux
• latitude
• location
  location as "postcode city"
  Only available with remote query.
• longitude
• PM1
  Quantity of particles with a diameter of less than 1 μm in μg/m³
• PM2.5
  Quantity of particles with a diameter of less than 2.5 μm in μg/m³
• PM10
  Quantity of particles with a diameter of less than 10 μm in μg/m³
• pressure
  Pressure in hPa
• pressureNN
  Pressure at sea level in hPa
  Is calculated if pressure and temperature sensor are active and the sensor is not at sea level.
  The height, can be determined by maps or SmartPhone, needs to be specified at the configuration page.
• signal
  WLAN signal strength in dBm
  Only available with local query.
• temperature
  Temperature in °C
• UVIntensity
  UV intensity in W
• UVRisk
  UV risk from 1 to 5

Attributes

• disable 1
  No queries are started.
• disabledForIntervals HH:MM-HH:MM HH:MM-HH-MM ...
• interval <seconds>
  Interval in seconds in which queries are performed.
  The default and minimum value is 300 seconds for remote request and 30 seconds for local requests.
• timeout <seconds>
  Timeout in seconds for the queries.
  The default and minimum value is 5 seconds.

M232

[EN DE]

Define
define <name> M232 <m232-device>

Define a M232 device. You can attach as many M232 devices as you like. A M232 device provides 6 analog inputs (voltage 0..5V with 10 bit resolution) and 8 bidirectional digital ports. The eighth digital port can be used as a 16 bit counter (maximum frequency 3kHz). The M232 device needs to be connected to a 25pin sub-d RS232 serial port. A USB-to-serial converter works fine if no serial port is available.

Examples:
define m232 M232 /dev/ttyUSB2



Set
set <name> stop

Stops the counter.

set <name> start

Resets the counter to zero and starts it.

set <name> octet

Sets the state of all digital ports at once, value is 0..255.

set <name> io0..io7 0|1

Turns digital port 0..7 off or on.


Get
get <name> [an0..an5]

Gets the reading of analog input 0..5 in volts.

get <name> [io0..io7]

Gets the state of digital ports 0..7, result is 0 or 1.

get <name> octet

Gets the state of all digital ports at once, result is 0..255.

get <name> counter

Gets the number of ticks of the counter since the last reset. The counter wraps around from 65,535 to 0 and then stops. See M232Counter for how we care about this.


Attributes
• model (m232)

M232Counter

[EN DE]

Define
define <name> M232Counter [unit [factor [deltaunit [deltafactor]]]]

Define at most one M232Counter for a M232 device. Defining a M232Counter will schedule an internal task, which periodically reads the status of the counter, and triggers notify/filelog commands. unit is the unit name, factor is used to calculate the reading of the counter from the number of ticks. deltaunit is the unit name of the counter differential per second, deltafactor is used to calculate the counter differential per second from the number of ticks per second.

Default values:
• unit: ticks
• factor: 1.0
• deltaunit: ticks per second
• deltafactor: 1.0

Note: the parameters in square brackets are optional. If you wish to specify an optional parameter, all preceding parameters must be specified as well.

Examples:
define counter M232Counter turns
define counter M232Counter kWh 0.0008 kW 2.88 (one tick equals 1/1250th kWh)


Do not forget to start the counter (with set .. start for M232) or to start the counter and set the reading to a specified value (with set ... value for M232Counter).

To avoid issues with the tick count reaching the end point, the device's internal counter is automatically reset to 0 when the tick count is 64,000 or above and the reading basis is adjusted accordingly.


Set
set <name> value <value>

Sets the reading of the counter to the given value. The counter is reset and started and the offset is adjusted to value/unit.

set <name> interval <interval>

Sets the status polling interval in seconds to the given value. The default is 60 seconds.


Get
get <name> status

Gets the reading of the counter multiplied by the factor from the define statement. Wraparounds of the counter are accounted for by an offset (see reading basis in the output of the list statement for the device).


Attributes
• dummy


• model (M232Counter)

M232Voltage

[EN DE]

Define
define <name> M232Voltage [an0..an5] [unit [factor]]

Define as many M232Voltages as you like for a M232 device. Defining a M232Voltage will schedule an internal task, which reads the status of the analog input every minute, and triggers notify/filelog commands. unit is the unit name, factor is used to calibrate the reading of the analog input.

Note: the unit defaults to the string "volts", but it must be specified if you wish to set the factor, which defaults to 1.0.

Example:
define volt M232Voltage an0
define brightness M232Voltage an5 lx 200.0



Set
N/A

Get
get <name> status


Attributes
• dummy


• model (M232Voltage)

MAX

[EN DE]

Devices from the eQ-3 MAX! group.
When heating thermostats show a temperature of zero degrees, they didn't yet send any data to the cube. You can force the device to send data to the cube by physically setting a temperature directly at the device (not through fhem).

Define
define <name> MAX <type> <addr>

Define an MAX device of type <type> and rf address <addr>. The <type> is one of HeatingThermostat, HeatingThermostatPlus, WallMountedThermostat, ShutterContact, PushButton, virtualShutterContact. The <addr> is a 6 digit hex number. You should never need to specify this by yourself, the autocreate module will do it for you.
Exception : virtualShutterContact
It's advisable to set event-on-change-reading, like attr MAX_123456 event-on-change-reading .* because the polling mechanism will otherwise create events every 10 seconds.
Example:
define switch1 MAX PushButton ffc545


Set
• deviceRename <value>
  rename of the device and its logfile
• desiredTemperature auto [<temperature>]
  For devices of type HeatingThermostat only. If <temperature> is omitted, the current temperature according to the week profile is used. If <temperature> is provided, it is used until the next switch point of the week porfile. It maybe one of
  • degree celcius between 4.5 and 30.5 in 0.5 degree steps
  • "on" or "off" set the thermostat to full or no heating, respectively
  • "eco" or "comfort" using the eco/comfort temperature set on the device (just as the right-most physical button on the device itself does)
• desiredTemperature [manual] <value> [until <date>]
  For devices of type HeatingThermostat only. <value> maybe one of
  • degree celcius between 4.5 and 30.5 in 0.5 degree steps
  • "on" or "off" set the thermostat to full or no heating, respectively
  • "eco" or "comfort" using the eco/comfort temperature set on the device (just as the right-most physical button on the device itself does)
  The optional "until" clause, with <data> in format "dd.mm.yyyy HH:MM" (minutes may only be "30" or "00"!), sets the temperature until that date/time. Make sure that the cube/device has a correct system time. If the keepAuto attribute is 1 and the device is currently in auto mode, 'desiredTemperature <value>' behaves as 'desiredTemperature auto <value>'. If the 'manual' keyword is used, the keepAuto attribute is ignored and the device goes into manual mode.
• desiredTemperature boost
  For devices of type HeatingThermostat only. Activates the boost mode, where for boostDuration minutes the valve is opened up boostValveposition percent.
• groupid <id>
  For devices of type HeatingThermostat only. Writes the given group id the device's memory. To sync all devices in one room, set them to the same groupid greater than zero.
• ecoTemperature <value>
  For devices of type HeatingThermostat only. Writes the given eco temperature to the device's memory. It can be activated by pressing the rightmost physical button on the device.
• comfortTemperature <value>
  For devices of type HeatingThermostat only. Writes the given comfort temperature to the device's memory. It can be activated by pressing the rightmost physical button on the device.
• measurementOffset <value>
  For devices of type HeatingThermostat only. Writes the given temperature offset to the device's memory. If the internal temperature sensor is not well calibrated, it may produce a systematic error. Using measurementOffset, this error can be compensated. The reading temperature is equal to the measured temperature at sensor + measurementOffset. Usually, the internally measured temperature is a bit higher than the overall room temperature (due to closeness to the heater), so one uses a small negative offset. Must be between -3.5 and 3.5 degree celsius.
• minimumTemperature <value>
  For devices of type HeatingThermostat only. Writes the given minimum temperature to the device's memory. It confines the temperature that can be manually set on the device.
• maximumTemperature <value>
  For devices of type HeatingThermostat only. Writes the given maximum temperature to the device's memory. It confines the temperature that can be manually set on the device.
• windowOpenTemperature <value>
  For devices of type HeatingThermostat only. Writes the given window open temperature to the device's memory. That is the temperature the heater will temporarily set if an open window is detected. Setting it to 4.5 degree or "off" will turn off reacting on open windows.
• windowOpenDuration <value>
  For devices of type HeatingThermostat only. Writes the given window open duration to the device's memory. That is the duration the heater will temporarily set the window open temperature if an open window is detected by a rapid temperature decrease. (Not used if open window is detected by ShutterControl. Must be between 0 and 60 minutes in multiples of 5.
• decalcification <value>
  For devices of type HeatingThermostat only. Writes the given decalcification time to the device's memory. Value must be of format "Sat 12:00" with minutes being "00". Once per week during that time, the HeatingThermostat will open the valves shortly for decalcification.
• boostDuration <value>
  For devices of type HeatingThermostat only. Writes the given boost duration to the device's memory. Value must be one of 5, 10, 15, 20, 25, 30, 60. It is the duration of the boost function in minutes.
• boostValveposition <value>
  For devices of type HeatingThermostat only. Writes the given boost valveposition to the device's memory. It is the valve position in percent during the boost function.
• maxValveSetting <value>
  For devices of type HeatingThermostat only. Writes the given maximum valveposition to the device's memory. The heating thermostat will not open the valve more than this value (in percent).
• valveOffset <value>
  For devices of type HeatingThermostat only. Writes the given valve offset to the device's memory. The heating thermostat will add this to all computed valvepositions during control.
• factoryReset
  Resets the device to factory values. It has to be paired again afterwards.
  ATTENTION: When using this on a ShutterContact using the MAXLAN backend, the ShutterContact has to be triggered once manually to complete the factoryReset.
• associate <value>
  Associated one device to another. <value> can be the name of MAX device or its 6-digit hex address.
  Associating a ShutterContact to a {Heating,WallMounted}Thermostat makes it send message to that device to automatically lower temperature to windowOpenTemperature while the shutter is opened. The thermostat must be associated to the ShutterContact, too, to accept those messages. !Attention: After sending this associate command to the ShutterContact, you have to press the button on the ShutterContact to wake it up and accept the command. See the log for a message regarding this! Associating HeatingThermostat and WallMountedThermostat makes them sync their desiredTemperature and uses the measured temperature of the WallMountedThermostat for control.
• deassociate <value>
  Removes the association set by associate.
• weekProfile [<day> <temp1>,<until1>,<temp2>,<until2>] [<day> <temp1>,<until1>,<temp2>,<until2>] ...
  Allows setting the week profile. For devices of type HeatingThermostat or WallMountedThermostat only. Example:
  set MAX_12345 weekProfile Fri 24.5,6:00,12,15:00,5 Sat 7,4:30,19,12:55,6
  sets the profile
  Friday: 24.5 °C for 0:00 - 6:00, 12 °C for 6:00 - 15:00, 5 °C for 15:00 - 0:00
Saturday: 7 °C for 0:00 - 4:30, 19 °C for 4:30 - 12:55, 6 °C for 12:55 - 0:00
  while keeping the old profile for all other days.
• saveConfig <name>
  
• restoreReadings <name of saved config>
  
• restoreDevice <name of saved config>
  
• exportWeekprofile <name od weekprofile device>
  

Get
N/A

Attributes
• actCycle <hh:mm> default none (only with CUL_MAX)
  Provides life detection for the device. [hhh: mm] sets the maximum time without a message from this device.
  If no messages are received within this time, the reading activity is set to dead.
  If the device sends again, the reading is reset to alive.
  Important : does not make sense with the ECO Pushbutton,
  as it is the only member of the MAX! family that does not send cyclical status messages !


• CULdev <name> default none (only with CUL_MAX)
  send device when the CUL_MAX device is using a IOgrp (Multi IO)


• DbLog_log_onoff (0|1) log on and off or the real values 30.5 and 4.5


• dummy (0|1) default 0
  sets device to a read-only device


• debug (0|1) default 0
  creates extra readings (only with CUL_MAX)


• dTempCheck (0|1) default 0
  monitors every 5 minutes whether the Reading desiredTemperature corresponds to the target temperature in the current weekprofile.
  The result is a deviation in Reading dTempCheck, i.e. 0 = no deviation


• externalSensor <device:reading> default none
  If there is no wall thermostat in a room but the room temperature is also recorded with an external sensor in FHEM (e.g. LaCrosse)
  the current temperature value can be used to calculate the reading deviation instead of the own reading temperature


• IODev <name>
  MAXLAN or CUL_MAX device name


• keepAuto (0|1) default 0
  If set to 1, it will stay in the auto mode when you set a desiredTemperature while the auto (=weekly program) mode is active.


• scanTemp (0|1) default 0
  used by MaxScanner


• skipDouble (0|1) default 0 (only with CUL_MAX)
  

Generated events:
• desiredTemperature
  Only for HeatingThermostat and WallMountedThermostat
• valveposition
  Only for HeatingThermostat
• battery
• batteryState
• temperature
  The measured temperature (= measured temperature at sensor + measurementOffset), only for HeatingThermostat and WallMountedThermostat

MAXLAN

[EN DE]

The MAXLAN is the fhem module for the eQ-3 MAX! Cube LAN Gateway.

The fhem module makes the MAX! "bus" accessible to fhem, automatically detecting paired MAX! devices. It also represents properties of the MAX! Cube. The other devices are handled by the MAX module, which uses this module as its backend.

Define
define <name> MAXLAN <ip-address>[:port] [<pollintervall> [ondemand]]

port is 62910 by default. (If your Cube listens on port 80, you have to update the firmware with the official MAX! software). If the ip-address is called none, then no device will be opened, so you can experiment without hardware attached.
The optional parameter <pollintervall> defines the time in seconds between each polling of data from the cube.
You may provide the option ondemand forcing the MAXLAN module to tear-down the connection as often as possible thus making the cube usable by other applications or the web portal.

Set
• pairmode [<n>,cancel]
  Sets the cube into pairing mode for <n> seconds (default is 60s ) where it can be paired with other devices (Thermostats, Buttons, etc.). You also have to set the other device into pairing mode manually. (For Thermostats, this is pressing the "Boost" button for 3 seconds, for example). Setting pairmode to "cancel" puts the cube out of pairing mode.
• raw <data>
  Sends the raw <data> to the cube.
• clock
  Sets the internal clock in the cube to the current system time of fhem's machine (uses timezone attribute if set). You can add
  attr ml set-clock-on-init
  to your fhem.cfg to do this automatically on startup.
• factorReset
  Reset the cube to factory defaults.
• reconnect
  FHEM will terminate the current connection to the cube and then reconnect. This allows re-reading the configuration data from the cube, as it is only send after establishing a new connection.

Get
N/A


Attributes
• set-clock-on-init
  (Default: 1). Automatically call "set clock" after connecting to the cube.
• do_not_notify
• dummy
• loglevel
• addvaltrigger
• timezone
  (Default: CET-CEST). Set MAX Cube timezone (requires "set clock" to take effect).
  NB.Cube time and cubeTimeDifference will not change until Cube next connects.
  
  • GMT-BST - (UTC +0, UTC+1)
  • CET-CEST - (UTC +1, UTC+2)
  • EET-EEST - (UTC +2, UTC+3)
  • FET-FEST - (UTC +3)
  • MSK-MSD - (UTC +4)
  The following are settings with no DST (daylight saving time)
  • GMT - (UTC +0)
  • CET - (UTC +1)
  • EET - (UTC +2)

MAX_Temperature

[EN DE]

This module extends the MAX radiator control by additional setting options.
Possibilities:
- Set the temperature for one or more radiator thermostats.
- Set the temperature and time (vacation mode).
- Groups can be defined for this module.
- Individual devices can be added or excluded.
- The layout for the selection fields can be adjusted as required.


Examples:

define MaxTemp MAX_Temperature
define MaxTemp MAX_Temperature T
define MaxTemp MAX_Temperature HT
define MaxTemp MAX_Temperature WT
define MaxTemp MAX_Temperature 123456


Define

define <NAME> MAX_Temperature
Definition of a temperature module for all radiator thermostats and wall thermostats.


define <NAME> MAX_Temperature T
Definition of a temperature module for all radiator thermostats and wall thermostats.


define <NAME> MAX_Temperature HT
Definition of a temperature module only for radiator thermostats.


define <NAME> MAX_Temperature WT
Definition of a temperature module only for wall thermostats.


define <NAME> MAX_Temperature 123456
Definition of a temperature module for a specific thermostat.

Attributes

• Layout
  attr <NAME> Layout <HTML>
  Possibility of layout of the advertisement.
  
  It is possible to define the layout yourself. HTML code is possible. Examples:
  Standard:
  [DEVICE][MODE][TEMP][SEND][DATE][CLOCK][SEND]<br>\n[STATE]
  
  Structure as a table:
  [STATE]<br><table class=\"block wide\"><tr><td>[DEVICE]</td><td>[MODE]</td><td>[DATE]</td><td>[CLOCK]</td><td>[SEND]</td></tr></table>
  
  Without setting the Holiday mode:
  [STATE]<br> [DEVICE][MODE][TEMP][SEND]
  
  Holiday mode setting only:
  [STATE]<br> [DEVICE][TEMP][DATE][CLOCK][SEND]
  
  All entries one below the other:
  [STATE]<br>
  [DEVICE]<br>
  [MODE]<br>
  [TEMP]<br>
  [DATE]<br>
  [CLOCK]<br>
  [SEND]<br>
  
  It is also possible to add Perl code (in curly brackets)
  {ReadingsVal("myDevice","MyReading","Default_Value")}[STATE][DEVICE][MODE][TEMP][SEND][DATE][CLOCK][SEND]
  
  Special entries:
  

  [STATE]	Status Display of readings of the selected MAX device. Standard: Mode: (auto | manual | temporary) keepAuto: (0 | 1) Temp: (current temperature) desiredTemperature: (set temperature) If a group is selected, the name of the group is displayed here.
  [DEVICE]	Selection box or name of the selected MAX device.
  [MODE]	Selection box for the mode (auto | manual).
  [TEMP]	Selection box for the desired temperature.
  [DATE]	Selection box for the date.
  [CLOCK]	Selection box for the time.
  [SEND]	Button to send the new settings.
  [RESET]	Button to reset the settings made.

• maxDay
  attr <NAME> maxDay (1,2,3,4,5,6,7,14,21,28,35)
  Setting how many days are entered in the selection field for the date.
  
• maxHour
  attr <NAME> maxHour (6,12,18,24)
  Setting how many hours are entered in the selection field for the time.
  
• ignoreDevices
  attr <NAME> ignoreDevices <listing>
  List of devices to be ignored by the module.
  Comma as separator.
  Example:
  MyMax_Wohnzimmer,MyMax_Schlafzimmer
  
• addDevices
  attr <NAME> addDevices <listing>
  List of devices to be added to the selection list.
  This means that e.g. Add "structure".
  Comma as separator.
  Example:
  Struc_heating1,Struc_heating2
  
• addDevicesFirst
  attr <NAME> addDevicesFirst (0|1)
  Show the manually added devices first in the list.
  
• addGroups
  attr <NAME> addGroups (Text)
  Create groups.
  Examples:
  Basement:Max_Device1,Max_Device2,Max_Device3 Upstairs:Max_Device4,Max_Device5
Group 1:Max_Device1,Max_Device2,Max_Device3 Group 2:Max_Device4,Max_Device5
  To insert a space in the group name, can be entered  . Example:
  My Group:Device1,Device2
• addGroupsFirst
  attr <NAME> addGroupsFirst (0|1)
  Show the groups first in the list.
  
• DevicesAlias
  attr <NAME> addDevicesAlias <listing>
  Assign an alias for the MAX devices.
  Comma as separator.
  Examples:
  Struc_Radiator1:Radiator below,Struc_Radiator2:Radiator above
  Max-Device1:Radiator bathroom,Max-Device2:Radiator kitchen
  
• ShowMSg
  attr <NAME> ShowMSg (0|1)
  After sending settings, display a success notification in a dialog.
  
• SendButton
  attr <NAME> SendButton (Text)
  Either the name of a symbol or a text. Standard:
  audio_play
  
• ResetButton
  attr <NAME> ResetButton (Text)
  Either the name of a symbol or a text. Standard:
  control_x
  
• createAT
  attr <NAME> createAT (0|1)
  Automatically creates a temporary AT to the device after the time has expired
  to switch back to automatic mode.
  This is usually not necessary
  
• autoAT_room
  attr <NAME> autoAT_room MAX
  The room in which the temporary AT should be created. Default:
  MAX
  

Readings

• Selected_*
  The currently selected values of the selection boxes.
  

MEDIAPORTAL

[EN DE]

Connects to a running MediaPortal instance via the WifiRemote plugin

Example

define wohnzimmer_Mediaportal MEDIAPORTAL 192.168.0.47:8017

Define

define <name> MEDIAPORTAL host[:port]

Define a Mediaportal interface to communicate with a Wifiremote-Plugin of a Mediaportal-System.

host[:port]
The name and port of the Mediaportal-Wifiremote-Plugin. If Port is not given, the default of 8017 will be used.

Set

• Common Tasks
  • connect
    Connects to Mediaportal immediately without waiting for the normal Fhem-Timeout for reconnect (30s).
  • powermode <mode>
    One of (logoff, suspend, hibernate, reboot, shutdown, exit). Sets the powermode, e.g. shutdown, for shutdown the computersystem of the Mediaportal-System.
  • reconnect
    Re-Connects to Mediaportal immediately.
• Control-Commands
  • command <command>
    One of (stop, record, pause, play, rewind, forward, replay, skip, back, info, menu, up, down, left, right, ok, volup, voldown, volmute, chup, chdown, dvdmenu, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, clear, enter, teletext, red, blue, yellow, green, home, basichome, nowplaying, tvguide, tvrecs, dvd, playlists, first, last, fullscreen, subtitles, audiotrack, screenshot). Sends the given command to the player.
  • key <keyvalue>
    Sends the given key to the player.
  • sleep
    Sends the hinernate-signal to Mediaportal. This command is a shortcut for "powermode hibernate"
  • wakeup
    Wakes the Mediaportal-System up (WakeUp-On-LAN).
• Play-Commands
  • playchannel <channelID>
    Plays the channel with the given ID.
  • playfile <fileType> <filePath>
    Plays the given file with the given type. FileType can be one of (audio, video).
  • playlist <command> <param>
    Sends the given playlistcommand with the given parameter. Command can be one of (play, loadlist, loadlist_shuffle, loadfrompath, loadfrompath_shuffle).
  • Volume <volumelevel>
    Sets the Volume to the given value.

Get

• Common Tasks
  • status
    Call for the answer of a status-Message. e.g. Asynchronously retrieves the information of "Title" and "PlayStatus".
  • nowplaying
    Call for the answer of a nowplaying-Message. e.g. Asynchronously retrieves the information of "Duration", "Position" and "File"".

Attributes

• Common
  • disable <value>
    One of (0, 1). With this attribute you can disable the module.
  • generateNowPlayingUpdateEvents <value>
    One of (0, 1). With this value you can disable (or enable) the generation of NowPlayingUpdate-Events. If set, Fhem generates an event per second with the updated time-values for the current playing. Defaults to "0".
  • HeartbeatInterval <interval>
    In seconds. Defines the heartbeat interval in seconds which is used for testing the correct work of the connection to Mediaportal. A value of 0 deactivate the heartbeat-check. Defaults to "15".
  • macaddress <address>
    Sets the MAC-Address for the Player. This is needed for WakeUp-Function. e.g. "90:E6:BA:C2:96:15"
• Authentication
  • authmethod <value>
    One of (none, userpassword, passcode, both). With this value you can set the authentication-mode.
  • password <value>
    With this value you can set the password for authentication.
  • username <value>
    With this value you can set the username for authentication.

MOBILEALERTS

[EN DE]

The MOBILEALERTS is a fhem module for the german MobileAlerts devices and TFA WEATHERHUB devices.

The fhem module represents a MobileAlerts device. The connection is provided by the MOBILELAERTSGW module. Currently supported: MA10100, MA10101, MA10200, MA10230, MA10238, MA10300, MA10650, MA10320PRO, MA10350, MA10410, MA10450, MA10660, MA10700, TFA 30.3312.02, MA10800, WL2000, TFA30.3060.01.IT, MA10120PRO, MA10860, MA10880
Supported but untested: ./.

Define
define <name> MOBILEALERTS <deviceID> <corrTempIn> <corrHumIn> <corrTempOut> <corrHumOut> <corrTemp2> <corrHum2> <corrTemp3> <corrHum3>

deviceID is the sensorcode on the sensor. alternative: deviceID_<ChannelNumber>
corrTempIn optional: correction temperature
corrHumIn optional: correction humidity
corrTempOut optional: correction temperature out / sensor 1
corrHumOut optional: correction humidity out / sensor 1
corrTemp2 optional: correction temperature sensor 2
corrHum2 optional: correction humidity sensor 2
corrTemp3 optional: correction temperature sensor 3
corrHum3 optional: correction humidity sensor 3

Readings
• lastMsg
  The last message received (always for unknown devices, for known devices only if attr lastMsg is set).
• deviceType
  The devicetype.
• lastRcv
  Timestamp of last message.
• actStatus
  Shows 'unknown', 'alive', 'dead', 'switchedOff' depending on attribut actCycle
• txCounter
  Counter of last message.
• batteryState
  State of Battery (low or ok)
• triggered
  1=last message was triggered by a event.
• tempertature, prevTemperature, temperatureIn, temperatureOut, prevTemperatureIn, prevTemperatureOut
  Temperature (depending on device and attribut expert).
• tempertatureString, prevTemperatureString, temperatureInString, temperatureOutString, prevTemperatureInString, prevTemperatureOutString
  Temperature as string (depending on device and attribut expert).
• state
  State of device (short actual reading)
• humidity, prevHumidity, humidityIn, humidityOut, prevHumidityIn, prevHumidityOut
  Humidity (depending on device and attribut expert).
• humidityString, prevHumidityString, humidityInString, humidityOutString, prevHumidityInString, prevHumidityOutString
  Humidity as string (depending on device and attribut expert).
• wetness
  Shows if sensor detects water.
• lastEvent, lastEvent<X> ,lastEventString, lastEvent<X>String
  Time when last event (rain) happend (MA10650 only).
• mmRain, mmRainActHour, mmRainLastHour, mmRainActDay, mmRainYesterday
  Rain since reset of counter, current hour, last hour, current day, yesterday.
• direction, directionInt
  Direction of wind.
• windSpeed, gustSpeed
  Windspeed in m/s.
• airPressure
  Barometric pressure in hPa
• airPressureString
  Barometric pressure as String
• alarm1, alarm2, alarm3, alarm4
  Active Alarms (values: on/off)

Set
• set <name> clear <readings|counters>
  Clears the readings (all) or counters (like mmRain).

Get
N/A


Attributes
• ignore
• readingFnAttributes
• lastMsg
  If value 1 is set, the last received message will be logged as reading even if device is known.
• actCycle <[hhh:mm]|off>
  This value triggers a 'alive' and 'not alive' detection. [hhh:mm] is the maximum silent time for the device. The reading actStatus will show the states: 'unknown', 'alive', 'dead'.
• expert
  Defines how many readings are show (0=only current, 1=previous, 4=all).

MOBILEALERTSGW

[EN DE]

The MOBILEALERTSGW is a fhem module for the german MobileAlerts Gateway and TFA WEATHERHUB.

The fhem module makes simulates as http-proxy to intercept messages from the gateway. In order to use this module you need to configure the gateway to use the fhem-server with the defined port as proxy. You can do so with the command initgateway or by app. It automatically detects devices. The other devices are handled by the MOBILELAERTS module, which uses this module as its backend.

Define
define <name> MOBILEALERTSGW <port>

port is the port where the proxy server listens. The port must be free.

Readings
• Gateways
  List of known gateways
• GW_<Gateway-MAC>_lastSeen
  Time when last message was received from gateway
• GW_<Gateway-MAC>_ip
  IP-Adresse of gateway
• GW_<Gateway-MAC>_serial
  Serialnumber of gateway
• GW_<Gateway-MAC>_proxy
  on, off: setting of proxy (only after get config)
• GW_<Gateway-MAC>_proxyname
  Name/IP of proxy (only after get config)
• GW_<Gateway-MAC>_proxyport
  Port of proxy (only after get config)
• GW_<Gateway-MAC>_config
  Complete configuration as hex-values (only after get config)

Set
• set <name> clear <readings>
  Clears the readings.
• set <name> initgateway <gatewayid>
  Sets the proxy in the gateway to the fhem-server. A reboot of the gateway may be needed in order to take effect.
• set <name> rebootgateway <gatewayid>
  Reboots the gateway.

Get
• get <name> config <IP or gatewayid>
  Gets the config of a gateway or all gateways. IP or gatewayid are optional. If not specified it will search for alle Gateways in the local lan (Broadcast).


Attributes
• forward
  If value 1 is set, the data will be forwarded to the MobileAlerts Server http://www.data199.com/gateway/put .
• allowfrom
  Sets from which hosts (gateways) IPs inputs are accepted. If not set all private IPs are allowed.

MPD

[EN DE]

FHEM module to control a MPD (or Mopidy) like the MPC (MPC = Music Player Command, the command line interface to the Music Player Daemon )
To install a MPD on a Raspberry Pi you will find a lot of documentation at the web e.g. http://www.forum-raspberrypi.de/Thread-tutorial-music-player-daemon-mpd-und-mpc-auf-dem-raspberry-pi in german
FHEM Forum : Modul für MPD ( in german )
Modul requires JSON -> sudo apt-get install libjson-perl
If you are using Mopidy with Spotify support you may also need LWP::UserAgent -> sudo apt-get install libwww-perl

Define

define <name> MPD <IP MPD Server | default localhost> <Port MPD Server | default 6600>
Example:


  define myMPD MPD 192.168.0.99 7000
  

if FHEM and MPD a running on the same device :

  define myMPD MPD
  




Set

set <name> <what>
 
Currently, the following commands are defined.
 
play => like MPC play , start playing song in playlist
clear => like MPC clear , delete MPD playlist
stop => like MPC stop, stops playing
pause => like MPC pause
previous => like MPC previous, play previous song in playlist
next => like MPC next, play next song in playlist
random => like MPC random, toggel on/off
repeat => like MPC repeat, toggel on/off
toggle => toggles from play to stop or from stop/pause to play
updateDb => like MPC update
volume (%) => like MPC volume %, 0 - 100
volumeUp => inc volume ( + attr volumeStep size )
volumeDown => dec volume ( - attr volumeStep size )
playlist (playlistname|songnumber|position) set playlist on MPD Server. If songnumber and/or postion not defined
MPD starts playing with the first song at position 0
playfile (file) => create playlist + add file to playlist + start playing
IdleNow => send Idle command to MPD and wait for events to return
reset => reset MPD Modul
mpdCMD (cmd) => send a command to MPD Server ( MPD Command Ref )
mute => on,off,toggle
seekcur (time) => Format: [[hh:]mm:]ss. Not before MPD version 0.20.
forward => jump forward in the current track as far as defined in the seekStep Attribute, default 7%
rewind => jump backwards in the current track, as far as defined in the seekStep Attribute, default 7%
channel (no) => loads the playlist with the given number
channelUp => loads the next playlist
channelDown => loads the previous playlist
save_bookmark => saves the current state of the playlist (track number and position inside the track) for the currently loaded playlist This will only work if the playlist was loaded through the module and if the attribute bookmarkDir is set. (not on radio streams !)
load_bookmark => resumes the previously saved state of the currently loaded playlist and jumps to the associated tracknumber and position inside the track




Get

get <name> <what>
 
Currently, the following commands are defined.
music => list all MPD music files in MPD databse
playlists => list all MPD playlist in MPD databse
playlistsinfo => show current playlist informations
webrc => HTML output for a simple Remote Control on FHEM webpage e.g :.


       define <name> weblink htmlCode {fhem("get <name> webrc", 1)}
       attr <name> room MPD
    

statusRequest => get MPD status
currentsong => get infos from current song in playlist
outputs => get name,id,status about all MPD output devices in /etc/mpd.conf
bookmarks => list all stored bookmarks




Attributes

• password , if password in mpd.conf is set
• loadMusic 1|0 => load titles from MPD database at startup (not supported by modipy, no longer recommended for activation!)
• loadPlaylists 1|0 => load playlist names from MPD database at startup
• volumeStep 1|2|5|10 => Step size for Volume +/- (default 5)
• titleSplit 1|0 => split title to artist and title if no artist is given in songinfo (e.g. radio-stream default 1)
• timeout (default 1) => timeout in seconds for TCP connection timeout
• waits (default 60) => if idle process ends with error, seconds to wait
• stateMusic 1|0 => show Music DropDown box in web frontend
• statePlaylists 1|0 => show Playlists DropDown box in web frontend
• player mpd|mopidy|forked-daapd => which player is controlled by the module
• Cover Art functions from Last.fm :
• image_size -1|0|1|2|3 (default -1 = don't use artist images and album cover from Last.fm)
  Last.fm is using diffrent image sizes :
  0 = 32x32 , 1 = 64x64 , 2 = 174x174 , 3 = 300x300
• artist_content 0|1 => store artist informations in Reading artist_content
• artist_summary 0|1 => store more artist informations in Reading artist_summary
  Example with readingsGroup :
  

         define rg_artist readingsGroup <MPD name>:artist,artist_image_html,artist_summary
        attr rg_artist room MPD
       

• cache (default lfm => /fhem/www/lfm) store artist image and album cover in a local directory
• unknown_artist_image => show this image if no other image is avalible (default : /fhem/icons/1px-spacer)
• bookmarkDir => set a writeable directory here to enable saving and restoring of playlist states using the set bookmark and get bookmark commands
• autoBookmark => set this to 1 to enable automatic loading and saving of playlist states whenever the playlist is changed using this module
• seekStep => set this to define how far the forward and rewind commands jump in the current track. Defaults to 7 if not set
• seekStepSmall (default 1) => set this on top of seekStep to define a smaller step size, if the current playing position is below seekStepThreshold percent. This is useful to skip intro music, e.g. in radio plays or audiobooks.
• seekStepSmallThreshold (default 0) => used to define when seekStep or seekStepSmall is applied. Defaults to 0. If set e.g. to 10, then during the first 10% of a track, forward and rewind are using the seekStepSmall value.
• no_playlistcollection (default 0) => if set to 1 , dont create reading playlistcollection



Readings

all MPD internal values
artist_image : (if using Last.fm)
artist_image_html : (if using Last.fm)
album_image : (if using Last.fm)
album_image_html : (if using Last.fm)
artist_content : (if using Last.fm)
artist_summary : (if using Last.fm)
currentTrackProvider : Radio / Bibliothek
playlistinfo : (TabletUI Medialist)
playlistcollection : (TabletUI)
playlistname : (TabletUI) current playlist name
playlist_num : current playlist number
playlist_json : (Medialist Modul)
rawTitle : Title information without changes from the modul

MQTT

connects fhem to mqtt.

A single MQTT device can serve multiple MQTT_DEVICE, MQTT_GENERIC_BRIDGE clients and (outdated) MQTT_BRIDGE clients.
Each MQTT_DEVICE acts as a bridge in between an fhem-device and mqtt.
Note: this module is based on Net::MQTT which needs to be installed from CPAN first.

Define

define <name> MQTT <ip:port> [<username>] [<password>]

Specifies the MQTT device.

Set

• set <name> connect
  (re-)connects the MQTT-device to the mqtt-broker

• set <name> disconnect
  disconnects the MQTT-device from the mqtt-broker

• set <name> publish [qos:?] [retain:?] <topic> <message>
  sends message to the specified topic

Attributes

• keep-alive
  sets the keep-alive time (in seconds).

• attr <name> last-will [qos:?] [retain:?] <topic> <message>
  Support for MQTT feature "last will"

  example:
  attr mqtt last-will /fhem/status crashed

• attr <name> client-id client id
  redefines client id

  example:
  attr mqtt client-id fhem1234567

• on-connect, on-disconnect
  attr <name> on-connect {Perl-expression} <topic> <message>
  Publish the specified message to a topic at connect / disconnect (counterpart to lastwill) and / or evaluation of Perl expression
  If a Perl expression is provided, the message is sent only if expression returns true (for example, 1) or undef.
  The following variables are passed to the expression at evaluation: $hash, $name, $qos, $retain, $topic, $message.

  examples:
  attr mqtt on-connect /topic/status connected
attr mqtt on-connect {Log3("abc",1,"on-connect")} /fhem/status connected

• on-timeout
  attr <name> on-timeout {Perl-expression} evaluate the given Perl expression on timeout
  

MQTT2_CLIENT

MQTT2_CLIENT is a cleanroom implementation of an MQTT client (which connects to an external server, like mosquitto) using no perl libraries. It serves as an IODev to MQTT2_DEVICES.

Define
define <name> MQTT2_CLIENT <host>:<port>

Connect to the server on <host> and <port>. <port> 1883 is default for mosquitto.
Notes:

• only QOS 0 and 1 is implemented

Set
• publish -r topic value
  publish a message, -r denotes setting the retain flag.


• password <password> value
  set the password, which is stored in the FHEM/FhemUtils/uniqueID file. If the argument is empty, the password will be deleted.


• connect
  disconnect
  manually connect or disconnect to the MQTT server. Needed for some strange embedded server.

Get
N/A

Attributes
• autocreate [no|simple|complex]
  if set to simple/complex, at least one MQTT2_DEVICE will be created, and its readingsList will be expanded upon reception of published messages. Note: this is slightly different from MQTT2_SERVER, where each connection has its own clientId. This parameter is sadly not transferred via the MQTT protocol, so the clientId of this MQTT2_CLIENT instance will be used.
  With simple the one-argument version of json2nameValue is added: json2nameValue($EVENT), with complex the full version: json2nameValue($EVENT, 'SENSOR_', $JSONMAP). Which one is better depends on the attached devices and on the personal taste, and it is only relevant for json payload. For non-json payload there is no difference between simple and complex.
  Default is no, as in absence of an MQTT2_DEVICE with a bridgeRegexp attribute it is not really useful.


• binaryTopicRegexp <regular-expression>
  this attribute is only relevant, if the global attribute "encoding unicode" is set.
  In this case the MQTT payload is automatically assumed to be UTF-8, which may cause conversion-problems if the payload is binary. This conversion wont take place, if the topic matches the regular expression specified. Note: as is the case with other modules, ^ and $ is added to the regular expression.


• clientId <name>
  set the MQTT clientId. If not set, the name of the MQTT2_CLIENT instance is used, after deleting everything outside 0-9a-zA-Z


• clientOrder [MQTT2_DEVICE] [MQTT_GENERIC_BRIDGE]
  set the notification order for client modules. This is relevant when autocreate is active, and the default order (MQTT2_DEVICE MQTT_GENERIC_BRIDGE) is not adequate. Note: Changing the attribute affects _all_ MQTT2_CLIENT instances.


• connectFn {...}
  if set, do not connect immediately, but evaluate the argument, which in turn has to call the connect function via fhem("set NAME connect") or MQTT2_CLIENT_connect(...).
  Needed by AWS-IOT connect with custom auth.


• connectTimeout <seconds>
  change the HTTP connect timeout, default is 4 seconds. This seems to be necessary for some MQTT servers in robotic vacuum cleaners.


• maxFailedConnects <number>
  maximum number of failed connections. Useful when experimenting with a public server, where repeatedly failing connection attempts lead to temporary suspension of the account. The counter is increased before the TCP connection is established, and reset after the MQTT CONNACK message or by the set connect command.


• disable
  disable the connection to the server.


• disabledForIntervals
  disable sending or dispatching of messages but not the connection to the server.


• disconnectAfter <seconds>
  if set, the connection will be closed after <seconds> of inactivity, and will be automatically reopened when sending a command.


• header
  a list of space separated tuples of key:value, used to set the HTTP header when MQTT is used over websocket.


• ignoreRegexp
  if $topic:$message matches ignoreRegexp, then it will be silently ignored. For general purpose servers, it is a good idea to set it e.g. to
  homeassistant/[^:"]+/config|tasmota/discovery/[^/:]+/(config|sensors)
  and also include the topics used to send commands towards your MQTT clients.


• lwt <topic> <message>
  set the LWT (last will and testament) topic and message, default is empty.


• keepaliveTimeout <seconds;>
  number of seconds for sending keepalive messages, 0 disables it. The broker will disconnect, if there were no messages for 1.5 * keepaliveTimeout seconds.


• lwtRetain
  if set, the lwt retain flag is set


• mqttVersion 3.1,3.1.1
  set the MQTT protocol version in the CONNECT header, default is 3.1


• nextOpenDelay <sec>
  if the server is unavailable or after it terminates the connection, MQTT2_CLIENT tries to reconnect every "nextOpenDelay" seconds. The default is 10, but this is too short in some cases, especially if a failed reconnect is problematic (see maxFailedConnects).


• msgAfterConnect [-r] topic message
  publish the topic after each connect or reconnect.
  If the optional -r is specified, then the publish sets the retain flag.


• execAfterConnect FHEM-command
  FHEM-command is executed after connect.


• msgBeforeDisconnect [-r] topic message
  publish the topic bofore each disconnect.
  If the optional -r is specified, then the publish sets the retain flag.


• qosMaxQueueLength <number>
  if set to a nonzero value, messages are published with QoS=1, and are kept in a memory-only buffer until acknowledged by the server. If there is no connection to the server, up to <number> messages are queued, and resent when the connection is esablished.


• rawEvents <topic-regexp>
  send all messages as events attributed to this MQTT2_CLIENT instance. Should only be used, if there is no MQTT2_DEVICE to process the topic.


• subscriptions <subscriptions>
  space separated list of MQTT subscriptions, default is #
  Note: if the value is the literal setByTheProgram, then the value sent by the client (e.g. MQTT_GENERIC_BRIDGE) is used.


• SSL
  Enable SSL (i.e. TLS)


• sslargs
  a list of space separated tuples of key:value, where key is one of the possible options documented in perldoc IO::Socket::SSL


• topicConversion [1|0]
  due to historic reasons colon (:) is converted in the topic to underscore (_). Setting this attribute to 0 will disable this conversion. Default is 1.


• username <username>
  set the username. The password is set via the set command, and is stored separately, see above.

MQTT2_DEVICE

MQTT2_DEVICE is used to represent single devices connected to the MQTT2_SERVER. MQTT2_SERVER and MQTT2_DEVICE is intended to simplify connecting MQTT devices to FHEM.

Define
define <name> MQTT2_DEVICE [clientId]

To enable a meaningful function you will need to set at least one of the readingList, setList or getList attributes below.
Specifying the clientId (sometimes referred to as CID) is optional, and it makes only sense, if the IO Device is an MQTT2_SERVER.

Set
see the setList attribute documentation below.

Get
see the getList attribute documentation below.

Attributes
• autocreate {0|1}
  if set to 0, disables extending the readingList, when the IODev autocreate is also set. Default is 1, i.e. new topics will be automatically added to the readingList.


• bridgeRegexp <regexp> newClientId ...
  Used to automatically redirect some types of topics to different MQTT2_DEVICE instances. The regexp is checked against the clientid:topic:message and topic:message. The newClientId is a perl expression!. Example:
  attr zigbee2mqtt bridgeRegexp zigbee2mqtt/([A-Za-z0-9]*)[/]?.*:.* "zigbee_$1"
  will create different MQTT2_DEVICE instances for different hex numbers in the topic. Note: the newClientId is enclosed in "", as it is a perl expression, should be unique, and the automatically created device will be created also with this name.
  Notes:
  • multiple tuples of <regexp> newClientId are separated by newline
  • setting bridgeRegexp will remove the readingList attribute and all readings.
  • For a zigbee2mqtt device connected via MQTT2_SERVER the following is probably a better solution:
    
    attr zigbee2mqtt bridgeRegexp zigbee2mqtt/0x........([^/]+):.* "zigbee_$1"


• devicetopic value
  
  • if value does not contain an equal sign (=), replace $DEVICETOPIC in the topic part of the readingList, setList and getList attributes with value.
  • if the value does contain an equal sign (=), then it is interpreted as
    Var1=Var1Value Var2="Value with space" Var3=...
    and $Var1,$Var2,$Var3 are replaced in the readingList, setList and getList attributes with the corresponding value.
    Note: the name Var1,etc must only contain the letters A-Za-z0-9_.
  • If the attribute is not set, $DEVICETOPIC will be replaced with the name of the device in the attributes mentioned above.


• devPos value
  used internally by the "Show neighbor map" visualizer in FHEMWEB. This function is active if the graphviz and devices readings are set, usually in the zigbee2mqtt bridge device.


• disable
  disabledForIntervals


• getList cmd reading [topic|perl-Expression] ...
  When the FHEM command cmd is issued, publish the topic (and optional message, which is separated by space from the topic), wait for the answer which must contain the specified reading, and show the result in the user interface.
  Multiple triples can be specified, each of them separated by newline. Example:
    attr dev getList\
    temp temperature myDev/cmd/getstatus\
    hum humReading myDev/cmd/getHumidity now
  This example defines 2 get commands (temp and hum), which both publish the same topic, but wait for different readings to be set.
  Notes:
  • the readings must be parsed by a readingList
  • get is asynchron, it is intended for frontends like FHEMWEB or telnet, the result cannot be used in self-written perl expressions. Use a set and a notify/DOIF/etc definition for such a purpose
  • arguments to the get command will be appended to the message published (not for the perl expression)
  • the command arguments are available as $EVENT, $EVTPART0, etc.
  • the perl expression must return a string containing the topic and the message separated by a space.


• imageLink href
  sets the image to be shown. The "Show neighbor map" function initializes the value automatically.


• jsonMap oldReading1:newReading1 oldReading2:newReading2...
  space or newline separated list of oldReading:newReading pairs.
  Used in the automatically generated readingList json2nameValue function to map the generated reading name to a better one. E.g.
  attr m2d jsonMap SENSOR_AM2301_Humidity:Humidity
attr m2d readingList tele/sonoff/SENSOR:.* { json2nameValue($EVENT, 'SENSOR_', $JSONMAP) }
  The special newReading value of 0 will prevent creating a reading for oldReading.


• periodicCmd <cmd1>:<period1> <cmd2>:<period2>...
  periodically execute the get or set command. The command will not take any arguments, create a new command without argument, if necessary. period is measured in minutes, and it must be an integer.


• readingList <regexp> [readingName|perl-Expression] ...
  If the regexp matches topic:message or cid:topic:message either set readingName to the published message, or evaluate the perl expression, which has to return a hash consisting of readingName=>readingValue entries. You can define multiple such tuples, separated by newline, the newline does not have to be entered in the FHEMWEB frontend. cid is the client-id of the sending device.
  Example:
    attr dev readingList\
    myDev/temp:.* temperature\
    myDev/hum:.* { { humidity=>$EVTPART0 } }

  Notes:
  • in the perl expression the variables $TOPIC, $NAME, $DEVICETOPIC $JSONMAP and $EVENT are available (the letter containing the whole message), as well as $EVTPART0, $EVTPART1, ... each containing a single word of the message.
  • the helper function json2nameValue($EVENT) can be used to parse a json encoded value. Importing all values from a Sonoff device with a Tasmota firmware can be done with:
    attr sonoff_th10 readingList tele/sonoff/S.* { json2nameValue($EVENT) }
    A second (optional) parameter to json2nameValue is treated as prefix, and will be prepended to each reading name.
    The third (optional) parameter is $JSONMAP, see the jsonMap attribute above.


• setExtensionsEvent
  If set, the event will contain the command implemented by SetExtensions (e.g. on-for-timer 10), else the executed command (e.g. on).


• setList cmd [topic|perl-Expression] ...
  When the FHEM command cmd is issued, publish the topic. Multiple tuples can be specified, each of them separated by newline, the newline does not have to be entered in the FHEMWEB frontend. Example:
    attr dev setList\
    on tasmota/sonoff/cmnd/Power1 on\
    off tasmota/sonoff/cmnd/Power1 off
  This example defines 2 set commands (on and off), which both publish the same topic, but with different messages (arguments).
  Notes:
  • arguments to the set command will be appended to the message published (this is not valid not for the perl expression)
  • the command arguments are available as $EVENT, $EVTPART0, etc., the name of the device as $NAME, both in the perl expression and the "normal" topic variant.
  • the perl expression must return a string containing the topic and the message separated by a space. If it returns "", undef or 0, no MQTT message will be sent.
  • SetExtensions is activated
  • if the topic name ends with :r, then the retain flag is set
  • if the whole argument is enclosed in {}, then it is evaluated as a perl expression. The string returned will be interpreted as described above.


• setStateList command command ...
  This attribute is used to get more detailed feedback when switching devices. I.e. when the command on is contained in the list, state will be first set to set_on, and after the device reports execution, state will be set to on (probably with the help of stateFormat). Commands not in the list will set a reading named after the command, with the word set and the command parameters as its value.
  
  If this attribute is not defined, then a set command will set the state reading to the name of the command.
  If this attribute is set to ignore, then a set command will not affect any reading in the device.

MQTT2_SERVER

MQTT2_SERVER is a builtin/cleanroom implementation of an MQTT server using no external libraries. It serves as an IODev to MQTT2_DEVICES, but may be used as a replacement for standalone servers like mosquitto (with less features and performance). It is intended to simplify connecting MQTT devices to FHEM.

Define
define <name> MQTT2_SERVER <tcp-portnr> [global|IP]

Enable the server on port <tcp-portnr>. If global is specified, then requests from all interfaces (not only localhost / 127.0.0.1) are serviced. If IP is specified, then MQTT2_SERVER will only listen on this IP.
To enable listening on IPV6 see the comments here.
Notes:

• to set user/password use an allowed instance and its basicAuth feature (set/attr)
• the retain flag is not propagated by publish
• only QOS 0 and 1 is implemented

Set
• publish [-r] topic value
  publish a message, -r denotes setting the retain flag.
• clearRetain
  delete all the retained topics.
• reopen
  reopen the server port. This is an alternative to restart FHEM when the SSL certificate is replaced.

Get
N/A

Attributes
• allowfrom


• autocreate [no|simple|complex]
  MQTT2_DEVICES will be automatically created upon receiving an unknown message. Set this value to no to disable autocreating, the default is simple.
  With simple the one-argument version of json2nameValue is added: json2nameValue($EVENT), with complex the full version: json2nameValue($EVENT, 'SENSOR_', $JSONMAP). Which one is better depends on the attached devices and on the personal taste, and it is only relevant for json payload. For non-json payload there is no difference between simple and complex.


• binaryTopicRegexp <regular-expression>
  this attribute is only relevant, if the global attribute "encoding unicode" is set.
  In this case the MQTT payload is automatically assumed to be UTF-8, which may cause conversion-problems if the payload is binary. This conversion wont take place, if the topic matches the regular expression specified. Note: as is the case with other modules, ^ and $ is added to the regular expression.


• clientId <name>
  set the MQTT clientId for all connections, for setups with clients creating a different MQTT-ID for each connection. The autocreate capabilities are greatly reduced in this case, and setting it requires to remove the clientId from all existing MQTT2_DEVICE readingList attributes.


• clientOrder [MQTT2_DEVICE] [MQTT_GENERIC_BRIDGE]
  set the notification order for client modules. This is relevant when autocreate is active, and the default order (MQTT2_DEVICE MQTT_GENERIC_BRIDGE) is not adequate. Note: Changing the attribute affects _all_ MQTT2_SERVER instances.


• disable
  disabledForIntervals
  disable distribution of messages. The server itself will accept and store messages, but not forward them.


• hideRetain [0|1]
  if set to 1, the RETAIN reading will be named .RETAIN, i.e. hidden by default.
• ignoreRegexp
  if $topic:$message matches ignoreRegexp, then it will be silently ignored. For general purpose servers, it is a good idea to set it e.g. to
  homeassistant/[^:"]+/config|tasmota/discovery/[^/:]+/(config|sensors)
  and also include the topics used to send commands towards your MQTT clients.
• keepaliveFactor
  the oasis spec requires a disconnect, if after 1.5 times the client supplied keepalive no data or PINGREQ is sent. With this attribute you can modify this factor, 0 disables the check. Notes:
  • dont complain if you set this attribute to less or equal to 1.
  • MQTT2_SERVER checks the keepalive only every 10 second.
• rawEvents <topic-regexp>
  Send all messages as events attributed to this MQTT2_SERVER instance. Should only be used, if there is no MQTT2_DEVICE to process the topic.


• rePublish
  if a topic is published from a source inside of FHEM (e.g. MQTT2_DEVICE), it is only sent to real MQTT clients, and it will not internally republished. By setting this attribute the topic will also be dispatched to the FHEM internal clients.


• respectRetain [1|0]
  As storing messages with the retain flag can take up considerable space and it has no use in a FHEM only environment, it is by default disabled for featurelevel > 6.1. Set this attribute to 1 if you have external devices relying on this feature.
• SSL
  Enable SSL (i.e. TLS). Note: after deleting or zeroing this attribute FHEM must be restarted.


• sslVersion
  See the global attribute sslVersion.


• sslCertPrefix
  Set the prefix for the SSL certificate, default is certs/server-, see also the SSL attribute.


• topicConversion [1|0]
  due to historic reasons colon (:) is converted in the topic to underscore (_). Setting this attribute to 0 will disable this conversion. Default is 1.

MQTT_DEVICE

acts as a fhem-device that is mapped to mqtt-topics.

requires a MQTT-device as IODev
Note: this module is based on Net::MQTT which needs to be installed from CPAN first.

Define

define <name> MQTT_DEVICE
Specifies the MQTT device.

Set

• set <name> <command>
  sets reading 'state' and publishes the command to topic configured via attr publishSet

• set <name> <reading> <value>
  sets reading <reading> and publishes the command to topic configured via attr publishSet_<reading>

• The set extensions are supported with useSetExtensions attribute.
  Set eventMap if your publishSet commands are not on/off.

  example for true/false:
  attr mqttest eventMap { dev=>{ 'true'=>'on', 'false'=>'off' }, usr=>{ '^on$'=>'true', '^off$'=>'false' }, fw=>{ '^on$'=>'on', '^off$'=>'off' } }

Attributes

• attr <name> publishSet [[<reading>:]<commands_or_options>] <topic>
  configures set commands and UI-options e.g. 'slider' that may be used to both set given reading ('state' if not defined) and publish to configured topic

  example:
  attr mqttest publishSet on off switch:on,off level:slider,0,1,100 /topic/123

• attr <name> publishSet_<reading> [<values>]* <topic>
  configures reading that may be used to both set 'reading' (to optionally configured values) and publish to configured topic

• attr <name> autoSubscribeReadings <topic>
  specify a mqtt-topic pattern with wildcard (e.c. 'myhouse/kitchen/+') and MQTT_DEVICE automagically creates readings based on the wildcard-match
  e.g a message received with topic 'myhouse/kitchen/temperature' would create and update a reading 'temperature'.
  Please note that topics with spaces will not work here!

• attr <name> subscribeReading_<reading> [{Perl-expression}] [qos:?] [retain:?] <topic>
  mapps a reading to a specific topic. The reading is updated whenever a message to the configured topic arrives.
  QOS and ratain can be optionally defined for this topic.
  Furthermore, a Perl statement can be provided which is executed when the message is received. The following variables are available for the expression: $hash, $name, $topic, $message. Return value decides whether reading is set (true (e.g., 1) or undef) or discarded (false (e.g., 0)).

  Example:
  attr mqttest subscribeReading_cmd {fhem("set something off")} /topic/cmd

• attr <name> retain <flags> ...
  Specifies the retain flag for all or specific readings. Possible values are 0, 1

  Examples:
  attr mqttest retain 0
  defines retain 0 for all readings/topics (due to downward compatibility)
  retain *:0 1 test:1
  defines retain 0 for all readings/topics except the reading 'test'. Retain for 'test' is 1
  

• attr <name> qos <flags> ...
  Specifies the QOS flag for all or specific readings. Possible values are 0, 1 or 2. Constants may be also used: at-most-once = 0, at-least-once = 1, exactly-once = 2

  Examples:
  attr mqttest qos 0
  defines QOS 0 for all readings/topics (due to downward compatibility)
  retain *:0 1 test:1
  defines QOS 0 for all readings/topics except the reading 'test'. Retain for 'test' is 1
  

• attr <name> useSetExtensions <flags>
  If set to 1, then the set extensions are supported.

MQTT_GENERIC_BRIDGE

This module is a MQTT bridge, which simultaneously collects data from several FHEM devices and passes their readings via MQTT, sets readings from incoming MQTT messages or executes incoming messages as a 'set' command for the configured FHEM device.
One for the device types could serve as IODev: MQTT, MQTT2_CLIENT or MQTT2_SERVER.

The (minimal) configuration of the bridge itself is basically very simple.

Definition:

In the simplest case, two lines are enough:

defmod mqttGeneric MQTT_GENERIC_BRIDGE [prefix] [devspec,[devspec]
attr mqttGeneric IODev

All parameters in the define are optional.

The first parameter is a prefix for the control attributes on which the devices to be monitored (see above) are configured. Default value is 'mqtt'. If this is e.g. redefined as mqttGB1_, the control attributes are named mqttGB1_Publish etc.

The second parameter ('devspec') allows to minimize the number of devices to be monitored (otherwise all devices will be monitored, which may cost performance). Example for devspec: 'TYPE=dummy' or 'dummy1,dummy2'. Following the general rules for devspec, a comma separated list must not contain any whitespaces!

get:

• version
  Displays module version.

• devlist [<name (regex)>]
  Returns list of names of devices monitored by this bridge whose names correspond to the optional regular expression. If no expression provided, all devices are listed.

• devinfo [<name (regex)>]
  Returns a list of monitored devices whose names correspond to the optional regular expression. If no expression provided, all devices are listed. In addition, the topics used in 'publish' and 'subscribe' are displayed including the corresponding read-in names.

readings:

• device-count
  Number of monitored devices

• incoming-count
  Number of incoming messages

• outgoing-count
  Number of outgoing messages

• updated-reading-count
  Number of updated readings

• updated-set-count
  Number of executed 'set' commands

• transmission-state
  last transmission state

Attributes:

The MQTT_GENERIC_BRIDGE device itself supports the following attributes:

• IODev
  This attribute is mandatory and must contain the name of a functioning MQTT-IO module instance. MQTT, MQTT2_CLIENT and MQTT2_SERVER are supported.

• disable
  Value '1' deactivates the bridge

  Example:
  attr <dev> disable 1

• globalDefaults
  Defines defaults. These are used in the case where suitable values are not defined in the respective device. see mqttDefaults.

  Example:
  attr <dev> sub:base=FHEM/set pub:base=FHEM

• globalAlias
  Defines aliases. These are used in the case where suitable values are not defined in the respective device. see mqttAlias.

• globalPublish
  Defines topics / flags for MQTT transmission. These are used if there are no suitable values in the respective device. see mqttPublish.

  Remark:
  Setting this attribute will publish any reading value from any device matching the devspec. In most cases this may not be the intented behaviour, setting accurate attributes to the subordinated devices should be preferred.

• globalTypeExclude
  Defines (device) types and readings that should not be considered in the transmission. Values can be specified separately for each direction (publish or subscribe). Use prefixes 'pub:' and 'sub:' for this purpose. A single value means that a device is completely ignored (for all its readings and both directions). Colon separated pairs are interpreted as '[sub:|pub:]Type:Reading'. This means that the given reading is not transmitted on all devices of the given type. An '*' instead of type or reading means that all readings of a device type or named readings are ignored on every device type.

  Example:
  attr <dev> globalTypeExclude MQTT MQTT_GENERIC_BRIDGE:* MQTT_BRIDGE:transmission-state *:baseID

• globalDeviceExclude
  Defines device names and readings that should not be transferred. Values can be specified separately for each direction (publish or subscribe). Use prefixes 'pub:' and 'sub:' for this purpose. A single value means that a device with that name is completely ignored (for all its readings and both directions). Colon-separated pairs are interpreted as '[sub:|pub:]Device:Reading'. This means that the given reading is not transmitted to the given device.

  Example:
  attr <dev> globalDeviceExclude Test Bridge:transmission-state

• forceNEXT
  

  Only relevant for MQTT2_CLIENT or MQTT2_SERVER as IODev. If set to 1, MQTT_GENERIC_BRIDGE will forward incoming messages also to further client modules like MQTT2_DEVICE, even if the topic matches to one of the subscriptions of the controlled devices. By default, these messages will not be forwarded for better compability with autocreate feature on MQTT2_DEVICE. See also clientOrder attribute in MQTT2 IO-type commandrefs; setting this in one instance of MQTT_GENERIC _BRIDGE might affect others, too.




For the monitored devices, a list of the possible attributes is automatically extended by several further entries. Their names all start with the prefix previously defined in the bridge. These attributes are used to configure the actual MQTT mapping.
By default, the following attribute names are used: mqttDefaults, mqttAlias, mqttPublish, mqttSubscribe.
The meaning of these attributes is explained below.

• mqttDefaults
  

  Here is a list of "key = value" pairs defined. The following keys are possible:

  • 'qos'
    defines a default value for MQTT parameter 'Quality of Service'.
  • 'retain'
    allows MQTT messages to be marked as 'retained'.
  • 'base'
    s provided as a variable ($base) when configuring concrete topics. It can contain either text or a Perl expression. Perl expression must be enclosed in curly brackets. The following variables can be used in an expression: $base = corresponding definition from the 'globalDefaults', $reading = Original reading name, $device = device name, and $name = reading alias (see mqttAlias. If no alias is defined, than $name = $ reading).
    Furthermore, freely named variables can be defined. These can also be used in the public / subscribe definitions. These variables are always to be used there with quotation marks.
  
  All these values can be limited by prefixes ('pub:' or 'sub') in their validity to only send or receive only (as far asappropriate). Values for 'qos' and 'retain' are only used if no explicit information has been given about it for a specific topic.

  Example:
  attr <dev> mqttDefaults base={"TEST/$device"} pub:qos=0 sub:qos=2 retain=0

• mqttAlias
  

  This attribute allows readings to be mapped to MQTT topic under a different name. Usually only useful if topic definitions are Perl expressions with corresponding variables or to achieve somehow standardized topic structures. Again, 'pub:' and 'sub:' prefixes are supported (For 'subscribe', the mapping will be reversed).

  Example:
  attr <dev> mqttAlias pub:temperature=temp

• mqttPublish
  

  Specific topics can be defined and assigned to the Readings(Format: <reading>:topic=<topic>). Furthermore, these can be individually provided with 'qos' and 'retain' flags.
  Topics can also be defined as Perl expression with variables ($reading, $device, $name, $base or additional variables as provided in mqttDefaults).
  
  Values for several readings can also be defined together, separated with '|'.
  If a '*' is used instead of a reading name, this definition applies to all readings for which no explicit information was provided.
  Topic can also be written as a 'readings-topic'.
  Attributes can also be sent ("atopic" or "attr-topic"). If you want to send several messages (e.g. to different topics) for an event, the respective definitions must be defined by appending unique suffixes (separated from the reading name by a !-sign): reading!1:topic=... reading!2:topic=....
  It is possible to define expressions (reading: expression = ...).
  The expressions could be used to change variables ($value, $topic, $qos, $retain, $message, $uid), or return a value of != undef.
  The return value is used as a new message value, the changed variables have priority.
  If the return value is undef, setting / execution is suppressed.
  If the return is a hash (topic only), its key values are used as the topic, and the contents of the messages are the values from the hash.

  Option 'resendOnConnect' allows to save the messages, if the bridge is not connected to the MQTT server. The messages to be sent are stored in a queue. When the connection is established, the messages are sent in the original order.

  Possible values:
  • none
    discard all
  • last
    save only the last message
  • first
    save only the first message then discard the following
  • all
    save all, but if there is an upper limit of 100, if it is more, the most supernatural messages are discarded.

  Examples:
  attr <dev> mqttPublish temperature:topic={"$base/$name"} temperature:qos=1 temperature:retain=0 *:topic={"$base/$name"} humidity:topic=/TEST/Feuchte
attr <dev> mqttPublish temperature|humidity:topic={"$base/$name"} temperature|humidity:qos=1 temperature|humidity:retain=0
attr <dev> mqttPublish *:topic={"$base/$name"} *:qos=2 *:retain=0
attr <dev> mqttPublish *:topic={"$base/$name"} reading:expression={"message: $value"}
attr <dev> mqttPublish *:topic={"$base/$name"} reading:expression={$value="message: $value"}
attr <dev> mqttPublish *:topic={"$base/$name"} reading:expression={"/TEST/Topic1"=>"$message", "/TEST/Topic2"=>"message: $message"}
attr <dev> mqttPublish *:resendOnConnect=last
attr <dev> mqttPublish temperature:topic={"$base/temperature/01/value"} temperature!json:topic={"$base/temperature/01/json"} temperature!json:expression={toJSON({value=>$value,type=>"temperature",unit=>"°C",format=>"00.0"})}


• mqttSubscribe
  This attribute configures the device to receive MQTT messages and execute corresponding actions.
  The configuration is similar to that for the 'mqttPublish' attribute. Topics can be defined for setting readings ('topic' or 'readings-topic') and calls to the 'set' command on the device ('stopic' or 'set-topic').
  Also attributes can be set ('atopic' or 'attr-topic').
  The result can be modified before setting the reading or executing of 'set' / 'attr' on the device with additional Perl expressions ('expression').
  The following variables are available in the expression: $device, $reading, $message (initially equal to $value). The expression can either change variable $value, or return a value != undef. Redefinition of the variable has priority. If the return value is undef, then the set / execute is suppressed (unless $value has a new value).
  If the return is a hash (only for 'topic' and 'stopic'), then its key values are used as readings or 'set' parameters, the values to be set are the values from the hash.
  Furthermore the attribute 'qos' can be specified ('retain' does not make sense here).
  Topic definition can include MQTT wildcards (+ and #).
  If the reading name is defined with a '*' at the beginning, it will act as a wildcard. Several definitions with '*' should also be used as: *1:topic = ... *2:topic = ... The actual name of the reading (and possibly of the device) is defined by variables from the topic ($device (only for global definition in the bridge), $reading, $name). In the topic these variables act as wildcards, of course only makes sense, if reading name is not defined (so start with '*', or multiple names separated with '|').
  The variable $name, unlike $reading, may be affected by the aliases defined in 'mqttAlias'. Also use of $base is allowed.
  When using 'stopic', the 'set' command is executed as 'set <dev> <reading> <value>'. For something like 'set <dev> <value>' 'state' should be used as reading name.

  If JSON support is needed: Use the json2nameValue() method provided by fhem.pl in 'expression' with '$message' as parameter.

  Examples:
  attr <dev> mqttSubscribe temperature:topic=TEST/temperature test:qos=0 *:topic={"TEST/$reading/value"}
attr <dev> mqttSubscribe desired-temperature:stopic={"TEST/temperature/set"}
attr <dev> mqttSubscribe state:stopic={"TEST/light/set"} state:expression={...}
attr <dev> mqttSubscribe state:stopic={"TEST/light/set"} state:expression={$value="x"}
attr <dev> mqttSubscribe state:stopic={"TEST/light/set"} state:expression={"R1"=>$value, "R2"=>"Val: $value", "R3"=>"x"} attr <dev> mqttSubscribe verbose:atopic={"TEST/light/verbose"} attr <dev> mqttSubscribe json:topic=XTEST/json json:expression={json2nameValue($message)}

• mqttForward
  

  This attribute defines what happens when one and the same reading is both subscribed and posted. Possible values: 'all' and 'none'.
  If 'none' is selected, than messages received via MQTT will not be published from the same device.
  The setting 'all' does the opposite, so that the forwarding is possible.
  If this attribute is missing, the default setting for all device types except 'dummy' is 'all' (so that actuators can receive commands and send their changes in the same time) and for dummies 'none' is used. This was chosen because dummies are often used as a kind of GUI switch element. In this case, 'all' might cause an endless loop of messages.

• mqttDisable
  

  If this attribute is set in a device, this device is excluded from sending or receiving the readings.

Examples

• Bridge for any devices with the standard prefix:
  defmod mqttGeneric MQTT_GENERIC_BRIDGE
attr mqttGeneric IODev mqtt

• Bridge with the prefix 'mqtt' for three specific devices:
  defmod mqttGeneric MQTT_GENERIC_BRIDGE mqtt sensor1,sensor2,sensor3
attr mqttGeneric IODev mqtt

• Bridge for all devices in a certain room:
  defmod mqttGeneric MQTT_GENERIC_BRIDGE mqtt room=Wohnzimmer
attr mqttGeneric IODev mqtt

• Simple configuration of a temperature sensor:
  defmod sensor XXX
attr sensor mqttPublish temperature:topic=haus/sensor/temperature

• Send all readings of a sensor (with their names as they are) via MQTT:
  defmod sensor XXX
attr sensor mqttPublish *:topic={"sensor/$reading"}

• Topic definition with shared part in 'base' variable:
  defmod sensor XXX
attr sensor mqttDefaults base={"$device/$reading"}
attr sensor mqttPublish *:topic={"$base"}

• Topic definition only for certain readings with renaming (alias):
  defmod sensor XXX
attr sensor mqttAlias temperature=temp humidity=hum
attr sensor mqttDefaults base={"$device/$name"}
attr sensor mqttPublish temperature:topic={"$base"} humidity:topic={"$base"}


• Example of a central configuration in the bridge for all devices that have Reading named 'temperature':
  defmod mqttGeneric MQTT_GENERIC_BRIDGE
attr mqttGeneric IODev mqtt
attr mqttGeneric defaults sub:qos=2 pub:qos=0 retain=0
attr mqttGeneric publish temperature:topic={"haus/$device/$reading"}


• Example of a central configuration in the bridge for all devices:
  defmod mqttGeneric MQTT_GENERIC_BRIDGE
attr mqttGeneric IODev mqtt
attr mqttGeneric defaults sub:qos=2 pub:qos=0 retain=0
attr mqttGeneric publish *:topic={"haus/$device/$reading"}


Limitations:

• If several readings subscribe to the same topic, no different QOS are possible.
• If QOS is not equal to 0, it should either be defined individually for all readings, or generally over defaults.
  Otherwise, the first found value is used when creating a subscription.
• Subscriptions are renewed only when the topic is changed, so changing the QOS flag onnly will only work after a restart of FHEM.

msg

[EN DE]

For documentation in german see FHEM Forum or FHEM Wiki

Syntax is:
msg [<type>] [<@device>|<e-mail address>] [<priority>] [|<title>|] <message>

Except for message all parameters are optional, for configuration of the entire messageing logics see also msgConfig.

Basic idea behind the command (and msgConfig) is to establish a central logic for dispatching messages to be sent to the user, so e.g. in case an address of an recipient changes, you only have to change one single point in your entire configuration.
Parameters are as follows:

• type
  Is optional and one of text, audio, light or screen. If ommitted, it defaults to text.
  You may provide more than one type by providing a comma-seperated list.
• @device or e-mail address
  For @device you may opt for any instance of a messenger service available in mscConfig, by default Pushover will be used (if available).
  For emailing, per default system() command per /usr/bin/mail is issued. You may provide more than one recipent by providing a comma-seperated list here (also mixed).
• priority
  Is also optional. You may any (nummeric) value understood by your addressed messaging device, good idea is to use values common in the Pushover API (-2 to 2).
• title
  Is also optional, but when given, it has to be enclosed in pipe characters.

MSGFile

[EN DE]

The MSGFile device is used to write arbitrary data to a file on disk or other media accessable through the filesystem. In order to write to a file, the access rights of the FHEM process to the specified file and path are relevant. To set the rights for a directory, please use OS related commands.

Define

define <name> MSGFile <filename>

Specifies the MSGFile device. At definition the message counter is set to 0. A filename must be specified at definition.

Examples:
define myFile MSGFile

Set

set <name> add|clear|list|write [text]
Set is used to manipulate the message buffer of the device. The message buffer is an array of lines of data, stored serial based on the incoming time into the buffer. Lines of data inside the buffer could not be deleted anymore, except of flashing the whole buffer.

add
to add lines of data to the message buffer. All data behind "add" will be interpreted as text message. To add a carriage return to the data, please use the CR attribute.
clear
to flash the message buffer and set the line counter to 0. All the lines of data are deleted and the buffer is flushed.
list
to list the message buffer.


write
to write the message buffer to the associated file.



Examples:
set myFile add Dies ist Textzeile 1
set myFile add Dies ist Textzeile 2
set myFile clear

Full working example to write two lines of data to a file:
define myFile MSGFile /tmp/fhemtest.txt
attr myFile filemode append
set myFile add Textzeile 1
set myFile add Textzeile 2
set myFile write
set myFile clear


Attributes
• filename
  sets the filename, must be a fully qualified filename. FHEM must have the rights to write this file to the directory
• filemode
  sets the filemode, valid are "new" or "append"
  new creates a new, empty file and writes the data to this file. Existing files are cleared, the data is lost!
  append uses, if available, an existing file and writes the buffer data to the end of the file. If the file do not exist, it will be created
• CR
  set the option to write a carriage return at the end of the line. CR could be set to 0 or 1, 1 enables this feature
• loglevel

MSGMail

[EN DE]

The MSGMail device is used to send mail messages to a recipient by connecting to a SMTP server. Currently MSGMail supports only servers, that allow SSL secured connections like Googlemail, GMX, Yahoo or 1und1. MSGMail requires the perl pacakge MAIL::Lite. For SSL support, Net::SMTP version 3.06 is required. On systems with an older version of Net::SMTP, MSGMail requires the package Net::SMTP::SSL.

Define

define <name> MSGMail <from> <to> <smtphost> <authfile>

Specifies the MSGMail device. At definition the message counter is set to 0. From, To, SMTPHost and the authfile (see attributes below) need to be defined at definition time.

Examples:
define myMail MSGMail from@address.com to@address.com smtp.provider.host /etc/msgauthfile

Set

set <name> add|clear|list|send [text]
Set is used to manipulate the message buffer of the device. The message buffer is an array of lines of data, stored serial based on the incoming time into the buffer. Lines of data inside the buffer could not be deleted anymore, except of flashing the whole buffer.

add
to add lines of data to the message buffer. All data behind "add" will be interpreted as text message. To add a carriage return to the data, please use the CR attribute.
clear
to flush the message buffer and set the line counter to 0. All the lines of data are deleted and the buffer is flushed.
list
to list the message buffer.

send
to send the message buffer.


Examples:
set myMail add Dies ist Textzeile 1
set myMail add Dies ist Textzeile 2
set myMail clear

Full working example to send two lines of data to a recipent:
define myMail MSGMail donald.duck@entenhausen.com dagobert.duck@duck-banking.com smtp.entenhausen.net /etc/fhem/msgmailauth
attr myMail smtpport 9999
attr myMail subject i need more money
attr myMail CR 0
set myMail add Please send me
set myMail add 1.000.000 Taler
set myMail send
set myMail clear



Attributes
Almost all of these attributes are not optional, most of them could set at definition.

• from
  sets the mail address of the sender
• to
  sets the mail address of the recipent
• smtphost
  sets the name of the smtphost, for example for GMX you could use mail.gmx.net or for Googlemail the smtphost is smtp.googlemail.com
• smtpport (optional)
  sets the port of the smtphost, for example for GMX or for Googlemail the smtport is 465, which is also the default and do not need to be set
• subject (optional)
  sets the subject of this email. Per default the subject is set to "FHEM"
  
• authfile
  sets the authfile for the SSL connection to the SMTP host
  the authfile is a simple textfile with the userid in line 1 and the password in line 2.
  Example:
  123user45
strenggeheim
  It is a good behaviour to protect this data and put the file, for example into the /etc directory and set the rights to 440 (chmod 440 /etc/msgmailauthfile), so that not everyone could see the contents of the file. FHEM must have access to this file to read the userid and password.
  
• mailtype plain|html
  Use this attribute to select the contenttype to text/plain or text/html. If text/html is selected, valid html code must be provided as content. No checks are applied! Per default this attribute is 'plain'
• CR
  set the option to write a carriage return at the end of the line. CR could be set to 0 or 1, 1 enables this feature. Per default this attribute is enabled
• loglevel

MYSENSORS

[EN DE]

connects fhem to MYSENSORS.

A single MYSENSORS device can serve multiple MYSENSORS_DEVICE clients.
Each MYSENSORS_DEVICE represents a mysensors node.

Define

define <name> MYSENSORS <serial device>|<ip:port>

Specifies the MYSENSORS device.

Set

• connect

  set <name> connect

  (re-)connects the MYSENSORS-device to the MYSENSORS-gateway

  Can also be used to reload the OTA_firmwareConfig file after editing.

• disconnect

  set <name> disconnect

  disconnects the MYSENSORS-device from the MYSENSORS-gateway

• inclusion-mode

  set <name> inclusion-mode on|off

  turns the gateways inclusion-mode on or off

Attributes

• autocreate

  attr <name> autocreate

  enables auto-creation of MYSENSOR_DEVICE-devices on receival of presentation-messages

• requestAck

  attr <name> requestAck

  request acknowledge from nodes.

  if set the Readings of nodes are updated not before requested acknowledge is received
  if not set the Readings of nodes are updated immediatly (not awaiting the acknowledge).

  May also be configured for individual nodes if not set for gateway.

• first-sensorid

  attr <name> first-sensorid <number < 255>

  configures the lowest node-id assigned to a mysensor-node on request (defaults to 20)

• OTA_firmwareConfig

  attr <name> OTA_firmwareConfig <filename>

  specifies a configuration file for the FOTA (firmware over the air - wireless programming of the nodes) configuration. It must be stored in the folder FHEM/firmware. The format of the configuration file is the following (csv):

  #Type,Name,Version,File,Comments
10,Blink,1,Blink.hex,blinking example

  The meaning of the columns is the following:

  Type

  a numeric value (range 0 .. 65536) - each node will be assigned a firmware type

  Name

  a short name for this type

  Version

  a numeric value (range 0 .. 65536) - the version of the firmware (may be different to the value that is send during the node presentation)

  File

  the filename containing the firmware - must also be stored in the folder FHEM/firmware

  Comments

  a description / comment for the firmware

  Note: Firmware config file by default only is read at startup. If you change it later, just issue a connect command to update also Internal values.

MYSENSORS_DEVICE

represents a mysensors sensor attached to a mysensor-node

requires a MYSENSORS-device as IODev

Define

define <name> MYSENSORS_DEVICE <Sensor-type> <node-id>

Specifies the MYSENSOR_DEVICE device.

Set

• AttrTemplate

  Helps to easily configure your devices. Just get a list of all available attrTremplates by issuing
  set <name> attrTemplate ?

  Have a look at the descriptions and choose a suitable one. Then use the drop-down list and click "set" or use
  set <name> attrTemplate A_02a_atmospheric_pressure

• clear

  set <name> clear

  clears MySensors EEPROM area and reboot (i.e. "factory" reset) - requires MY_SPECIAL_DEBUG

• flash

  set <name> flash

  Checks whether a newer firmware version is available. If a newer firmware version is available the flash procedure is started. The sensor node must support FOTA for this.

• fwType

  set <name> fwType <value>

  assigns a firmware type to this node (must be a numeric value in the range 0 .. 65536).
  Should be contained in the FOTA configuration file

  .

  Note: Firmware config file by default only is read at startup. If you change it later, just issue a connect command to the GW to update also Internal values.

• time

  set <name> time

  sets time for nodes (that support it)

• reboot

  set <name> reboot

  reboots a node (requires a bootloader that supports it).
  Attention: Nodes that run the standard arduino-bootloader will enter a bootloop!
  Dis- and reconnect the nodes power to restart in this case.

Get

• Extended_DEBUG

  get <name> Extended_DEBUG

  requires MY_SPECIAL_DEBUG
  retrieves the CPU frequency, CPU voltage and free memory of the sensor

• ReadingsFromComment

  get <name> ReadingsFromComment

  rebuild reding names from comments of presentation messages if available
  After issuing this get check the log for changes.

• RSSI

  get <name> RSSI

  requires MY_SIGNAL_REPORT_ENABLED, not supported by all transportation layers
  delievers a set of Signal Quality information.

Attributes

• config

  attr <name> config [<M|I>]

  configures metric (M) or inch (I). Defaults to 'M'

• OTA_autoUpdate

  attr <name> OTA_autoUpdate [<0|1>]

  specifies whether an automatic update of the sensor node should be performed (1) during startup of the node or not (0). Defaults to 0

• setCommands

  attr <name> setCommands [<command:reading:value>]*

  configures one or more commands that can be executed by set.

  e.g.:
  attr <name> setCommands on:switch_1:on off:switch_1:off

  if list of commands contains both 'on' and 'off' set extensions are supported

• setReading_<reading>

  attr <name> setReading_<reading> [<value>]*

  configures a reading that can be modified by set-command

  e.g.:
  attr <name> setReading_switch_1 on,off

• setExtensionsEvent

  attr <name> setExtensionsEvent

  If set, the event will contain the command implemented by SetExtensions (e.g. on-for-timer 10), else the executed command (e.g. on).

• mapReading_<reading>

  attr <name> mapReading_<reading> <childId> <readingtype> [<value>:<mappedvalue>]*

  configures the reading-name for a given childId and sensortype

  e.g.:
  attr xxx mapReading_aussentemperatur 123 temperature
attr xxx mapReading_leftwindow 10 status 1:closed 0:open

  See also mapReadingType for setting defaults for types without predefined defaults

• requestAck

  attr <name> requestAck

  request acknowledge from nodes.
  if set the Readings of nodes are updated not before requested acknowledge is received
  if not set the Readings of nodes are updated immediatly (not awaiting the acknowledge).
  May also be configured on the gateway for all nodes at once

• mapReadingType_<reading>

  attr <name> mapReadingType_<reading> <new reading name> [<value>:<mappedvalue>]*

  configures reading type names that should be used instead of technical names

  e.g.:
  attr xxx mapReadingType_LIGHT switch 0:on 1:off

  to be used for mysensor Variabletypes that have no predefined defaults (yet)

• OTA_BL_Type

  attr <name> OTA_BL_Type <either Optiboot or MYSBootloader>*

  For other bootloaders than Optiboot V3.0 OTA updates will only work if bootloader type is specified - MYSBootloader will reboot node if firmware update is started, so make sure, node will really recover

• OTA_Chan76_IODev

  attr <name> OTA_Chan76_IODev

  As MYSBootloader per default uses nRF24 channel 76, you may specify a different IODev for OTA data using channel 76

• timeoutAck

  attr <name> timeoutAck <time in seconds>*

  configures timeout to set device state to NACK in case not all requested acks are received

• timeoutAlive

  attr <name> timeoutAlive <time in seconds>*

  configures timeout to set device state to alive or dead. If messages from node are received within timout spec, state will be alive, otherwise dead. If state is NACK (in case timeoutAck is also set), state will only be changed to alive, if there are no outstanding messages to be sent.

MaxScanner

[EN DE]

The MaxScanner-Module enables FHEM to capture temperature and valve-position of thermostats in regular intervals.

Define

define <name> MaxScanner


Set-Commands
set <name> run


Runs the scanner loop immediately. (Is usually done by timer)


Get-Commands
get <name> associatedDevices


Gets the asscociated devices (thermostats, shutterContacts)


Attributes for the Scanner-Device


• readingFnAttributes

• disable
  When value=1, then the scanner device is disabled; possible values: 0,1; default: 0

• scnCreditThreshold
  the minimum value of available credits; when lower, the scanner will remain inactive; possible values: 150..600; default: 300

• scnMinInterval
  scan interval in minutes, when the calculated interval is lower, then scnMinintervall will be used instead;possible values: 3..60; default: 3


User-Attributes for the Thermostat-Device


• scanTemp
  When value=1, then scanner will use the thermostat; possible values: 0,1; default: 0

• scnProcessByDesiChange
  When value=1, then scanner will use method "desired change" instead of "mode change"; possible values: 0,1; default: 0

• scnModeHandling
  When scnProcessByDesiChange is active, this attribute select the way of handling the mode of the thermostat; possible values: [NOCHANGE,AUTO,MANUAL];default: AUTO

• scnShutterList
  comma-separated list of shutterContacts associated with the thermostat


Additional information


• Discussion in FHEM forum


• WIKI information in FHEM Wiki

MediaList

[EN DE]

This module can support you to navigate trough you local connected music library. It can compile complex playlists and als an quick playing of an selected whole path.
Note: this module needs the following additional modules:

• libmp3-tag-perl
• libjson-xs-perl
• libmp3-info-perl


Define
define <name> MediaList <RootPath>

Defines a new instanze of MediaList. The Rootpath defines your start directory.
Examples:
define MyMediaList MediaList /media/music


Readings

• CurrentDir:your navigated current directory
• FolderContent:the folder content of CurrentDir
• SelectedItem:the last selected Item from FolderContent
• currentdir_playlist:playlist of CurrentDir
• currentdir_playlistduration:duration of currentdir_playlist
• playlist:your playlist ;)
• playlistduration:duration of your playlist

Set
• RequestedDirectory
  Moving to given relative directory. An record of Reading FolderContent must be used.
  Example:
  
  set <MyMediaList> RequestedDirectory AbbaMusic
  
• Play
  Submit the Playlist to your defined Targetdevice. You has to select which playlist you want to submit
  
• currentdir: Submit the playlist of current directory, see Reading currentdir_playlist
• playlist: Submit the real playlist, see Reading playlist

Example:

set <MyMediaList> Play currentdir
set <MyMediaList> Play playlist

• Playlist_New
  Creates an new playlist.
  Example:
  
  set <MyMediaList> Playlist_New MyNewPlaylist
  
• Playlist_Add
  Add an Track or complete currentdir to your playlist
  
  Example:
  set <MyMediaList> Playlist_Add 0
  Add first Track from Reading currentdir_playlist to your playlist
  set <MyMediaList> Playlist_Add
  Add all Tracks from Reading currentdir_playlist to your playlist
  
• Playlist_Del
  Deletes an Track from your playlist.
  Example:
  
  set <MyMediaList> Playlist_Del 0
  Drops first Track from your Playlist
• Playlist_Empty
  Makes your playlist empty.
  Example:
  
  set <MyMediaList> Playlist_Empty
  

Get
N/A

Attributes
• MediaList_PlayerDevice
  Definition of your Traget Player Device
  Example:
  attr <MyMediaList> MediaList_PlayerDevice Sonos_LivingRoom
  
  
• MediaList_PathReplaceFrom
  Rewrite the local mediapath to an accessible path by Targetdevice. This Attribut define the FROM pattern.
  Example:
  attr <MyMediaList> MediaList_PathReplaceFrom /media/music/
  
  
• MediaList_PathReplaceTo
  Rewrite the local mediapath to an accessible path by Targetdevice. This Attribut define the TO pattern.
  Example:
  attr <MyMediaList> MediaList_PathReplaceTo \\NAS/music/
  
  
• MediaList_PathReplaceToPic
  Rewrites the local Cover path to an accessible path your Webbrowser, TabletUI. This Attribut define the TO pattern. The FROM pattern are defined by MediaList_PathReplaceFrom
  Example:
  attr <MyMediaList> MediaList_PathReplaceToPic https://192.168.1.30/music/
  
  For this example you has to share your music directory via Webserver
• MediaList_PlayerStartCommand
  Definition of the Startcommand for your Targetdevice.
  Example:
  attr <MyMediaList> MediaList_PlayerStartCommand StartPlaylist file:<fullfile>
  
  Command to insert the playlist into your Targetdevice ans starts playing. The definition of fullfile defines a internal dummy to rewrite it by a real playlistname
• MediaList_CacheFileDir
  Definition of your cachefiledir. In this directory the playlist.m3u will be created. In cases of symlinks or music-copies, this directory will be used
  Example:
  attr <MyMediaList> MediaList_CacheFileDir /var/lib/mpd/playlists/
attr <MyMediaList> MediaList_CacheFileDir cache/
  
• MediaList_mkTempCopy
  Definition if you want a playlist with remote files or local accessible files.
  In case of using an sonos device, an remote file based playlist is sufficient.
  In case of using an MPD, local files in MPD music directory must be used
  Example:
  attr <MyMediaList> MediaList_mkTempCopy none
  In case of an Sonos Device
  attr <MyMediaList> MediaList_mkTempCopy symlink
  In case of an MPD Device

MieleAtHome

[EN DE]

MieleAtHome - Controls Miele@home Devices

About

The MieleAtHome module uses the Miele 3rd Party Cloud API. You need a Miele Developer Account to use it! See below for details.
To use the MieleAtHome module you first have to define a device which will act als shared provider for your credentials. When this one is set up, you can use the autocreate-feature to create devices for your appliances.

Miele Developer Account:

To use this module you need to register as a developer at https://www.miele.com/f/com/en/register_api.aspx. After you successfully registered, you will receive a clientId and a clientSecret which you'll need to configure in your <gateway>-device.

Define

(1) Setup gateway:
define <gateway> MieleAtHome

(2a) Autocreate devices:
set <gateway> autocreate

(2b) Manually create devices:
define <MieleDevice> MieleAtHome <DeviceId>@<gateway> [Interval]

Example

(1) Setup gateway:
define MieleConnection MieleAtHome
attr MieleConnection login mylogin@example.com
attr MieleConnection clientId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
set MieleConnection password mypassword
set MieleConnection clientSecret yyyyyyyyyyyyyyyyyyyy

This instance (MieleConnection) will be used to share the credentials. You have to set the attributes login and clientId. Then you have to set password and clientSecret via set MieleConnection-command.

(2a) Autocreate devices:
set MieleConnection autocreate

This will create a device called Miele_xxxxxxxxxxxxx. You can rename autocreated devices afterwards.

(2b) Manually create devices:
define Waschmaschine MieleAtHome 000123456789@MieleConnection 120

This statement creates the instance of your specific Miele@home appliance with the name Waschmaschine and the DeviceId 000123456789 and a refresh-interval of 120 seconds. The interval is optional, its default is 120 seconds.

Remote starting appliences

Appliences like wasching mashines can be started remotely via FHEM, but this is rather unintuitive:
Therefore the user loads the applience, selects a start or end time within the next 24 hours and presses the start button. The applience then waits for a "remote start" and can be started by FHEM before the start or end time has elapsed. If this is not received within the specified start or end time, it starts itself to be ready in time.

Set
• autocreate
  autocreate fhem-devices for each Miele@home appliance found in your account. Needs login, clientId, password and clientSecret to be configured properly. Only available for the gateway device.
• clientSecret <secret>
  sets the clientSecret of your Miele@home-developer Account and stores it in a file (base64-encoded if you have MIME::Base64 installed).
• light [enable|disable]
  enable/disable the light of your device. only available depending on the type and state of your appliance.
• mode <mode>
  set the mode of your applience. can be either sabbathMode or normalOperationMode.
• on
  power up your device. only available depending on the type and state of your appliance.
• off
  power off your device. only available depending on the type and state of your appliance.
• password <pass>
  set the password of your Miele@home Account and stores it in a file (base64-encoded if you have MIME::Base64 installed).
• pause
  pause your device. only available depending on the type and state of your appliance.
• start
  start your device. only available depending on the type and state of your appliance.
• startTime <[H]H:MM>
  modify the start time of your device relative from current time. only available depending on the type and state of your appliance.
• stop
  stop your device. only available depending on the type and state of your appliance.
• startSuperFreezing
  start super freezing your device. only available depending on the type and state of your appliance.
• stopSuperFreezing
  stop super freezing your device. only available depending on the type and state of your appliance.
• startSuperCooling
  start super cooling your device. only available depending on the type and state of your appliance.
• stopSuperCooling
  stop super cooling your device. only available depending on the type and state of your appliance.
• targetTemperature_zoneN <temp>
  set the targetTemperature of zone N of your applience. The available temperature-range is determined by the Miele-API.
• update
  instantly update all readings.
• ventilationStep [Step1|Step2|Step3|Step4]
  set the ventilation step of your device. only available depending on the type and state of your appliance.

Get
• listDevices
  lists the devices associated with your Miele@home-account. Needs login, clientId, password and clientSecret to be configured properly.

Attributes
• api [poll|event]
  set to poll if you want FHEM to repeatedly poll the Miele server for updates. Set to event if you want to have a keepalive-connection to the Miele server. With event, updates are received as soon as they are updated on the Miele server. With poll updates are only received in the configured interval.
  poll is the current default but the default will be switched to event after a testing period.
• clientId
  set the clientId of your Miele@home-developer account.
• country
  set the country where you registered your Miele@home account.
• login
  set the login of your Miele@home account.
• disable
  disables this MieleAtHome-instance.
• lang [de|en]
  request the readings in either german or english. en is default.

MilightBridge

[EN DE]

This module is the interface to a Milight Bridge which is connected to the network using a Wifi connection. It uses a UDP protocal with no acknowledgement so there is no guarantee that your command was received.

The Milight system is sold under various brands around the world including "LimitlessLED, EasyBulb, AppLamp"

The API documentation is available here: http://www.limitlessled.com/dev/

Define

define <name> MilightBridge <host/ip:port>

Specifies the MilightBridge device.
<host/ip> is the hostname or IP address of the Bridge with optional port (defaults to 8899 if not defined, use 50000 for V1,V2 bridges)

Readings

• state
  [Initialized|ok|unreachable]: Shows reachable status of bridge using "ping" check every 10 (checkInterval) seconds.
• sendFail
  0 if everything is OK. 1 if the send function was unable to send the command - this would indicate a problem with your network and/or host/port parameters.
• slot[0|1|2|3|4|5|6|7|8]
  The slotX reading will display the name of the MilightDevice that is defined with this Bridge as it's IODev. It will be blank if no device is defined for that slot.

Attributes

• sendInterval
  Default: 100ms. The bridge has a minimum send delay of 100ms between commands.
• checkInterval
  Default: 10s. Time after the bridge connection is re-checked.
  If this is set to 0 checking is disabled and state = "Initialized".
• protocol
  Default: udp. Change to tcp if you have enabled tcp mode on your bridge.
• tcpPing
  If this attribute is defined, ping will use TCP instead of UDP.

MilightDevice

[EN DE]

This module represents a Milight LED Bulb or LED strip controller. It is controlled by a MilightBridge.

The Milight system is sold under various brands around the world including "LimitlessLED, EasyBulb, AppLamp"

The API documentation is available here: http://www.limitlessled.com/dev/

Requires perl module Math::Round

Define

define <name> MilightDevice <devType(RGB|RGBW|White)> <IODev> <slot>

Specifies the Milight device.
<devType> One of RGB, RGBW, White depending on your device.
<IODev> The MilightBridge which the device is paired with.
<slot> The slot on the MilightBridge that the device is paired with or 'A' to group all slots.

Readings

• state
  [on xxx|off|night]: Current state of the device / night mode (xxx = 0-100%).
• brightness
  [0-100]: Current brightness level in %.
• brightness_on
  [0-100]: The brightness level before the off command was sent. This allows the light to turn back on to the last brightness level.
• rgb
  [FFFFFF]: HEX value for RGB.
• previousState
  [hsv]: hsv value before last change. Can be used with restorePreviousState set command.
• savedState
  [hsv]: hsv value that was saved using saveState set function
• hue
  [0-360]: Current hue value.
• saturation
  [0-100]: Current saturation value.
• transitionInProgress
  [0|1]: Set to 1 if a transition is currently in progress for this device (eg. fade).
• discoMode
  [0|1]: 1 if discoMode is enabled, 0 otherwise.
• discoSpeed
  [0|1]: 1 if discoSpeed is increased, 0 if decreased. Does not mean much for RGBW
• lastPreset
  [0..X]: Last selected preset.
• ct
  [1-10]: Current colour temperature (3000=Warm,6500=Cold) for White devices.

Set

• on <ramp_time (seconds)>
• off <ramp_time (seconds)>
• toggle
• night
• dim <percent(0..100)> [seconds(0..x)] [flags(l=long path|q=don't clear queue)]
  Will be replaced by brightness at some point
• dimup <percent change(0..100)> [seconds(0..x)]
  Special case: If percent change=100, seconds will be adjusted for actual change to go from current brightness.
• dimdown <percent change(0..100)> [seconds(0..x)]
  Special case: If percent change=100, seconds will be adjusted for actual change to go from current brightness.
• pair
  May not work properly. Sometimes it is necessary to use a remote to clear pairing first.
• unpair
  May not work properly. Sometimes it is necessary to use a remote to clear pairing first.
• restorePreviousState
  Set device to previous hsv state as stored in previousState reading.
• saveState
  Save current hsv state to savedState reading.
• restoreState
  Set device to saved hsv state as stored in savedState reading.
• preset (0..X|+)
  Load preset (+ for next preset).
• hsv <h(0..360)>,<s(0..100)>,<v(0..100)> [seconds(0..x)] [flags(l=long path|q=don't clear queue)]
  Set hsv value directly
• rgb RRGGBB [seconds(0..x)] [flags(l=long path|q=don't clear queue)]
  Set rgb value directly or using colorpicker.
• hue <(0..360)> [seconds(0..x)] [flags(l=long path|q=don't clear queue)]
  Set hue value.
• saturation <s(0..100)> [seconds(0..x)] [flags(q=don't clear queue)]
  Set saturation value directly
• discoModeUp
  Next disco Mode setting (for RGB and RGBW).
• discoModeDown
  Previous disco Mode setting (for RGB).
• discoSpeedUp
  Increase speed of disco mode (for RGB and RGBW).
• discoSpeedDown
  Decrease speed of disco mode (for RGB and RGBW).
• ct <3000-6500>
  Colour temperature 3000=Warm White,6500=Cold White (10 steps) (for White devices only).
• set extensions are supported.

Get

• rgb
• hsv

Attributes

• dimStep
  Allows you to modify the default dimStep if required.
• defaultRampOn
  Set the default ramp time if not specified for on command.
• defaultRampOff
  Set the default ramp time if not specified for off command.
• presets
  List of hsv presets separated by spaces (eg 0,0,100 9,0,50).
• colorCast
  Color shift values for red,yellow,green,cyan,blue,magenta (-29..29) for HSV color correction (eg 0,5,10,-5,0,0)
• gamma
  Set gamma correction value for device (eg 0.8)
• dimOffWhite
  Use a different switching logic for White bulbs to better handle packet loss.
• updateGroupDevices
  Update the state of single devices switched with slot 'A'.
• restoreAtStart
  Restore the state of devices at startup. Default 0 for slot 'A', 1 otherwise.
• defaultBrightness
  Set the default brightness if not known. (Default: 36)

Modbus

[EN DE]

Modbus defines a shared modbus i/o interface and functions to be called from other logical modules / devices. This low level module takes care of the communication with modbus devices and provides Get, Set and cyclic polling of Readings as well as formatting and input validation functions. The logical device modules for individual machines only need to define the supported modbus function codes and objects of the machine with the modbus interface in data structures. These data structures are then used by this low level module to implement Set, Get and automatic updateing of readings in a given interval.
This version of the Modbus module supports Modbus RTU and ASCII over serial / RS485 lines as well as Modbus TCP and Modbus RTU or RTU over TCP. It defines read / write functions for Modbus holding registers, input registers, coils and discrete inputs.

Prerequisites
• This module requires the Device::SerialPort or Win32::SerialPort module.

Define
define <name> Modbus <device>

A define of a low level io device based on this module is only necessary if a shared device like a RS485 USB adapter is used or if you need to pass several logical connections through a shared tcp connection e.g. to a gateway. This module will also be used as a library for other high level modules that define all the data objects.
Example:


define ModBusLine Modbus /dev/ttyUSB1@9600

In this example the module opens the given serial interface and other logical modules can access several Modbus devices connected to this bus concurrently. If your device needs special communications parameters like even parity you can add the number of data bits, the parity and the number of stopbits separated by commas after the baudrate e.g.:

define ModBusLine Modbus /dev/ttyUSB2@38400,8,E,2



Set-Commands

this low level device module doesn't provide set commands for itself but implements set for logical device modules that make use of this module. See ModbusAttr for example.

Get-Commands

this low level device module doesn't provide get commands for itself but implements get for logical device modules that make use of this module.

Attributes


• do_not_notify
• readingFnAttributes


• queueMax
  max length of the queue used for sending requests, defaults to 200.
• queueDelay
  modify the delay used when sending requests to the device from the internal queue, defaults to 1 second
• queueTimeout
  modify the timeout used to remove old entries in the send queue for requests. By default entries that cound not be sent for more than 20 seconds will be deleted from the queue
• enableQueueLengthReading
  if set to 1 the physical device will create a reading with the length of the queue used internally to send requests.
  
• busDelay
  defines a delay that is always enforced between the last read from the bus and the next send to the bus for all connected devices
• clientSwitchDelay
  defines a delay that is always enforced between the last read from the bus and the next send to the bus for all connected devices but only if the next send goes to a different device than the last one
• frameGap
  defines the time after which the read buffer is discarded if no frame has been received. This defaults to 1.5 seconds.
• dropQueueDoubles
  prevents new request to be queued if the same request is already in the send queue
• retriesAfterTimeout
  defines how often the module will try to resend a request after a timeout. This defaults to 0
• maxTimeoutsToReconnect
  defines that the module will disconnect and reconnect a connection after the given number of successive timeouts
• maxTimeoutstimeoutLogLevelToReconnect
  defines at which log level timeout messages will be logged. It defaults to 3 and could e.g. be set to 4.
• closeAfterResponse
  if this attribute is set to 1 then the module will only open a connection when it needs to send a request. After receiving the response the connection is closed unless the send queue contains more requests to be sent. This might be helpful if modbus TCP slaves have to be queried by multiple masters but the slave is unable to handle more than one connection at a time.
• nextOpenDelay
  delay in seconds that is passed to DevIo. It is enforced between successive calls to DevIo_Open.
• nextOpenDelay2
  delay in seconds to override nextOpenDelay in DevIo. This delay is enforced inside to Modbus module. Normally this attribute should never be needed.
• openTimeout
  timeout in seconds that is passed to DevIo.
• silentReconnect
  this attribute controls at what loglevel reconnect messages from devIO will be logged. Without this attribute they will be logged at level 3. If this attribute is set to 1 then such messages will be logged at level 4.
• showError
  if this attribute is set to 1 then a new reading LAST_ERROR will be created in case of errors or timeouts.
• skipGarbage
  If the module is used as master or if it is using Modbus ASCII as protocol, then the module will skip bytes received that can not be the start of correct frames.
  For Modbus ASCII it skips bytes until the expected starting byte ":" is seen. For Modbus RTU a response has to start with the id of the request that was sent before.
  If set to 1 this attribute will enhance the way the module treats Modbus request frames over serial lines in passive mode and a slave. It will then skip all bytes until a byte with a modbus id is seen that is used by a logical Fhem modbus device. Or if the last frame was a request, then it skips everything until the modbus id of this request is seen as the start of a response. Setting this attribuet to 1 might lead to more robustness, however when there are other slaves on the same bus, it might als create trouble when other slaves do not send responses.
  
• profileInterval
  if set to something non zero it is the time period in seconds for which the module will create bus usage statistics. Please note that this number should be at least twice as big as the interval used for requesting values in logical devices that use this physical device
  The bus usage statistics create the following readings:
  • Profiler_Delay_sum
  seconds used as delays to implement the defined delays like sendDelay and commDelay
  • Profiler_Fhem_sum
  seconds spend processing in the module
  • Profiler_Idle_sum
  idle time
  • Profiler_Read_sum
  seconds spent reading and validating the data read
  • Profiler_Send_sum
  seconds spent preparing and sending data
  • Profiler_Wait_sum
  seconds waiting for a response to a request
  • Statistics_Requests
  number of requests sent
  • Statistics_Timeouts
  timeouts encountered

ModbusAttr

ModbusAttr uses the low level Modbus module 98_Modbus.pm to provide a generic Modbus module (as master, slave, relay or passive listener) that can be configured by attributes similar to the way HTTPMOD works for devices with a web interface.
ModbusAttr can be used as a Modbus master (sometimes also called a Modbus client) that queries data from other devices over a serial RS232 / RS485 or TCP connection,
it can be used as a Modbus slave (sometimes also called a Modbus server) that can make readings of Fhem devices available via Modbus to external Modbus masters,
it can act as a Modbus relay that receives requests over one connection and forwards them over another connection (e.g. from Modbus TCP to serial Modbus RTU)
or it can passively listen to other devices that communicate over a serial RS485 connection and extract readings from the objects it sees.
The supported protocols are Modbus RTU, Modbus ASCII or Modbus TCP.
There are several attributes that modify the way data objects are converted before they are stored in readings or sent to a device. Data can be modified by a perl expression defined in an atribute, formatted with a format string defined in another attribute or mapped to a table defined in an attribute.
Readings can directly correspond to one data object or they can span several objects. A float value for example might be stored in two input or holding registers in the Modbus device. By specifying attributes that define the type of an object no perl coding is necessary.

Prerequisites
• This module requires the basic Modbus module which itsef requires DevIO which again requires Device::SerialPort or Win32::SerialPort module if you connect devices to a serial port (RS232 or RS485).

Define that Fhem acts as a Modbus master (sometimes called a Modbus client) that queries a slave (sometimes called a Modbus server)
define Modbus /dev/device@baudrate,bits,parity,stop
define <name> ModbusAttr <Id> <Interval>
or
define <name> ModbusAttr <Id> <Interval> <Address:Port> <RTU|ASCII|TCP>

In the first case the module connects as a master to the external Modbus slave device with Modbus Id <Id> through a serial modbus device (RS232 or RS485). Therefore a physical [[Modbus]] device is defined first
In the second case the module connects as a master directly through Modbus TCP or Modbus RTU or ASCII over TCP to a slave device in the network.
If <Interval> is not 0 then the module actively requests data from the external device every <Interval> seconds

The objects that the module should request and the readings it should create from these objects have to be defined with attributes (see below).
These attributes will define a mapping from so called "coils", "digital inputs", "input registers" or "holding registers" of the external device to readings inside Fhem together with the data type and format of the values.
Interval can be 0 in which case the Module only requests data when it is triggered with a Fhem get-Command.
With this mode a Fhem installation can for example query sensor data from a heating system, energy meter or solar power installation if these systems offer a Modbus interface.
Examples:


define ModbusLine Modbus /dev/ttyUSB1@9600
define WP ModbusAttr 1 60

Defines the Fhem device WP as a Modbus master that communicates through the Modbus serial interface device named ModbusLine to query a Modbus slave with id 1. The protocol defaults to Modbus RTU
or

define ModbusLine Modbus /dev/ttyUSB1@9600
define WP ModbusAttr 20 0 ASCII

Defines the Fhem device WP as a Modbus master that communicates through the Modbus serial interface device named ModbusLine with Modbus ASCII. Use Modbus Id 20 and don't query the device in a defined interval. Instead individual SET / GET options have to be used for communication.
or

define WP ModbusAttr 5 60 192.168.1.122:502 TCP

to talk Modbus TCP to a slave device with IP-Address 192.168.1.122 and the reserved port for Modbus TCP 502
Note that for Modbus over a TCP connection you don't need a basic Modbus device for the interface like ModbusLine above.
or

define WP ModbusAttr 3 60 192.168.1.122:8000 RTU

to talk Modbus RTU over TCP and use the port number 8000


Define that Fhem acts as a Modbus slave (=server) that can be queried by a Modbus master
define <name> ModbusAttr <Id> slave|server
or
define <name> ModbusAttr <Id> slave|server| <Address:Port> <RTU|ASCII|TCP>

The module waits for connections from other Modbus masters. It will respond to their requests if the requests contain the given Modbus <Id>
To provide data with Modbus to external Modbus masters a mapping needs to be defined using attributes. These attributes will define a mapping from Readings inside Fhem to so called "coils", "digital inputs", "input registers" or "holding registers" and their Modbus object address together with the data type and format of the values.
With this mode a Fhem installation can for example supply data to a PLC that actively reads data from Fhem or writes data to Fhem readings.
Examples:


define MRS485 Modbus /dev/ttyUSB2@9600,8,E,1
define Data4PLC ModbusAttr 1 slave

Define Data4PLC as a Modbus slave (the old name for sever) that communicates through the Modbus serial interface device named MRS485 to listen for Modbus requests with Id 1. The protocol defaults to Modbus RTU
or

define MRS485 Modbus /dev/ttyUSB2@9600,8,E,1
define Data4PLC ModbusAttr 20 slave ASCII

to listen for Modbus requests with Id 20 with Modbus ASCII.
or

define Data4PLC ModbusAttr 5 slave 192.168.1.2:502 TCP

to start listening to TCP port 502 on the local address 192.168.1.2. Modbus TCP will be used as protocol and requests with Modbus Id 5 will be answered.
Please be aware that opening a port number smaller than 1024 needs root permissions on Unix devices. So it is probably better to use a non standard port number above 1024 instead.
or

define Data4PLC ModbusAttr 3 slave 192.168.1.2:8000 RTU

to listen to the local port 8000 and talk Modbus RTU over TCP


Define as Modbus passive listener
define <name> ModbusAttr <Id> passive <RTU|ASCII|TCP>

The module listens on a serial (RS485) connection for modbus communication with the given Modbus <Id> and extracts readings. It does not send requests by itself but waits for another master (client) to communicate with a slave (server). So only objects that the other master requests can be seen by Fhem in this configuration.
The objects that the module recognizes and the readings that it should create from these objects have to be defined with attributes (see below) in the same way as for a Modbus master.
These attributes will define a mapping from so called "coils", "digital inputs", "input registers" or "holding registers" of the external device to readings inside Fhem together with the data type and format of the values.
With this mode a Fhem installation can for example listen to the communication between an energy counter as slave and a solar control system as master if they use Modbus RTU over RS485. Since only one Master is allowed when using Modbus over serial lines, Fhem can not be master itself. As a passive listener it can however see when the master queries e.g. the current power consumption and then also see the reply from the energy meter and store the value in a Fhem reading.
Examples:


define MB-485 Modbus /dev/ttyUSB2
define WP ModbusAttr 1 passive

to passively listen for Modbus requests and replies with Id 1 over a serial interface managed by an already defined basic modbus device named MB-485. The protocol defaults to Modbus RTU
or

define MB-485 Modbus /dev/ttyUSB2
define WP ModbusAttr 20 passive ASCII

to passivel listen for Modbus requests / replies with Id 20 and Modbus ASCII.


Define as Modbus relay
define <name> ModbusAttr <Id> relay to <FhemMasterDevice>
or
define <name> ModbusAttr <Id> relay <Address:Port> <RTU|ASCII|TCP> to <FhemMasterDevice>

The module waits for connections from other Modbus masters. It will forward requests if they match the given Modbus <Id> to an already defined Modbus Master device inside Fhem which will send them to its defined slave, take the reply and then pass it back to the original Master.
With this mode a Fhem installation can for example be used in front of a device that only speaks Modbus RTU over RS485 to make it available via Modbus TCP over the local network.
Examples:


define MB-485 Modbus /dev/ttyUSB2
define Heating ModbusAttr 22 0
define Relay ModbusAttr 33 relay 192.168.1.2:1502 TCP to Heating

Defines MB-485 as a base device for the RS-485 communication with a heating system,
defines Heating as a Modbus Master to communicate with the heating and its Modbus ID 22,
and then defines the relay which listens to the local IP address 192.168.1.2, TCP port 1502, Modbus Id 33 and protocol Modbus-TCP.
Requests coming in through Modbus TCP and port 1502 are then translated to Modbus RTU and forwarded via RS-485 to the heating system with Modbus Id 22.
or (unlikely)

define MB-232 Modbus /dev/ttyUSB2@19200
define Solar ModbusAttr 7 0 192.168.1.122:502 RTU
define PLC2NetRelay ModbusAttr 1 ASCII relay to Solar

Defines MB-232 as a base device for the RS-232 communication with a PLC as Modbus master,
defines Solar as a Modbus Master to communicate with Modbus TCP to a Solar power system at IP Adrress 192.168.1.122 and its Modbus ID 7,
and then defines the PLC2NetRelay as a relay which listens to Modbus-ASCII requests over the serial RS-232 link from a PLC to Modbus ID 1.
Requests to Modbus Id 1 coming in through the serial link are then translated to Modbus TCP and forwarded over the network to the solar power system with Modbus Id 7.


Configuration of the module as master or passive listener
Data objects (holding registers, input registers, coils or discrete inputs) are defined using attributes. If Fhem is Modbus master or passive listener, the attributes assign data objects of external devices (heating systems, power meters, PLCs or other) with their register addresses to readings inside fhem and control how these readings are calculated from the raw values and how they are formatted.
Please be aware that Modbus does not define common data types so the representation of a value can be very different from device to device. One device might make a temperature value avaliable as a floating point value that is stored in two holding registers, another device might store the temperature multiplied with 10 as an signed integer in one register. Even the order of bytes can vary.
Therefore it is typically necessary to specify the data representation as a Perl unpack code.
A Modbus master can also write values to Objects in the device and attributes define how this is done.

Example for a Modbus master or passive configuration:


        define PWP ModbusAttr 5 30
        attr PWP obj-h256-reading Temp_Wasser_ein
        attr PWP obj-h256-type signed short big
        attr PWP obj-h256-expr $val/10

        attr PWP obj-h258-reading Temp_Wasser_Aus
        attr PWP obj-h258-type signed short big
        attr PWP obj-h258-expr $val/10

        attr PWP obj-h262-reading Temp_Luft
        attr PWP obj-h262-type signed short big
        attr PWP obj-h262-expr $val / 10

        attr PWP obj-h770-reading Temp_Soll
        attr PWP obj-h770-type signed short big
        attr PWP obj-h770-expr $val / 10
        attr PWP obj-h770-set 1
        attr PWP obj-h770-setexpr $val * 10
        attr PWP obj-h770-max 32
        attr PWP obj-h770-min 10
        attr PWP obj-h770-hint 8,10,20,25,28,29,30,30.5,31,31.5,32

        attr PWP dev-h-combine 5
        attr PWP dev-h-defPoll 1

        attr PWP room Pool-WP
        attr PWP stateFormat {sprintf("%.1f Grad", ReadingsVal($name,"Temp_Wasser_Ein",0))}
        attr PWP webCmd Temp_Soll
        

Attributes to define data objects start with obj- followed by a code that identifies the type and address of the data object.
Modbus devices offer the following types of data objects:
• holding registers (16 bit objects that can be read and written)
• input registers (16 bit objects that can only be read)
• coils (single bit objects that can be read and written)
• discrete inputs (single bit objects that can only be read)

The module uses the first character of these data object types to define attributes. Thus h770 refers to a holding register with the decimal address 770 and c120 refers to a coil with address 120. The address has to be specified as pure decimal number. The address counting starts at address 0

Please note that the documentation for devices sometimes uses different numbering. They might start counting with one instead of zero so if a voltage value is stored in input register number 107 according to the documentation of the device, it might technically mean register number 106 (in the Modbus protocol specification addresses start with 0).
Also some vendors use hexadecimal descriptions of their register addresses. So input register 107 might be noted as hex and means 263 or even 262 as decimal address.
attr PWP obj-h258-reading Temp_Wasser_Aus defines a reading with the name Temp_Wasser_Aus that is read from the Modbus holding register at address 258.
The attributes ending on -type specify the data type. In the above example signed short big is a 16 bit signed integer in big endian byte ordering. this information is used by the modbus module to select the correct perl unpack code and length. instead of using a -type attribute it is also possible to specify this unpack code and length explixitely (in older versions of the Fhem Modbus module this was necessary)
With the attribute ending on -expr you can define a perl expression to do some conversion or calculation on the raw value read from the device. In the above example the raw value has to be devided by 10 to get the real value. If the raw value is also the final value then no -expr attribute is necessary.

An object attribute ending on -set creates a fhem set option which allows the user to issue a set command which then sends a Modbus write request to the device. In the above example the reading Temp_Soll can be changed to 12 degrees by the user with the fhem command set PWP Temp_Soll 12
The object attributes ending on -min and -max define min and max values for input validation and the attribute ending on -hint will tell fhem to create a selection list so the user can graphically select the defined values.

To define general properties of the device you can specify attributes starting with dev-. E.g. with dev-timing-timeout you can specify the timeout when waiting for a response from the device. With dev-h- you can specify several default values or general settings for all holding registers like the function code to be used when reading or writing holding registers. These attributes are optional and the module will use defaults that work in most cases.
dev-h-combine 5 for example allows the module to combine read requests to objects having an address that differs 5 or less into one read request. Without setting this attribute the module will start individual read requests for each object. Typically the documentation for the modbus interface of a given device states the maximum number of objects that can be read in one function code 3 request.


Handling Data Types
The Modbus protocol does not define data types. If the documentation of a device states that for example the current temperature is stored in holding register 102 this leaves room for many interpretations. Not only can the address 102 mean different things (actually decimal 102 or rather 101 if the vendor starts counting at 1 instead of 0 or even 257 or 258 if the vendor used hexadecimal addresses in his documentation ) also the data representation can be many different things. As in every programming language, there are many ways to represent numbers. They can be stored signed or unsigned, they can be integers or floating point numbers, the byte-order can be "big endian" or "small endian", the value can be stored in one holding register or in two holding registers (floating point numbers typically take four bytes which means two holding registers).
The Modbus module allows flexible configuration of data representations by assigning a predefined type and by assigning a Perl unpack-code, a length, a Perl Expression, and the register ordering. The following example illustrates how this can be done:


        attr PWP obj-h338-reading Pressure
        attr PWP obj-h338-len 2
        attr PWP obj-h338-unpack f>
        attr PWP obj-h338-revRegs 1
        attr PWP obj-h338-format %.2f
        

In This example a floating point value for the reading "Pressure" is read from the holding registers starting at address 338. The value occupies 32 Bits and is therefore stored in two registers. The Perl pack code to use is f> which means a native single precision float in big endian format (byte order). With revRegs the module is instructed to reverse the order of the registers directly after reading. The format specification then defines how the value is formatted into a reading - in this case with two digits after the comma. See http://perldoc.perl.org/functions/pack.html for Perl pack / unpack codes and http://perldoc.perl.org/functions/sprintf.html for format specifications.

If you need to read / write many objects for a device, defining all these parameters each time is not elegant. The Modbus module therefore offers two ways to simplify this task:
You can use defaults for every type of object or you can use predefined types or define your own data types once and then refer to them.
This exampe shows how defaults can be specified for holding registers and input registers:


        attr PWP dev-h-defUnpack f>
        attr PWP dev-h-defLen 2
        attr PWP dev-h-defRevRegs 1
        attr PWP dev-h-defFormat %.2f
        
        attr PWP dev-i-defUnpack n
        attr PWP dev-i-defLen 1
        

The next example shows how you can define your own data types and then apply them to objects:


        attr WP dev-type-VT_R4-format %.1f
        attr WP dev-type-VT_R4-len 2
        attr WP dev-type-VT_R4-revRegs 1
        attr WP dev-type-VT_R4-unpack f>
        
        attr WP obj-h1234-reading Temp_In
        attr WP obj-h1234-type VT_R4
        attr WP obj-h1236-reading Temp_Out
        attr WP obj-h1236-type VT_R4
        

This example defines a data type with the name VT_R4 which uses an unpack code of f>, length 2 and reversed register ordering. It then assigns this Type to the objects Temp_In and Temp_Out.

The following data types are already defined and can directly be used instead of specifying unpack codes and lengths:

• signed short big
16 bits signed integer in big endian byte ordering (high, low)
• unsigned short big
16 bits unsigned integer in big endian byte ordering
• signed short little
16 bits signed integer in vax / little endian byte ordering (low high)
• unsigned short little
16 bits unsigned integer in vax / little endian byte ordering (low high)
• signed long big
32 bits signed integer in big endian byte ordering (high, low), occupies two registers
• unsigned long big
32 bits unsigned integer in big endian byte ordering, occupies two registers
• signed long little
32 bits signed integer in vax / little endian byte ordering (low high), occupies two registers
• unsigned long little
32 bits unsigned integer in vax / little endian byte ordering (low high), occupies two registers
• float32 big
32 bits floating point number in big endian byte ordering, occupies two registers
• float32 little
32 bits floating point number in vax / little endian byte ordering (low high), occupies two registers
• float64 big
64 bits floating point number in big endian byte ordering, occupies four registers
• float64 little
64 bits floating point number in vax / little endian byte ordering (low high), occupies four registers
• string
string with default lenght 2 so the length should be overwritten as needed
additionally there are some predefined abbreviations / aliases for these predefined data types. For exmple the word big can be omitted so unsigned short is the same as unsigned short big or real is an alias for float32 big and double is an alias for floa64 big.

Configuration of the module as Modbus slave (server)
Data objects that the module offers to external Modbus masters (holding registers, input registers, coils or discrete inputs) are defined using attributes. If Fhem is Modbus slave, the attributes assign readings of Fhem devices to Modbus objects with their addresses and control how these objects are calculated from the reading values that exist in Fhem.
It is also possible to allow an external Modbus master to send write function codes and change the value of readings inside Fhem. Example for a Modbus slave configuration:


        define MRS485 Modbus /dev/ttyUSB2@9600,8,E,1
        define Data4PLC ModbusAttr 1 slave
        attr Data4PLC IODev MRS485
        
        attr Data4PLC obj-h256-reading THSensTerrasse:temperature
        attr Data4PLC obj-h256-unpack f
        attr Data4PLC obj-h256-len 2
        
        attr Data4PLC obj-h258-reading THSensTerrasse:humidity
        attr Data4PLC obj-h258-unpack f
        attr Data4PLC obj-h258-len 2
        
        attr Data4PLC obj-h260-reading myDummy:limit
        attr Data4PLC obj-h260-unpack n
        attr Data4PLC obj-h260-len 1
        attr Data4PLC obj-h260-allowWrite 1
        

In this example Fhem allows an external Modbus master to read the temperature of a Fhem device named THSensTerrasse through holding register 256 and the humidity of that Fhem device through holding register 258. Both are encoded as floting point values that span two registers.
Instead of specifying unpack codes and lengths predefined data types could be used here as well. The master can also read but also write the reading named limit of the device myDummy.

Set-Commands for Fhem as Modbus master operation
are created based on the attributes defining the data objects.
Every object for which an attribute like obj-xy-set is set to 1 will create a valid set option.
Additionally the attribute enableControlSet enables the set options interval, stop, start, reread as well as scanModbusObjects, scanStop and scanModbusId (for devices connected with RTU / ASCII over a serial line).
Starting with Version 4 of the Modbus module enableControlSet defaults to 1.

• interval <Interval>
modifies the interval that was set during define.
• stop
stops the interval timer that is used to automatically poll objects through modbus.
• start
starts the interval timer that is used to automatically poll objects through modbus. If an interval is specified during the define command then the interval timer is started automatically. However if you stop it with the command set <mydevice> stop then you can start it again with set <mydevice> start.
• reread
causes a read of all objects that are set to be polled in the defined interval. The interval timer is not modified.

• scanModbusObjects <startObj> - <endObj> <reqLen>
scans the device objects and automatically creates attributes for each reply it gets. This might be useful for exploring devices without proper documentation. The following example starts a scan and queries the holding registers with addresses between 100 and 120.
set MyModbusAttrDevice scanModbusObjects h100-120
For each reply it gets, the module creates a reading like
scan-h100 hex=0021, string=.!, s=8448, s>=33, S=8448, S>=33
the representation of the result as hex is 0021 and the ASCII representation is .!. s, s>, S and S> are different representations with their Perl pack-code.
• scanModbusId <startId> - <endId> <knownObj>
scans for Modbus Ids on an RS485 Bus. The following set command for example starts a scan:
set Device scanModbusId 1-7 h770
since many modbus devices don't reply at all if an object is requested that does not exist, scanModbusId needs the adress of an object that is known to exist. If a device with Id 5 replies to a read request for holding register 770, a reading like the following will be created:
scanId-5-Response-h770 hex=0064, string=.d, s=25600, s>=100, S=25600, S>=100
• scanStop
stops any running scans.
• saveAsModule <name>
experimental: saves the definitions of obj- and dev- attributes in a new fhem module file as /tmp/98_ModbusGen<name>.pm.
if this file is copied into the fhem module subdirectory (e.g. /opt/fhem/FHEM) and fhem is restarted then instead of defining a device as ModbusAttr with all the attributes to define objects, you can just define a device of the new type ModbusGen<name> and all the objects will be there by default. However all definitions can still be changed / overriden with the attribues defined in ModbusAttr if needed.

Get-Commands for Modbus master operation

All readings are also available as Get commands. Internally a Get command triggers the corresponding request to the device and then interprets the data and returns the right field value. To avoid huge option lists in FHEMWEB, the objects visible as Get in FHEMWEB can be defined by setting an attribute obj-xy-showGet to 1.

custom function codes

if a device supports special function codes beyond 1-6 and 15-17 then they can be defined and used with attributes that define how the requests and replies for such function codes are constructed and how they can be parsed.

simple example for a function code that does not contain data:


        attr Master dev-fc66Request-unpack none
        attr Master dev-fc66Response-unpack none
        
        attr Master obj-h9999-reading Reset
        attr Master obj-h9999-set 1
        attr Master obj-h9999-overrideFCwrite 66
        

the unpack none specifies that there is no field in the request with function code 66, the message just consists of the function code and the checksum for modbus RTU.
To use a custom function code, it can be assigned to an individual virtual object with the obj-XY-overrideFCwrite attribute so a set command to this object will use the custom function code and pass the objects type, address and length via the fields TYPE, ADR and LEN. In the above example TYPE, ADR and LEN are not even used.

The next example defines function code 93 for a master which behaves just like function code 3 to read holding registers:


        attr Master dev-fc93Request-unpack nn
        attr Master dev-fc93Request-fieldList ADR, LEN

        attr Master dev-fc93Response-unpack Ca*
        attr Master dev-fc93Response-fieldList LEN, VALUES
        attr Master dev-fc93Response-fieldExpr-PDULEXP $pduHash->{LEN} + 2
        attr Master dev-fc93Response-fieldExpr-TYPE 'h'
        

the relevant part for a custom function code request and response is the part between the modbus id and the checksum (for RTU). This part is defined with an unpack code and a list of Fields that correspond to the fields defined by the unpack code elements.
See the Modbus specification for details on how the request and response looks like for function code 3
Possible fields for custom function codes are ADR, LEN, TYPE, VALUES and PDULEXP.

Example for a slave:

        attr Slave  dev-fc93Request-unpack nn
        attr Slave  dev-fc93Request-fieldList ADR, LEN
        attr Slave  dev-fc93Request-fieldExpr-PDULEXP 5
        attr Slave  dev-fc93Request-fieldExpr-TYPE 'h'

        attr Slave  dev-fc93Response-unpack Ca*
        attr Slave  dev-fc93Response-fieldList LEN, VALUES
        attr Slave  dev-fc93Response-fieldExpr-LEN $val * 2;
        

The unpack code nn stands for two 16 bit unsigned numbers.
The field TYPE is set with a Perl expression to h (in this case only the constant h)
ADR, LEN specify that the numbers unpacked are the holding register address and the length in registers.
The field PDULEXP is the expected length of the PDU including the leading Modbus ID byte.
For the response this expected PFU length is calculated by adding 2 to the unpacked field LEN For the slave the length field LEN is doubled because in the protocol for function code 3 it means the length in bytes whereas in the module the length means the number of 16 bit registers.
If during parsing the fields TYPE, ADR and VALUES are set and there is an object / reading with that type and address defined, then the field VALUES is passed on for interpretation as this object.


Attributes


• do_not_notify
• readingFnAttributes


• alignTime
  Aligns each periodic read request for the defined interval to this base time. This is typcally something like 00:00 (see the Fhem at command)
• enableControlSet
  enables the built in set commands like interval, stop, start and reread (see above).
  Starting with Version 4 of the Modbus module enableControlSet defaults to 1. This attribute can however be used to disable the set commands by setting the attribute to 0
  
  
• showError
  if this attribute is set to 1 then a reading with the name LAST_ERROR will be created when a timeout occurs or when a Modbus reply conatins an error code
  

please also notice the attributes for the physical modbus interface as documented in 98_Modbus.pm
the following list of attributes can be applied to any data object by specifying the objects type and address in the variable part. For many attributes you can also specify default values per object type (see dev- attributes later) or you can specify an object attribute without type and address (e.g. obj-len) which then applies as default for all objects:
• obj-[cdih][0-9]+-reading
  define the name of a reading that corresponds to the modbus data object of type c,d,i or h and a decimal address (e.g. obj-h225-reading).
  For master or passive operation this reading name will be used to create a reading for the modbus device itself.
  For slave operation this can also be specified as deviceName:readingName to refer to the reading of another device inside Fhem whose value can be queried by an external Modbus master with the goven type and address.
  
• obj-[cdih][0-9]+-name
  defines an optional internal name of the data object of type c,d,i or h and a decimal address (e.g. obj-h225-name).
  This has no meaning for fhem and serves mainly documentation purposes.
  
• obj-[cdih][0-9]+-set
  if set to 1 then this data object (e.g. obj-h225) can be changed with a Fhem set command which results in a modbus write request sent to the external slave device.
  (works only if this device is a modbus master and for holding registers and coils since discrete inputs and input registers can not be modified by definition).
  
• obj-[cdih][0-9]+-min
  this defines a lower limit to the value of this data object (e.g. obj-h225-min).
  If in master mode this applies to values written with a Fhem set command to an external slave device and is used for input validation.
  If in slave mode this applies to values written by an external master device to Fhem readings.
  
• obj-[cdih][0-9]+-max
  this defines an upper limit to the value of this data object (e.g. obj-h225-max)
  If in master mode this applies to values written with a Fhem set command to an external slave device and is used for input validation.
  If in slave mode this applies to values written by an external master device to Fhem readings.
  
• obj-[cdih][0-9]+-hint
  this is used in master mode for set options and tells fhemweb what selection to display for the set option (list or slider etc.)
  Example: attr MBTest obj-h225-hint slider,5,1,75
• obj-[cdih][0-9]+-expr
  In master mode this defines a perl expression that converts the raw value read from an external slave device into a value that is stored in a Fhem reading.
  In slave mode this defines a perl expression that converts the raw value written from an external master device into a value that is stored in a Fhem reading.
  Inside the expression you can use $val to get the value or the array @val in case there are several values (e.g. when unpack produces more than one value)
  Example: attr MBTest obj-h225-expr $val * 2
• obj-[cdih][0-9]+-setexpr
  In master mode this defines a perl expression that converts the user specified value from the set command to a raw value that can be sent to the external slave device with a write function code.
  In slave mode this defines a perl expression that converts the value of a reading inside Fhem to a raw value that can be sent to the device as a response to the read function code received from the external master device.
  This is typically the inversion of -expr above.
  Inside the expression you can use $val to get the value or the array @val in case there are several values (e.g. when unpack produces more than one value)
  Example: attr MBTest obj-h225-setexpr $val / 2
• obj-[cdih][0-9]+-allowWrite
  this only applies to a Fhem Modbus device in slave mode. If set to 1 it defines that a reading can be changed with a write function code by an external modbus master.
  Example: attr MBTest obj-h333-allowWrite 1
• obj-[cdih][0-9]+-ignoreExpr
  defines a perl expression that returns 1 if a value should be ignored and the existing reading should not be modified
  In master mode this applies to values read from an external slave device.
  In slave mode this applies to values written to Fhem readings by an external master device.
  Inside the expression you can use $val to get the value or the array @val in case there are several values (e.g. when unpack produces more than one value)
  Example: attr MBTest obj-h333-ignoreExpr $val > 100
• obj-[cdih][0-9]+-map
  In master mode defines a map to convert raw values read from an external device to more convenient strings that are then stored in Fhem readings or back (as reversed map) when a value to write has to be converted from the user set value to a raw value that can be written.
  In slave mode defines a map to convert raw values received from an external device with a write function code to more convenient strings that are then stored in Fhem readings
  or back (as reversed map) when a value to read has to be converted from the Fhem reading value to a raw value that can be sent back as response.
  Example: attr MBTest obj-h225-map 0:mittig, 1:oberhalb, 2:unterhalb
• obj-[cdih][0-9]+-mapDefault
  defines a default value to be used with a map (for output manipulation). This value will be returned if there is no match in the map
  Example: attr MBTest obj-h225-mapDefault other
• obj-[cdih][0-9]+-rmapDefault
  defines a default value to be used with a reverse map (e.g. for input validation). This value will be returned if there is no match in the map Example: attr MBTest obj-h225-rmapDefault 0
• obj-[cdih][0-9]+-format
  In master mode this defines a format string (see Perl sprintf) to format a value read from an external slave device before it is stored in a reading e.g. %.1f
  In slave mode this defines a format string to format a value from a Fhem reading before it is sent back in a response to an external master
  Example: attr MBTest obj-h225-format %.1f
• obj-[cdih][0-9]+-len
  defines the length of the data object in registers (16 Bits). It defaults to 1.
  Some devices store e.g. 32 bit floating point values in two registers. In this case you should set this attribute to two.
  This setting is relevant both in master and in slave mode. The lenght has to match the length implied by the unpack code.
  Example: attr MBTest obj-h225-len 2
• obj-[cdih][0-9]+-unpack
  defines the pack / unpack code to convert data types.
  In master mode it converts the raw data string read from the external slave device to a reading or to convert from a reading to a raw format when a write request is sent to the external slave device.
  In slave mode it converts the value of a reading in Fhem to a raw format that can be sent as a response to an external Modbus master or it converts the raw data string read from the external master device to a reading when the master is using a write function code and writing has been allowed.
  For an unsigned integer in big endian format this would be "n",
  for a signed 16 bit integer in big endian format this would be "s>", in little endian format it would be "s<"
  and for a 32 bit big endian float value this would be e.g. "f>". (see the perl documentation of the pack function for more codes and details).
  Please note that you also have to set a -len attribute (for this object or for the device) if you specify an unpack code that consumes data from more than one register.
  For a 32 bit float e.g. len should be 2.
  Example: attr MBTest obj-h225-unpack n
• obj-[cdih][0-9]+-revRegs
  this is only applicable to objects that span several input registers or holding registers.
  When they are received from an external device then the order of the registers will be reversed before further interpretation / unpacking of the raw register string. The same happens before data is sent to an external device
  Example: attr MBTest obj-h225-revRegs 1
• obj-[cdih][0-9]+-bswapRegs
  After registers have been received and before they are sent, the byte order of all 16-bit values are swapped. This changes big-endian to little-endian or vice versa. This functionality is most likely used for reading (ASCII) strings from devices where they are stored as big-endian 16-bit values.
  Example: original reading is "324d3130203a57577361657320722020". After applying bswapRegs, the value will be "4d3230313a2057576173736572202020" which will result in the ASCII string "M201: WWasser ". Should be used with "(a*)" as -unpack value.
  Example: attr MBTest obj-h225-bswapRegs 1
• 
  defines an encoding to be used in a call to the perl function decode to convert the raw data string received from a device. This can be used if the device delivers strings in an encoding like cp850 instead of utf8.
  Example: attr MBTest obj-h225-decode cp850
• obj-[cdih][0-9]+-encode
  defines an encoding to be used in a call to the perl function encode to convert raw data strings received from a device. This can be used if the device delivers strings in an encoding like cp850 and after decoding it you want to reencode it to e.g. utf8.
  Example: attr MBTest obj-h225-encode utf8
• obj-[ih][0-9]+-type
  defines that this object has a predefined or user defined data type. Data types can be defined using the dev-type- attribues.
  If a device with many objects uses for example floating point values that span two swapped registers with the unpack code f>, then instead of specifying the -unpack, -revRegs, -len, -format and other attributes over and over again, you could define a data type with attributes that start with dev-type-VT_R4- and then use this definition for each object as e.g. obj-h1234-type VT_R4
  example:
  

              attr WP dev-type-VT_R4-format %.1f
              attr WP dev-type-VT_R4-len 2
              attr WP dev-type-VT_R4-revRegs 1
              attr WP dev-type-VT_R4-unpack f>
              
              attr WP obj-h1234-reading Temp_Ist
              attr WP obj-h1234-type VT_R4
              

  
  see above for a list of predefined data types.
• obj-[cdih][0-9]+-showGet
  If the Fhem Modbus device is in master mode, every reading can also be requested by a get command. However these get commands are not automatically offered in fhemweb. By specifying this attribute, the get will be visible in fhemweb.
  Example: attr MBTest obj-h225-showGet 1
• obj-[cdih][0-9]+-poll
  If the Fhem Modbus device is in master mode, Fhem automatically creates read requests to the external modbus slave. If this attribute is set to 1 for an object then this obeject is included in the cyclic update request as specified in the define command for a Modbus master. If not set, then the object can manually be requested with a get command, but it is not automatically updated each interval. Note that this setting can also be specified as default for all objects with the dev- atributes described later.
  This attribute is ignored in slave mode.
  Example: attr MBTest obj-h225-poll 1
• obj-[cdih][0-9]+-polldelay
  this applies only to master mode. It allows to poll objects at a lower rate than the interval specified in the define command. You can either specify a time in seconds or number prefixed by "x" which means a multiple of the interval of the define command.
  If you specify a normal numer then it is interpreted as minimal time between the last read and another automatic read.
  Please note that this does not create an additional interval timer. Instead the normal interval timer defined by the interval of the define command will check if this reading is due or not yet. So the effective interval will always be a multiple of the interval of the define.
  If this attribute is set to "once" then the object will only be requested once after a restart.
  Example: attr MBTest obj-h225-pollDelay x3
• obj-[cdih][0-9]+-group
  Allows control over the way how objects are combined in one request and in which order they are processed when the response comes in.
  example:
  

              
              attr MyMaster obj-h100-reading Temp
              attr MyMaster obj-h100-unpack f>
              attr MyMaster obj-h100-len 2
              attr MyMaster obj-h100-format %.2f
              attr MyMaster obj-h100-poll 1
              attr MyMaster obj-h100-expr ReadingsVal($name, 'TempMultiplyer', 1) * $val
              attr MyMaster obj-h100-group 1-2
              attr MyMaster obj-h102-reading TempMultiplyer
              attr MyMaster obj-h102-unpack f>
              attr MyMaster obj-h102-len 2
              attr MyMaster obj-h102-poll 1
              attr MyMaster obj-h102-group 1-1
              attr MyMaster dev-h-combine 8
              

  
  this will cause the holding registers 100 and 102 to be read together. When the response is received, register 102 will be processed first so when register 100 is processed, its value can be multipied with the already updated reading for register 102.
  This is helpful for devices where readings need to be computed out of several registers that need to be requested together and where the order of processing is important.
• obj-[cdih][0-9]+-overrideFCread and obj-[cdih][0-9]+-overrideFCwrite
  allow overwriting a function call number to be used when reading or writing an individual object.
  Please do not use this attribute unless you understand the modbus protocol and its function codes.
• dev-([cdih]-)?read
  specifies the function code to use for reading this type of object in master mode. The default is 3 for holding registers, 1 for coils, 2 for discrete inputs and 4 for input registers.
  
• dev-([cdih]-)?write
  specifies the function code (decimal) to use for writing this type of object in master mode. The default is 6 for holding registers and 5 for coils. Discrete inputs and input registers can not be written by definition.
  Some slave devices might need function code 16 for writing holding registers. In this case dev-h-write can be set to 16.
  Example: attr MBTest dev-h-write 16
• dev-([cdih]-)?combine
  This applies only to master mode. It defines how many adjacent objects of an external slave device can be read in one request. If not specified, the default is 1
  If this value is too big, some data will not be read.
  Example: attr MBTest dev-h-combine 8
• dev-([cdih]-)?addressErrCode
  This applies only if the Fhem Modbus device is in slave mode. defines which error code to send back to a master that requests an object with an address that is not configured in Fhem.
  If nothing is specified, the error code 2 is used. If 0 is specified, then no error is sent back.
  
• dev-([cdih]-)?valueErrCode
  This applies only if the Fhem Modbus device is in slave mode. It defines which error code to send back to a master that tries to write a value to an object / reading where the value is lower than the specified minimum value or higher than the specified maximum value. (this feature is not implemented yet)
  If nothing is specified, the error code 1 is used. If 0 is specified, then no error is sent back.
  
• dev-([cdih]-)?notAllowedErrCode
  This applies only if the Fhem Modbus device is in slave mode. It defines which error code to send back to a master that tries to write to an object / reading where writing has not been allowed with the .
  If nothing is specified, the error code 1 is used. If 0 is specified, then no error is sent back.
  
• dev-([cdih]-)?defLen
  defines the default length for this object type. If not specified, the default is 1
  Example: attr MBTest dev-h-defLen 2
• dev-([cdih]-)?defFormat
  defines a default format string to use for this object type in a sprintf function on the values read from the device.
  Example: attr MBTest dev-h-defFormat %.1f
• dev-([cdih]-)?defExpr
  defines a default Perl expression to use for this object type to convert raw values read. (see obj-...-expr)
  Example: attr MBTest dev-h-defExpr $val / 10
• dev-([cdih]-)?defSetexpr
  defines a default Perl expression to use like -setexpr (see obj-...-setexpr)
  Example: attr MBTest dev-h-defSetexpr $val * 10
• dev-[cdih][0-9]+-defAllowWrite
  this only applies to a Fhem Modbus device in slave mode.
  If set to 1 it defines that readings can be changed with a write function code by an external modbus master.
  
• dev-([cdih]-)?defIgnoreExpr
  defines a default Perl expression to decide when values should be ignored.
  
• dev-([cdih]-)?defUnpack
  defines the default unpack code for this object type.
  Example: attr MBTest dev-h-defUnpack f>
• dev-([cdih]-)?defRevRegs
  defines that the order of registers for objects that span several registers will be reversed before further interpretation / unpacking of the raw register string
  
• dev-([cdih]-)?defBswapRegs
  per device default for swapping the bytes in Registers (see obj-bswapRegs above)
  
• dev-([cdih]-)?defDecode
  defines a default for decoding the strings read from a different character set e.g. cp850
  
• dev-([cdih]-)?defEncode
  defines a default for encoding the strings read (or after decoding from a different character set) e.g. utf8
  
• dev-([cdih]-)?defPoll
  if set to 1 then all objects of this type will be included in the cyclic update by default.
  Example: attr MBTest dev-h-defPoll 1
• dev-([cdih]-)?defPolldelay
  sets a default for obj-x-polldelay attributes
• dev-([cdih]-)?defShowGet
  if set to 1 then all objects of this type will have a visible get by default.
  Example: attr MBTest dev-h-defShowGet 1
• dev-([cdih]-)?defHint
  defines a default hint for all objects of this type
• dev-([cdih]-)?defSet
  defines a default for allowing set commands to all objects of this type Example: attr MBTest dev-h-defSet 1
• dev-type-XYZ-unpack, -len, -encode, -decode, -revRegs, -bswapRegs, -format, -expr, -map
  define the unpack code, length and other details of a user defined data type. XYZ has to be replaced with the name of a user defined data type. use obj-h123-type XYZ to assign this type to an object.
  see here
• dev-([cdih]-)?allowShortResponses
  if set to 1 the module will accept a response with valid checksum but data lengh < lengh in header
  
• dev-d-brokenFC2
  if set to doepke the module will change the parsing of function code 2 responses for devices that send an additional dummy zero byte before the correct response data byte
  
• dev-h-brokenFC3
  if set to 1 the module will change the parsing of function code 3 and 4 responses for devices that send the register address instead of the length in the response
  
• dev-c-brokenFC5
  if set the module will use the hex value specified here instead of ff00 as value 1 for setting coils
  
• dev-timing-timeout
  timeout for the device when a Fhem master waits for a slave response (defaults to 2 seconds)
  
• dev-timing-serverTimeout
  timeout for a TCP connected Fhem slave before it closes a TCP connection after inactivity
  
• dev-timing-sendDelay
  delay to enforce between sending two requests to the device. Default ist 0.1 seconds.
  
• dev-timing-commDelay
  delay between the last read and a next request. Default ist 0.1 seconds.
  
• queueMax
  max length of the queue for sending modbus requests as master, defaults to 200.
  This atribute should be used with devices connected through TCP or on physical devices that are connected via serial lines but not on logical modbus devices that use another physical device as IODev.
  
• nextOpenDelay
  delay for Modbus-TCP connections. This defines how long the module should wait after a failed TCP connection attempt before the next reconnection attempt. This defaults to 60 seconds.
• nextOpenDelay2
  delay for Modbus-TCP connections. This defines how long the module should wait after any TCP connection attempt before the next reconnection attempt. This defaults to 2 seconds.
• openTimeout
  timeout to be used when opening a Modbus TCP connection (defaults to 3)
• timeoutLogLevel
  log level that is used when logging a timeout. Defaults to 3.
• silentReconnect
  if set to 1, then it will set the loglevel for "disconnected" and "reappeared" messages to 4 instead of 3. This is especially useful when TCP slaves discoonect after an inactivity timeout.
• maxTimeoutsToReconnect
  this attribute is only valid for TCP connected devices. In such cases a disconnected device might stay undetected and lead to timeouts until the TCP connection is reopened. This attribute specifies after how many timeouts an automatic reconnect is tried.
• closeAfterResponse
  if set to 1, then Fhem as Master will close TCP connections to Slaves after it received the response and automatically reopen the connection to the slave when the next request has to be sent.
• nonPrioritizedSet
  if set to 1, then set commands will not be sent on the bus before other queued requests and the response will not be waited for.
• nonPrioritizedGet
  if set to 1, then get commands will not be blocking and the response will not be waited for.
• sortUpdate
  this attribute has become obsolte. The requests during a getUpdate cycle will always be sorted before beeing queued.
• cacheUpdateHash
  if this attribute is set to 1 then then Fhem as Modbus-Master will ignore any pollDelays, cache the list of combined objects to be requested and request this list in all subsequent getUpdate rounds in the defined interval. It has no effect on explicit get commands.
  This will result in increased memory usage and potentially some performance increase.
• cacheParseInfo
  if this attribute is set to 1 then then Fhem will cache the information regarding parsing each object in a hash which results in increased memory usage and potentially some performance increase.
• propagateVerbose
  this attribute causes changes to the verbose attribute of a logical device to be propagated to the physical io device or if the logical device is a relay device to the master device used by the relay.
• connectionsRoom
  defines to which room a TCP connection device for TCP slaves or relays is assigned to. When a TCP slave accepts a connection then the new temporary connection device is by default assigned to the room "Connections". If this attribute is set to "none" then no room attribute is set for connection devices by the module and fhem will automatically use the room 'hidden'.
• serverIdExpr
  sets the server id response to be sent back as client if a server is requesting it via function code 17
  this is defiend as a perl expression for more flexibility.
• disable
  stop communication with the device while this attribute is set to 1. For Modbus over TCP this also closes the TCP connection.
• dev-fc[\d]+Response-unpack
  defines the pack / unpack code to be used when creating or parsing a custom function code response
• dev-fc[\d]+Response-fieldList
  defines the fields that are used for creating or parsing a custom function code response.
  Possible fields are TYPE, ADR, LEN, VALUES, PDULEXP. They correspond to the unpack code in the attribute above and are specified in a comma seperated list.
• dev-fc[\d]+Response-fieldExpr-.*
  defines additional Perl expressions for the fields that are used for creating or parsing a custom function code response.
  The correspondig field is the last part of the attribute name. Possible fields are TYPE, ADR, LEN, VALUES, PDULEXP.
• dev-fc[\d]+Request-unpack
  defines the pack / unpack code to be used when creating or parsing a custom function code request
• dev-fc[\d]+Request-fieldList
  defines the fields that are used for creating or parsing a custom function code request.
  Possible fields are TYPE, ADR, LEN, VALUES, PDULEXP. They correspond to the unpack code in the attribute above and are specified in a comma seperated list.
• dev-fc[\d]+Request-fieldExpr-.*
  defines additional Perl expressions for the fields that are used for creating or parsing a custom function code request.
  The correspondig field is the last part of the attribute name. Possible fields are TYPE, ADR, LEN, VALUES, PDULEXP.

ModbusElsnerWS

The ModbusElsnerWS weather evaluation modul serves as a connecting link between the Elsner P03/3-Modbus Weather Stations and blind actuators. ModbusElsnerWS uses the low level Modbus module to provide a way to communicate with the Elsner P03/3-Modbus Weather Stations. It read the modbus holding registers for the different values and process them in a periodic interval. It evaluates the received weather data and based on adjustable thresholds and delay times it generates up/down signals for blinds according to wind, rain and sun. This way blinds can be pilot-controlled and protected against thunderstorms. The GPS function of the sensor provides the current values of the date, time, weekday, sun azimuth, sun elevation, longitude and latitude.
As an alternative to the module for the Elsner Modbus sensors, sensors with the manufacturer-specific serial RS485 protocol can also be used. The ElsnerWS module is available for this purpose. EnOcean profiles "Environmental Applications" with the EEP A5-13-01 ... EEP A5-13-06 are also available for these weather stations, but they also require weather evaluation units from Eltako or AWAG, for example. The functional scope of the modules is widely similar.

Functions
• Evaluation modul for the weather sensors P03/3-Modbus and P03/3-Modbus GPS
• Processing weather raw data and creates graphic representation
• For wind observations, average speeds, gusts and peak values are calculated.
• Alarm signal in case of failure of the weather sensor
• Up/down readings for blinds according to wind, rain and sun
• Adjustable switching thresholds and delay times
• Day/night signal
• Display of date, time, sun azimuth, sun elevation, longitude and latitude
• Execution of custom alarm commands, see customCmdAlarmOff and customCmdAlarmOn.
• Execution of custom up and down commands that can be triggered by the readings dayNight, isRaining, isStormy, isSunny, isSunnyEast, isSunnySouth, isSunnyWest and isWindy, see customCmdDown and customCmdUp.

Prerequisites
This module requires the basic Modbus module which itsef requires Device::SerialPort or Win32::SerialPort module.

Hardware Connection
The weather sensor P03/3-Modbus(GPS) is connected via a shielded cable 2x2x0.5 mm2 to a RS485 transceiver. The sensor is connected via the pins A to the RS485 B(+)-Port, B to RS485 A(-)-Port, 1 to + 12...28 V, 2 to GND and Shield. Please note that the RS485 connection names are reversed. Only the usual pins for serial Modbus communication A, B and Ground are needed.
The serial bus should be terminated at its most remote ends with 120 Ohm resistors. If several Modbus units are connected to the serial bus, only the termination resistor in the devices furthest ends must be switched on.
More information about the sensor, see P03/3-Modbus(GPS) User Guide.
The USB adapters Digitus DA-70157, In-Circuit USB-RS485-Bridge and DSD TECH SH-U10 USB to RS485 converter are successfully tested at a Raspberry PI in conjunction with the weather sensor.

Define
define <name> ModbusElsnerWS id=<ID> interval=<Interval>|passive

The module connects to the Elsner Weather Station with the Modbus Id <ID> through an already defined Modbus device and actively requests data from the system every <Interval> seconds. The query interval should be set to 1 second. The readings windAvg2min, windGust10min, windGustCurrent and windPeak10min required for wind observation are calculated only at a query interval of 1 second.
The following parameters apply to the default factory settings and an RS485 transceiver to USB.

Example:
define modbus Modbus /dev/ttyUSB1@19200,8,E,1
define WS ModbusElsnerWS id=1 interval=1

Get
get <name> <value>


where value is
• raw
  get sensor dates manualy

Attributes
• brightnessDayNight E_min/lx:E_max/lx, [brightnessDayNight] = 0...99000:0...99000, 10:20 is default.
  Set switching thresholds for reading dayNight based on the reading brightness.
• brightnessDayNightDelay t_reset/s:t_set/s, [brightnessDayNightDelay] = 0...3600:0...3600, 600:600 is default.
  Set switching delay for reading dayNight based on the reading brightness. The reading dayNight is reset or set if the thresholds are permanently undershot or exceed during the delay time.
• brightnessSunny E_min/lx:E_max/lx, [brightnessSunny] = 0...99000:0...99000, 20000:40000 is default.
  Set switching thresholds for reading isSunny based on the reading brightness.
• brightnessSunnyDelay t_reset/s:t_set/s, [brightnessSunnyDelay] = 0...3600:0...3600, 120:30 is default.
  Set switching delay for reading isSunny based on the reading brightness. The reading isSunny is reset or set if the thresholds are permanently undershot or exceed during the delay time.
• brightnessSunnyEast E_min/lx:E_max/lx, [brightnessSunnyEast] = 0...99000:0...99000, 20000:40000 is default.
  Set switching thresholds for reading isSunnyEast based on the reading sunEast.
• brightnessSunnyEastDelay t_reset/s:t_set/s, [brightnessSunnyEastDelay] = 0...3600:0...3600, 120:30 is default.
  Set switching delay for reading isSunnyEast based on the reading sunEast. The reading isSunnyEast is reset or set if the thresholds are permanently undershot or exceed during the delay time.
• brightnessSunnySouth E_min/lx:E_max/lx, [brightnessSunnySouth] = 0...99000:0...99000, 20000:40000 is default.
  Set switching thresholds for reading isSunnySouth based on the reading sunSouth.
• brightnessSunnySouthDelay t_reset/s:t_set/s, [brightnessSunnySouthDelay] = 0...3600:0...3600, 120:30 is default.
  Set switching delay for reading isSunnySouth based on the reading sunSouth. The reading isSunnySouth is reset or set if the thresholds are permanently undershot or exceed during the delay time.
• brightnessSunnyWest E_min/lx:E_max/lx, [brightnessSunnyWest] = 0...99000:0...99000, 20000:40000 is default.
  Set switching thresholds for reading isSunnyWest based on the reading sunWest.
• brightnessSunnyWestDelay t_reset/s:t_set/s, [brightnessSunnyWestDelay] = 0...99000:0...99000, 120:30 is default.
  Set switching delay for reading isSunnyWest based on the reading sunWest. The reading isSunnyWest is reset or set if the thresholds are permanently undershot or exceed during the delay time.
• customCmdAlarmOff <command>
  customCmdAlarmOn <command>
  Command being executed if an alarm is set (on) or deleted (off). If <command> is enclosed in {}, then it is a perl expression, if it is enclosed in "", then it is a shell command, else it is a "plain" fhem.pl command (chain). In the <command> you can access the name of the device by using $NAME, $TYPE and the current readings
  $BRIGHTNESS, $DATE, $DAYNIGHT, $HEMISPHERE, $ISRAINING, $ISSTORMY, $ISSUNNY, $ISSUNNYEAST, $ISSUNNYSOUTH", $ISSUNNYWEST, $ISWINDY, $LATITUDE, $LONGITUDE, $NAME, $SUNAZIMUTH, $SUNEAST, $SUNELAVATION, $SUNSOUTH, $SUNWEST, $TEMPERATURE, $TIME, $TIMEZONE, $TWILIGHT, $TYPE, $WEEKDAY, $WINDAVG2MIN, $WINDGUST10MIN, $WINDGUSTCURRNT, $WINDPEAK10MIN, $WINDSPEED, $WINDSTENGTH.
  The eventMap replacements are taken into account. This data is available as a local variable in perl, as environment variable for shell scripts, and will be textually replaced for Fhem commands.
  The alarm commands have a higher priority than the up and down commands.
• customCmdDown <command>
  customCmdUp <command>
  The command is executed if the Up or Down command is triggered, see customCmdDownTrigger or customCmdUpTrigger. If <command> is enclosed in {}, then it is a perl expression, if it is enclosed in "", then it is a shell command, else it is a "plain" fhem.pl command (chain). In the <command> you can access the name of the device by using $NAME, $TYPE and the current readings
  $BRIGHTNESS, $DATE, $DAYNIGHT, $HEMISPHERE, $ISRAINING, $ISSTORMY, $ISSUNNY, $ISSUNNYEAST, $ISSUNNYSOUTH", $ISSUNNYWEST, $ISWINDY, $LATITUDE, $LONGITUDE, $NAME, $SUNAZIMUTH, $SUNEAST, $SUNELAVATION, $SUNSOUTH, $SUNWEST, $TEMPERATURE, $TIME, $TIMEZONE, $TWILIGHT, $TYPE, $WEEKDAY, $WINDAVG2MIN, $WINDGUST10MIN, $WINDGUSTCURRNT, $WINDPEAK10MIN, $WINDSPEED, $WINDSTENGTH.
  The eventMap replacements are taken into account. This data is available as a local variable in perl, as environment variable for shell scripts, and will be textually replaced for Fhem commands.
  The alarm commands have a higher priority than the up and down commands.
• customCmdDownPeriod once|threeTimes|3|10|180|600
  customCmdUpPeriod once|threeTimes|3|10|180|600
  [customCmdDownPeriod] = once|threeTimes|3|10|180|600, once is default.
  Number or period of custom command to be executed.
• customCmdDownTrigger dayNight|isRaining|isStormy|isSunny|isSunnyEast|isSunnySouth|isSunnyWest|isWindy
  The commands in the attribute customCmdDown are executed if one of the selected readings is triggered as follows:
  • [dayNight] = night
  • [isRaining] = no
  • [isStormy] = no
  • [isSunny] = yes
  • [isSunnyEast] = yes
  • [isSunnySouth] = yes
  • [isSunnyWest] = yes
  • [isWindy] = no
  The commands in the attribute customCmdDown are executed periodically every second if the attribute is not set.
• customCmdUpTrigger dayNight|isRaining|isStormy|isSunny|isSunnyEast|isSunnySouth|isSunnyWest|isWindy
  The commands in the attribute customCmdUp are executed if one of the selected readings is triggered as follows:
  • [dayNight] = day
  • [isRaining] = yes
  • [isStormy] = yes
  • [isSunny] = no
  • [isSunnyEast] = no
  • [isSunnySouth] = no
  • [isSunnyWest] = no
  • [isWindy] = yes
  The commands in the attribute customCmdUp are executed periodically every second if the attribute is not set.
• customCmdPriority down|up, [customCmdPriority] = down|up, up is default.
  Priority of custom commands. If both the up and down command are triggered, only the prioritized command is executed.
• readingFnAttributes
• signOfLife off|on, [signOfLife] = off|on, on is default.
  Monitoring of the periodic telegrams from sensor.
• signOfLifeInterval t/s, [signOfLifeInterval] = 1 ... 15, 3 is default.
  Monitoring period in seconds of the periodic telegrams from sensor.
• timeEvent no|yes, [timeEvent] = no|yes, no is default.
  Update the reading time periodically.
• updateGlobalAttr no|yes, [updateGlobalAttr] = no|yes, no is default.
  Update the global attributes latitude and longitude with the received GPS coordinates.
• windSpeedStormy v_min/m/s:v_max/m/s, [windSpeedStormy] = 0...35:0...35, 13.9:17.2 (windStrength = 7 B - 8 B) is default.
  Set switching thresholds for reading isStormy based on the reading windSpeed.
• windSpeedStormyDelay t_reset/s:t_set/s, [windSpeedStormyDelay] = 0...3600:0...3600, 60:3 is default.
  Set switching delay for reading isStormy based on the reading windSpeed. The reading isStormy is reset or set if the thresholds are permanently undershot or exceed during the delay time.
• windSpeedWindy v_min/m/s:v_max/m/s, [windSpeedWindy] = 0...35:0...35, 1.6:3.4 (windStrength = 2 B - 3 B) is default.
  Set switching thresholds for reading isWindy based on the reading windSpeed.
• windSpeedWindyDelay t_reset/s:t_set/s, [windSpeedWindyDelay] = 0...3600:0...3600, 60:3 is default.
  Set switching delay for reading isWindy based on the reading windSpeed. The reading isWindy is reset or set if the thresholds are permanently undershot or exceed during the delay time.

Generated events
• T: t/°C B: E/lx W: v/m/s IR: no|yes
• alarm: dead_sensor
• brightness: E/lx (Sensor Range: E = 0 lx ... 99000 lx)
• date: JJJJ-MM-TT
• dayNight: day|night
• hemisphere: north|south
• isRaining: no|yes
• isStormy: no|yes
• isSunny: no|yes
• isSunnyEast: no|yes
• isSunnySouth: no|yes
• isSunnyWest: no|yes
• isWindy: no|yes
• latitude: φ/° (Sensor Range: φ = -90 ° ... 90 °)
• longitude: λ/° (Sensor Range: λ = -180 ° ... 180 °)
• sunAzimuth: α/° (Sensor Range: α = 0 ° ... 359 °)
• sunEast: E/lx (Sensor Range: E = 0 lx ... 99000 lx)
• sunElevation: β/° (Sensor Range: β = -90 ° ... 90 °)
• sunSouth: E/lx (Sensor Range: E = 0 lx ... 99000 lx)
• sunWest: E/lx (Sensor Range: E = 0 lx ... 99000 lx)
• temperature: t/°C (Sensor Range: t = -40 °C ... 70 °C)
• time: hh:mm:ss
• timeZone: CET|CEST|UTC
• twilight: T/% (Sensor Range: T = 0 % ... 100 %)
• weekday: Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday
• windAvg2min: v/m/s (Sensor Range: v = 0 m/s ... 70 m/s)
• windGust10min: v/m/s (Sensor Range: v = 0 m/s ... 70 m/s)
• windGustCurrent: v/m/s (Sensor Range: v = 0 m/s ... 70 m/s)
• windPeak10min: v/m/s (Sensor Range: v = 0 m/s ... 70 m/s)
• windSpeed: v/m/s (Sensor Range: v = 0 m/s ... 70 m/s)
• windStrength: B (Sensor Range: B = 0 Beaufort ... 12 Beaufort)
• state: T: t/°C B: E/lx W: v/m/s IR: no|yes

ModbusSET

[EN DE]

ModbusSET uses the low level Modbus module to provide a way to communicate with Silent 10 heat pumps from SET. It probably works with other heat pumps from SET as well and since the control device used in these heat pumps is an iChill IC121 from Dixell, it could even work for other heat pumps with this controller as well or with few changes. It defines the modbus holding registers for the temperature sensors and reads them in a defined interval.
Prerequisites
• This module requires the basic Modbus module which itsef requires Device::SerialPort or Win32::SerialPort module.

Define
define <name> ModbusSET <Id> <Interval>

The module connects to the heat pump with Modbus Id <Id> through an already defined modbus device and actively requests data from the heat pump every <Interval> seconds

Example:


define WP ModbusSET 1 60

Configuration of the module


apart from the modbus id and the interval which both are specified in the define command there is nothing that needs to be defined. However there are some attributes that can optionally be used to modify the behavior of the module.

The attributes that control which messages are sent / which data is requested every <Interval> seconds are:

        poll-Hyst_Mode
        poll-Temp_Luft
        poll-Temp_Wasser_Aus_Off
        poll-Temp_Wasser_Ein_Off
        poll-Temp_Wasser_Aus
        poll-Hysterese
        poll-Temp_Wasser_Ein
        poll-Temp_Soll
        poll-Temp_Luft_Off
        poll-Temp_Verdampfer
        poll-Temp_Verdampfer_Off
        

if the attribute is set to 1, the corresponding data is requested every <Interval> seconds. If it is set to 0, then the data is not requested. by default the temperatures are requested if no attributes are set.
if some readings should be polled, but less frequently than the normal interval, you can specify a pollDelay- Attribute for the reading.
The pollDelay attribute allows to poll objects at a lower rate than the interval specified in the define command. you can either specify a time in seconds or number prefixed by "x" which means a multiple of the interval of the define command.
if you specify a normal numer then it is interpreted as minimal time between the last read and another automatic read. Please note that this does not create an individual interval timer. Instead the normal interval timer defined by the interval of the define command will check if this reading is due or not yet. So the effective interval will always be a multiple of the interval of the define.

Example:

        define WP ModbusSET 1 60
        attr WP poll-Temp_Soll 0
        attr WP pollDelay-Hysterese 300
        

Set-Commands

The following set options are available:

        Hysterese (defines the hysterese in Kelvin)
        Hyst_Mode (defines the interpretation of hysterese for the heating and can be set to mittig, oberhalb or unterhalb)
        Temp_Wasser_Aus_Off (offset of sensor in Kelvin - used to kalibrate)
        Temp_Wasser_Ein_Off (offset of sensor in Kelvin - used to kalibrate)
        Temp_Luft_Off (offset of sensor in Kelvin - used to kalibrate)
        Temp_Verdampfer_Off (offset of sensor in Kelvin - used to kalibrate)
        Temp_Soll (target temperature of the heating pump)
        


Get-Commands

All readings are also available as Get commands. Internally a Get command triggers the corresponding request to the device and then interprets the data and returns the right field value. To avoid huge option lists in FHEMWEB, only the most important Get options are visible in FHEMWEB. However this can easily be changed since all the readings and protocol messages are internally defined in the modue in a data structure and to make a Reading visible as Get option only a little option (e.g. showget => 1 has to be added to this data structure

Attributes


• do_not_notify
• readingFnAttributes


• poll-Hyst_Mode
• poll-Temp_Luft
• poll-Temp_Wasser_Aus_Off
• poll-Temp_Wasser_Ein_Off
• poll-Temp_Wasser_Aus
• poll-Hysterese
• poll-Temp_Wasser_Ein
• poll-Temp_Soll
• poll-Temp_Luft_Off
• poll-Temp_Verdampfer
• poll-Temp_Verdampfer_Off
include a read request for the corresponding registers when sending requests every interval seconds

• pollDelay-*
set a delay for polling individual Readings. In case some readings should be polled less frequently than the normal delay specified during define. Specifying a pollDelay will not create an individual timer for polling this reading but check if the delay is over when the normal update interval is handled.
You can either specify a time in seconds or number prefixed by "x" which means a multiple of the interval of the define command.
If you specify a normal numer then it is interpreted as minimal time between the last read and another automatic read. Please note that this does not create an individual interval timer. Instead the normal interval timer defined by the interval of the define command will check if this reading is due or not yet. So the effective interval will always be a multiple of the interval of the define.
• dev-timing-timeout
set the timeout for reads, defaults to 2 seconds

• dev-timing-minSendDelay
minimal delay between two requests sent to this device
• dev-timing-minCommDelay
minimal delay between requests or receptions to/from this device

ModbusTrovis5576

[EN DE]

ModbusTrovis5576 uses the low level Modbus module to provide a way to communicate with the Samson Trovis 5576 Heating Management. It defines the modbus holding registers for the different values and reads them in a defined interval.

Prerequisites
This module requires the basic Modbus module which itsef requires Device::SerialPort or Win32::SerialPort module.

Hardware Connection
The Manual shows on page 124 a diagram of the correct pins for connecting to the serial port. The RS232-Port is not the one on the front side, but, as seen from the front, on the left side of the heating management. This port is covered with a small plastic-shield which can easily be removed.
Only the usual pins for serial communication (TD, RD and Ground) are needed.

Special meanings with Readings and the Heating Management System
If you change the value of "Betriebsart" ("Operating Mode") the rotary switch at the heating management doesn't change. To reflect this fact the display shows "GLT" (in German "Gebäudeleittechnik" - Building Control Center) and the corresponding so-called Ebenen-Bit ("_EBN" - Level-Bit) is set to "GLT".
If you want to switch back to autonomous mode you can set the appropriate Ebenen-Bit to "Autark".

If you change the value of "Betriebsart" to standby it could be happen that it is automatically (re-)changed to "Mond" ("Moon"). This happens if the outside temperature is lower than 3°C and it's shown with the value of "Frostschutzbetrieb" ("Frost Protection Mode").

Suggestion:
It is hardly recommended to set the Attribute event-on-change-reading to .*. Otherwise the system will generate many senseless events.

Define
define <name> ModbusTrovis5576 <ID> <Interval> [<IP-Address:Port> <TCP or RTU>]

The module connects to the Samson Trovis 5576 Heating Management with the Modbus Id <ID> through an already defined Modbus device and actively requests data from the system every <Interval> seconds.

Example:
define heizung ModbusTrovis5576 255 60

Set-Commands
The following set options are available:
• Regelkreis 1 (Usually Wallmounted-Heatings):
  • RK1_Betriebsart: Operating mode of Regelkreis 1. Possible values are Standby, Mond or Sonne.
  • RK1_Betriebsart_EBN: The Ebenen-Bit according to the Operating Mode. Possible values are GLT or Autark.
  • RK1_Stellsignal: The percent value of opening of the heat transportation valve.
  • RK1_Stellsignal_EBN: The Ebenen-Bit according to the heat transportation valve. Possible values are GLT or Autark.
  • RK1_Umwaelzpumpe: The on/off state of thr circulation pump. Possible values are An or Aus.
  • RK1_Umwaelzpumpe_EBN: The Ebenen-Bit according to the circulation pump. Possible values are GLT or Autark.
• Regelkreis 2 (Usually Floor Heating System):
  • RK2_Betriebsart: Operating mode of Regelkreis 2. Possible values are Standby, Mond or Sonne.
  • RK2_Betriebsart_EBN: The Ebenen-Bit according to the Operating Mode. Possible values are GLT or Autark.
  • RK2_Stellsignal: The percent value of opening of the heat transportation valve.
  • RK2_Stellsignal_EBN: The Ebenen-Bit according to the heat transportation valve. Possible values are GLT or Autark.
  • RK2_Umwaelzpumpe: The on/off state of the circulation pump. Possible values are An or Aus.
  • RK2_Umwaelzpumpe_EBN: The Ebenen-Bit according to the circulation pump. Possible values are GLT or Autark.
• Drinkable Water Reservoir:
  • Wasser_Betriebsart: Operating mode of the drinkable water system. Possible values are Standby, Mond or Sonne.
  • Wasser_Betriebsart_EBN: The Ebenen-Bit according to the Operating Mode. Possible values are GLT or Autark.
  • Wasser_Speicherladepumpe: The on/off state of the reservoir loading pump. Possible values are An or Aus.
  • Wasser_Speicherladepumpe_EBN: The Ebenen-Bit according to the Speicherladepumpe. Possible values are GLT or Autark.
  • Wasser_Zirkulationspumpe: The on/off state of the circular pump. Possible values are An or Aus.
  • Wasser_Zirkulationspumpe_EBN: The Ebenen-Bit according to the circular pump. Possible values are GLT or Autark.
  • Wasser_ThermischeDesinfektion: On/off state of the thermal disinfection. Possible values are An or Aus.
  • Wasser_Temp_Soll: The desired temperature for the drinkabke water reservoir.
  • Wasser_Temp_Minimum: The lowest temperature for the drinkable water reservoir.
  • Wasser_Temp_Desinfektion: The desired temperature of the thermal disinfection system.

All other Readings (along with their Meanings) which can only be read:

• Common Data:
  • Modellnummer: Shows the modelnumber. Should be "5576".
  • Aussen_Temp: Shows the currently measured outside temperature in °C.
  • Fehlerstatusregister_CL1: Shows the current status register (CL1).
• Regelkreis 1 (Usually Wallmounted-Heatings):
  • RK1_Schalter: Represent the current value of the rotary switch. Possible values are PA, Auto, Standby, Hand, Sonne or Mond.
  • RK1_Frostschutzbetrieb: On/off state of the frost protection mode of Regelkreis 1.
  • RK1_Vorlauf_Temp: Shows the currently measured flow temperature in °C of Regelkreis 1.
  • RK1_Ruecklauf_Temp: Shows the currently measured return temperature in °C of Regelkreis 1.
• Regelkreis 2 (Usually Floor Heating System):
  • RK2_Schalter: Represent the current value of the rotary switch. Possible values are PA, Auto, Standby, Hand, Sonne or Mond.
  • RK2_Frostschutzbetrieb: On/off state of the frost protection mode of Regelkreis 2.
  • RK2_Vorlauf_Temp: Shows the currently measured flow temperature in °C of Regelkreis 2.
  • RK2_Ruecklauf_Temp: Shows the currently measured return temperature in °C of Regelkreis 2.
• Drinkable Water Reservoir:
  • Wasser_Schalter: Represent the current value of the rotary switch. Possible values are PA, Auto, Standby, Hand, Sonne or Mond.
  • Wasser_Frostschutzbetrieb: On/off state of the frost protection mode of the drinkable water heating system.
  • Wasser_Temp: Shows the currently measured return temperature in °C of the drinkablr water reservoir.

Get-Commands
All readings are also available as Get commands. Internally a Get command triggers the corresponding request to the device and then interprets the data and returns the correct field value. This is a good way for getting a new current value from the Heating Management System.

Attribute
Only centralized Attributes are in use. Especially:
• readingFnAttributes

N4HBUS

[EN DE]

This module connects fhem to the net4home Bus. You need to define ojects with N4MODULE to set or read data of th net4home bus.

Further technical information can be found at the net4home.de Homepage

Define

define <name> N4HBUS <device>

<device> is a combination of <host>:<port>, where <host> is the IP address of the net4home Busconnector and <port> (default:3478).

Example:
define net4home N4HBUS 192.168.1.69:3478

The device can also be connected to the busconnector on the same machine.
Default Port for communication is 3478. In case you need to change this please change also the Port in the conf of Busconnector service.

Readings

• state - current state of the connection to net4home bus connector

Attributes

• MI - a unique MI in the net4home environment (default:65281)
• OBJADR - a unique OBJADR in the net4home environment (default:32700)

N4HMODULE

[EN DE]

fhem-Module to communicate with net4home modules via IP

Define
define <name> N4HMODULE <device> <type> <objectaddress>

Defines a net4home device connected to a N4HBUS device

Examples:
define n4h_28204 N4HMODULE n4h 24 28204

Currently the following values are supported:
Measurement

• 24 - Measurement,Temperature
• 25 - Measurement,Brightness
• 26 - Measurement,Humidity
• 34 - TLH-Regler H,Sollwert,Temperatur
• 95 - Ausgang, Jal, Motor AJ3
• 210 - RF Reader
• 240 - Measurement,Wind
• 242 - Measurement,Pressure
• 245 - Measurement,Rain

Readings
• The readings are dependent of the object of the net4home bus module.
  

Attributes
• interval
  the interval in seconds used to send values to bus.

NEUTRINO

[EN DE]

Define
define <name> NEUTRINO <ip-address-or-hostname> [[[[<port>] [<poll-interval>]] [<http-user>]] [<http-password>]]

This module controls NEUTRINO based devices like Coolstream receiver via network connection.

Defining an NEUTRINO device will schedule an internal task (interval can be set with optional parameter <poll-interval> in seconds, if not set, the value is 45 seconds), which periodically reads the status of the device and triggers notify/filelog commands.

Example:

define SATReceiver NEUTRINO 192.168.0.10

# With custom port
define SATReceiver NEUTRINO 192.168.0.10 8080

# With custom interval of 20 seconds
define SATReceiver NEUTRINO 192.168.0.10 80 20

# With HTTP user credentials
define SATReceiver NEUTRINO 192.168.0.10 80 20 root secret


Set
set <name> <command> [<parameter>]

Currently, the following commands are defined.

• on   -   powers on the device (standby mode)
• off   -   turns the device in standby mode
• toggle   -   switch between on and off (standby mode)
• shutdown   -   poweroff the device
• reboot   -  reboots the device
• channel   -   zap to specific channel
• volume 0...100   -   set the volume level in percentage
• mute on,off,toggle   -   controls volume to mute
• statusRequest   -   requests the current status of the device
• remoteControl UP,DOWN,...   -   sends remote control command
  
• showText text   -   sends info messages to be displayed on screen
• showtextwithbutton   -   sends info messagees to be displayed on screen with OK button




Get
get <name> <what>

Currently, the following commands are defined:


channel
channelurl
currentTitle
input
mute
power
volume



Attributes

• disable - Disable polling (true/false)
• http-noshutdown - Set FHEM-internal HttpUtils connection close behaviour (defaults=0)
• https - Access box via secure HTTP (true/false)
• timeout - Set different polling timeout in seconds (default=2)



Generated Readings:

• ber - Shows Bit Error Rate for current channel
• bouquetnr - Shows bouquet number for current channel
• channel - Shows the service name of current channel
• channel_id - Shows the channel id of current channel
• channel_name - Shows the channel name of current channel
• channel_url - Shows the channel url of current channel (use with vlc player)
• currentTitle - Shows the title of the running event
• epg_current_channel_id - Shows the channel id of epg information
• epg_current_date - Shows the date of epg information
• egp_current_description - Shows the current description of the current program
• egp_current_duration_min - Shows the current duration of the current program
• egp_current_info1 - Displays the current information of the current program
• egp_current_info2 - Displays the current information of the current program
• egp_current_number - Displays the current number(epg) of the current program
• egp_current_start_sec - Shows the current start time of the current program (ticks)
• egp_current_start_t - Shows the current start time of the current program
• egp_current_stop_sec - Shows the current stop time of the current program (ticks)
• egp_current_stop_t - Shows the current stop time of the current program
• eventid - Shows the current event id of the current program
• image_* - Shows image information of NEUTRINO
• input - Shows currently used input
• mute - Reports the mute status of the device (can be "on" or "off")
• power - Reports the power status of the device (can be "on" or "off")
• presence - Reports the presence status of the receiver (can be "absent" or "present").
• recordmode - Reports the record mode of the device (can be "on" or "off")
• recordmodetitle - Reports the last record title
• sig - Shows signal for current channel in percent
• snr - Shows signal to noise for current channel in percent
• state - Reports current power state and an absence of the device (can be "on", "off" or "standby")
• time_now - Reports current time
• time_raw_now - Reports current time (ticks)
• timerX - Shows complete timer (Report from NEUTRINO)
• timerXannounceTime - Shows announce time of the timer
• timerXname - Shows channel name of the timer
• timerXnumber - Shows timer number
• timerXrepcount - Shows rep count of the timer
• timerXrepeat - Shows repeat time of the timer
• timerXstartTime - Shows start time of the timer
• timerXstopTime - Shows stop time of the timer
• timerXtyp - Shows type of the timer
• timer_count - Shows the number of timers
• timer_count - Shows the maximum number of timers
• volume - Reports current volume level of the receiver in percentage values (between 0 and 100 %)

NUKIBridge

[EN DE]

NUKIBridge - controls Nuki Devices (Smartlock, Opener and so on) over the Nuki Bridge
The Nuki Bridge module connects FHEM to the Nuki Bridge and then reads all the Nuki devices available on the bridge. Furthermore, the detected Nuki smart devices are automatically created as independent devices.

Define
There a two ways to define the bridge for use in fhem.
first:
define <name> NUKIBridge

Example:

define NBridge1 NUKIBridge


This statement creates a NUKIBridge device and activated the Bridge discovery and API activation. Once a bridge has been discovered on the LAN the API done be activated and the API token retrieved. You has to confirm this request by pressing the button on the bridge.
After the bridge device is setting up, all available Smartlocks are automatically placed in FHEM.

second:
define <name> NUKIBridge <HOST> <API-TOKEN>

Example:

define NBridge1 NUKIBridge 192.168.0.23 F34HK6


This statement creates a NUKIBridge device with the name NBridge1 and the IP 192.168.0.23 as well as the token F34HK6.
After the bridge device is created, all available Smartlocks are automatically placed in FHEM.


Readings
• bridgeType - Hardware bridge / Software bridge
• configAuthSuccess - state of command activat/deactiviate bridge discovery
• currentGMTime - Current timestamp
• firmwareVersion - Version of the bridge firmware
• hardwareId - Hardware ID
• lastError - Last connected error
• serverConnected - Flag indicating whether or not the bridge is connected to the Nuki server
• serverId - Server ID
• state - state of the bridge device, mostly online
• uptime - Uptime of the bridge in seconds
• wifiFirmwareVersion- Version of the WiFi modules firmware
• wlanConnected - wifi connect?

The preceding number is continuous, starts with 0 und returns the properties of one Smartlock.


Set
• getDeviceList - Prompts to re-read all devices from the bridge and if not already present in FHEM, create the automatically.
• callbackRemove - Removes a previously added callback
• clearLog - Clears the log of the Bridge (only hardwarebridge)
• factoryReset - Performs a factory reset (only hardwarebridge)
• fwUpdate - Immediately checks for a new firmware update and installs it (only hardwarebridge)
• info - Returns all Smart Locks in range and some device information of the bridge itself
• reboot - reboots the bridge (only hardwarebridge)




Get
• callbackList - List of register url callbacks.
• logFile - Retrieves the log of the Bridge




Attributes
• disable - disables the Nuki Bridge
• webhookFWinstance - Webinstanz of the Callback
• webhookHttpHostname - IP or FQDN of the FHEM Server Callback

NUKIDevice

[EN DE]

NUKIDevice - Controls the Nuki Smartlock
The Nuki module connects FHEM over the Nuki Bridge with a Nuki Smartlock or Nuki Opener. After that, it´s possible to control your Nuki devices
Normally the Nuki devices are automatically created by the bridge module.

Define

define <name> NUKIDevice <Nuki-Id> <IODev-Device> <Device-Type>

Device-Type is 0/4 for the Smartlock and 2 for the Opener.

Example:

define Frontdoor NUKIDevice 1 NBridge1 0


This statement creates a NUKIDevice with the name Frontdoor, the NukiId 1 and the IODev device NBridge1.
After the device has been created, the current state of the Smartlock is automatically read from the bridge.


Readings
Smartlock
• batteryCharging - is the battery charging true/false.
• batteryPercent - current battry state in percent.
• batteryState - battery state ok/low
• deviceType - type name of nuki device smartlock/smartlock3/opener
• firmwareVersion - version of device firmware
• name - name of the device
• nukiid - id of the nuki device
• paired - paired information false/true
• rssi - value of rssi
• state - Status of the Smartlock or error message if any error.
• stateName - Status of the Smartlock or error message if any error.
• succes - true, false Returns the status of the last closing command. Ok or not Ok.

Opener
• batteryState - battery state ok/low
• deviceType - type name of nuki device smartlock/smartlock3/opener
• firmwareVersion - version of device firmware
• mode - Operation mode (door mode/continuous mode)
• name - name of the device
• nukiid - id of the nuki device
• paired - paired information false/true
• ringactionState - state of ring (0/1)
• ringactionTimestamp - timestamp of ring
• rssi - value of rssi
• state - Status of the Smartlock or error message if any error.
• stateName - Status of the Smartlock or error message if any error.
• succes - true, false Returns the status of the last closing command. Ok or not Ok.


Set
Smartlock
• statusRequest - retrieves the current state of the smartlock from the bridge.
• lock - lock
• unlock - unlock
• unlatch - unlock / open Door
• unpair - Removes the pairing with a given Smart Lock
• locknGo - lock when gone
• locknGoWithUnlatch - lock after the door has been opened

Opener
• statusRequest - retrieves the current state of the smartlock from the bridge.
• activateRto - activate ring to open mode / ringing the bell activates the electric strike actuation
• deactivateRto - deactivate ring to open mode
• electricStrikeActuation - electric strike actuation
• activateContinuousMode - activate Nuki Opener Mode with Ring to Open continuously
• deactivateContinuousMode - deactivate Ring to Open continuously


Attributes
• disable - disables the Nuki device

NUT

[EN DE]

The Network UPS Tools (www.networkupstools.org) provide support for Uninterruptable Power Supplies and the like. This module gives access to a running nut server. You can read data (status, runtime, input voltage, sometimes even temperature and so on). In the future it will also be possible to control the UPS (start test, switch off).
Which values you can use as readings is set with asReadings. Which values are available with this UPS, you can check with list theUPS. Only ups.status is always read and used as the status of the device.


Define
define <name> NUT <ups> [<host>[:<port>]]

<ups> is the name of a ups defined in the nut server.
[<host>[:<port>]] is the host of the nut server. If omitted, localhost:3493 is used.

Example:
define theUPS NUT myups otherserver


Set
N/A

Get
N/A

Attributes
• disable


• readingFnAttributes


• pollState
  Polling interval in seconds for the state of the ups. Default: 10


• pollVal
  Polling interval in seconds of the other Readings. This should be a multiple of pollState. Default: 60


• asReadings
  Values of the UPS which are used as Readings (ups.status is read anyway)
  Example:
  attr theUPS asReadings battery.charge,battery.runtime,input.voltage,ups.load,ups.power,ups.realpower

Nello

[EN DE]

The Nello module enables you to control your intercom using the nello one module.
To set it up, you need to add a new user with admin rights via the nello app just for use with fhem. You cannot use your main account since only one session at a time is possible.
After that, you can define the device and continue with login.
ATTENTION: If the login fails, try resetting your password using the recoverPassword function.
Recommendation: To receive instant events, call the detectDeviceID function after login.



Required Packages

sudo apt-get install libcpan-meta-yaml-perl
sudo cpan -i Net::MQTT::Simple




Define

define <name> Nello



Example: define nello Nello





set <required> [ <optional> ]

• login <username> <password>
  login to your created account
• recoverPassword <username>
  recovers the password
• detectDeviceID
  detects your device ID by opening the door and creates MQTT helper (used for event hooks)
• open [ <location_id> ]
  opens the door for a given location (if the account has only access to one location the default one will be used automatically).
• update
  updates your locations and activities



Get

N/A



Attributes

• updateInterval
  the interval to fetch new activites in seconds
  default: 900 (if deviceID is available), 15 otherwise

NetIO230B

[EN DE]

fhem-module for NetIO 230B Power Distribution Unit    (see: NetIO 230B (koukaam.se))

Note: this module needs the HTTP::Request and LWP::UserAgent perl modules.
Please also note: the PDU must use firmware 3.1 or later and set to unencrypted mode.

Define
• define <name> NetIO230B <ip-address> <socket number(s) > [<user name> <password>]
• define <name> NetIO230B <ip-address> <socket number(s) > [<config file path>]

Defines a switching device, where sockets can be switched

• separately (just use 0-4 as socket number)
• all together (use 1234 as socket number)
• in arbitrary groups (e.g 13 switches socket 1 and 3, 42 switches socket 2 and 4, etc...), invalid numbers are ignored

User name and password are optional. When no user name or password is passed, the module looks for a configfile at '/var/log/fhem/netio.conf'. If no config file is found, it uses 'admin/admin' as user/pass, since this is the default configuration for the device.

Alternatively you can pass a path to a configfile instead of the user/pass combo. (e.g. /var/tmp/tmp.conf) Configfile-Format:


%config= (
   host => "192.168.61.40",
   user => "admin",
   password => "admin"
);

(All settings optional)

Examples:

• define Socket3 NetIO230B 192.168.178.10 3
• define Socket1_and_4 NetIO230B 192.168.178.10 14
• define coffeemaker NetIO230B 192.168.178.10 1 username secretpassword
• define coffeemaker_and_light NetIO230B 192.168.178.10 23 /var/log/kitchen.conf

Get
get <name> state

returns the state of the socket(s)
Example:
get coffeemaker_and_light   => on or off



Set
set <name> <value>

where value is one of:


		on
		off
		

Examples:
set coffeemaker_and_light on

Netzer

[EN DE]

The Netzer realizes an Ethernet interface on a PIC-based platform. As a gateway module it enables communication between standard TCP/IP sockets and serial busses like I2C, SPI and UART. Also up to 13 GPIO pins can be accessed. This Modul provides access to these GPIO pins on a Netzer running IO_base in Version 1.5. There are two pins usable as ADC channel, two as PMW outputs, three as counter and three can generate an interrupt. The GPIO pins are configured a input per default. Before a port can be used as output it must be configured via the embedded webpage. If one of the input ports is configured to send interrupt events on GPIO Server, on every event all port values will be updated. All ports can be read and controlled individually by the function readingsProxy.

Define
define <name> Netzer <host:port>


Set
set <name> <port[_counter]> <value>
Where <value> is a character between a and m
according to the port. If Port attr is cnt an aditional value <port_counter> can be set.
Only ports with corresponding attr Port_[a-m] set to PWM or out can be used.
If Port attr is:
• PWM <value> can be a number between 0 and 1023
• out <value> can be a number between 0 and 1
• cnt <port_counter> <value> can be a number between 0 and 32767


Get
get <name> [<port[_counter]>]
If no <port> is set, all readings will be updated.
<port> is a character between a and m
according to the port. If Port attr is cnt an aditional reading <port_counter> can be read.


Attributes
• poll_interval
  Set the polling interval in minutes to query the sensor for new measured values. Default: 5, valid values: decimal number


• Port_<port>
  
  Configuration for Netzer port.
  <port> is a character between a and m.
  
  • in: Port is defined as input. Same behavior as no attribute. Set is not avaliable for this port.
    Can be used for all ports
  • out: Port is defined as output. Set is avaliable for this port with <value> between 0 and 1.
    Can be used for all ports
  • cnt: Port is defined as input. Set is not avaliable for this port.
    An second reading: Port_<port>_counter is avaiable. It can be updated with get an changed with set.
    Port_<port>_counter <value> = 0-32767 or overflow if outside this range.
    Can be used for ports a,b,c
  • ADC: Port is defined as analog input. Get <value> is 0-1023 according the voltage on port. Set is not avaliable for this port.
    Can be used for ports e,f
  • PWM: Port is defined as PWM output. Set and get <value> is 0-1023 according the duty cycle on the port.
    Can be used for ports d,j

NetzerI2C

[EN DE]

Provides access to Netzer's I2C interfaces for some logical modules and also directly.

preliminary:
Serial Server of Netzer must be activated and configured for I2C .

Define
define <name> NetzerI2C <Device-Address:Port>
where <Device-Address:Port> Device Address/ IP-Address and Serial Server TCP Port of the Netzer


Set
• Write one byte (or more bytes sequentially) directly to an I2C device (for devices that have only one register to write):
  set <name> writeByte <I2C Address> <value>
  
  
• Write one byte (or more bytes sequentially) to the specified register of an I2C device:
  set <name> writeByteReg <I2C Address> <Register Address> <value>
  
  
• Write n-bytes to an register range, beginning at the specified register:
  set <name> writeBlock <I2C Address> <Register Address> <value>
  
  
Examples:
Write 0xAA to device with I2C address 0x60
set test1 writeByte 60 AA
Write 0xAA to register 0x01 of device with I2C address 0x6E
set test1 writeByteReg 6E 01 AA
Write 0xAA to register 0x01 of device with I2C address 0x6E, after it write 0x55 to register 0x02
set test1 writeByteReg 6E 01 AA 55
Write 0xA4 to register 0x03, 0x00 to register 0x04 and 0xDA to register 0x05 of device with I2C address 0x60 as block operation
set test1 writeBlock 60 03 A4 00 DA



Get
get <name> read <I2C Address> [<Register Address> [<number of registers>]]
gets value of I2C device's registers

Examples:
Reads byte from device with I2C address 0x60
get test1 writeByte 60
Reads register 0x01 of device with I2C address 0x6E.
get test1 read 6E 01 AA 55
Reads register 0x03 to 0x06 of device with I2C address 0x60.
get test1 read 60 03 4




Attributes
• ignore
• do_not_notify
• showtime

Netzfrequenz

[EN DE]

displays the actual frenquency of the german power grid

Define
define <name> Netzfrequenz

defines the device.

Neuron

[EN DE]

Module for EVOK driven devices like UniPi Neuron.

Define
define Neuron <IP>[:<Port>]


Set
set <name> <value> [<args>]

where value can be e.g.:

• dev_circuit
  outputs only
  <args>: on, off for outputs and slider for ao
  
• clearreadings
  delete all readings
• websocket
  <arg>: open,close
  open, close websocket connection
• postjson
  <args>: dev circuit type value
  send JSON command to subdevice
  example: set neuron input 1_01 mode simple
For details please refer to UniPi Evok documentation.

Get
get <name> <value> [<arg>]

where value can be

• all: refresh all readings
• config: returns the configuration from the subdevice <arg>
• updt_sets_gets: updates all set and get options
• value: returns the state from the subdevice <arg>

Attributes
• connection
  Set the connection type to the EVOK device
  Default: polling
  valid values: websockets, polling
  
  
• poll_interval
  Set the polling interval in minutes to query all readings (and distribute them to logical devices)
  Default: -
  valid values: decimal number
  
  
• wsFilter
  Filter to limit the list of devices which should send websocket events
  Default: all
  valid values: all, ai, ao, input, led, relay, wd, temp, unit_register
  
  
• logicalDev
  Filter which subdevices should create / communicate with logical device
  Default: ao, input, led, relay
  valid values: ai, ao, input, led, relay, wd, temp, unit_register
  
  
• readingFnAttributes

NeuronPin

[EN DE]

Logical Module for EVOK driven devices. Defines will be automatically created by the Neuron module.
Define
define NeuronPin <dev> <circuit> <Neuron IODev>

<dev> is an device type like input, ai (analog input), relay (digital output) etc.
<circuit> is the number of the device.
<Neuron IODev> is the EVOK device where this subdevice is connected

Example:

      define  NeuronPin_relay_2_01 NeuronPin relay 2_01 Neuron1
    

Set
set <name> <value>

where value can be e.g.:

• for relay
  off
on
The set extensions are also supported for output devices.
  
Other set values depending on the options of the device function. Details can be found in the UniPi Evok documentation.

Get
get <name> <value>

where value can be

• refresh: uptates all readings
• config: returns the configuration JSON

Attributes
• poll_interval
  Set the polling interval in minutes to query all readings
  Default: -
  valid values: decimal number
  
  
• restoreOnStartup
  Restore Readings and sets after reboot
  Default: last
  valid values: last, on, off, no
  
  
• aomax
  Maximum value for the slider from the analog output ports
  Default: 10
  valid values: decimal number
  
  
• skipreadings
  Values which will be sent from the Device and which shall not be listed as readings
  Default: relay_type,typ,dev,circuit,glob_dev_id,value,pending
  valid values: comma separated list
  
  
• ownsets
  Values which will be sent from the Device which can be changed via set. For Values for where the device sends fixed choices, the sets will created automatically
  Default: debounce;counter;interval;pwm_freq;pwm_duty:slider,0,0.1,100
  valid values: semicolon separated list
  
  
• autoalias
  If set to 1, reading alias will automatically change the attribute "alias"
  Default: 1
  valid values: 0,1
  
  
• IODev
• readingFnAttributes
• do_not_notify
• showtime
• disable
• disabledForIntervals

Nextion

[EN DE]

This module connects remotely to a Nextion display that is connected through a ESP8266 or similar serial to network connection Nextion devices are relatively inexpensive tft touch displays, that include also a controller that can hold a user interface and communicates via serial protocol to the outside world.
A description of the Hardwarelayout for connecting the ESP8266 module and the Nextion Dispaly is in the correspdong forum thread https://forum.fhem.de/index.php/topic,51267.0.html.

Define
define <name> Nextion <hostname/ip>:23

Defines a Nextion device on the given hostname / ip and port (should be port 23/telnetport normally)

Example: define nxt Nextion 10.0.0.1:23




Set
set <name> <what> [<value>]

where <what> / <value> is one of


• raw <nextion command>
  Sends the given raw message to the nextion display. The supported commands are described with the Nextion displays: http://wiki.iteadstudio.com/Nextion_Instruction_Set
  Examples:
  

  set nxt raw page 0

  switch the display to page 0
  

  set nxt raw b0.txt

  get the text for button 0
  

• cmd <nextion command>
  same as raw
• page <0 - 9>
  set the page number given as new page on the nextion display.
• pageCmd <one or multiple page numbers separated by ,> <cmds>
  Execute the given commands if the current page on the screen is in the list given as page number.


Attributes


• hasSendMe <0 or 1>
  Specify if the display definition on the Nextion display is using the "send me" checkbox to send current page on page changes. This will then change the reading currentPage accordingly
• initCommands <series of commands>
  Display will be initialized with these commands when the connection to the device is established (or reconnected). Set logic for executing perl or getting readings can be used. Multiple commands will be separated by ;
  Example
    t1.txt="Hallo";p1.val=1;
• initPage1 <series of commands> to initPage9 <series of commands>
  When the corresponding page number will be displayed the given commands will be sent to the display. See also initCommands.
  Example
    t1.txt="Hallo";p1.val=1;
• expectAnswer <1 or 0>
  Specify if an answer from display is expected. If set to zero no answer is expected at any time on a command.


Readings
• received <Hex values of the last received message from the display>
  The message is converted in hex values (old messages are stored in the readings old1 ... old5). Example for a message is H65(e) H00 H04 H00
• rectext <text or empty>
  Translating the received message into text form if possible. Beside predefined data that is sent from the display on specific changes, custom values can be sent in the form $name=value. This can be sent by statements in the Nextion display event code
  print "$bt0="
get bt0.val
• currentPage <page number on the display>
  Shows the number of the UI screen as configured on the Nextion display that is currently shown.
  This is only valid if the attribute hasSendMe is set to 1 and used also in the display definition of the Nextion.
• cmdSent <cmd>
  Last cmd sent to the Nextion Display
• cmdResult <result text>
  Result of the last cmd sent to the display (or empty)

Nmap

[EN DE]

Nmap is the FHEM module to perform a network scan with Nmap and to display information about the available network devices.
If a new device is detected, an event "<name> new host: <hostname> (<IPv4>)" is generated.
If a device with a known MAC address has been given a new IP, an event "<name> new IP: <hostname> (<IPv4>)" is generated.

Prerequisites:
The "Nmap" program and the Perl module "Nmap::Parser" are required.
Under Debian (based) system, these can be installed using "apt-get install nmap libnmap-parser-perl" .



Define

define <name> Nmap <target specification>
In the <target specification> are all target hosts, which are to be scanned.
The simplest case is the description of an IP destination address or a target host name for scanning.
To scan an entire network of neighboring hosts, Nmap supports CIDR-style addresses. Numbits can be appended to an IPv4 address or hostname, and Nmap will scan all IP addresses where the first numbits match those of the given IP or host name. For example, 192.168.10.0/24 would scan the 256 hosts between 192.168.10.0 and 192.168.10.255. 192.168.10.40/24 would scan exactly the same targets. It's also possible to scan multiple networks at the same time. For example 192.168.1.0/24 192.168.2.0/24 would scan the 512 hosts between 192.168.1.0 and 192.168.2.255.
See Nmap Manpage (Specifying Destinations) .

Set

• clear readings
  Deletes all readings except "state".
• deleteOldReadings <s>
  Deletes all readings older than <s> seconds.
• interrupt
  Cancels a running scan.
• statusRequest
  Starts a network scan.

Readings

General Readings:
• NmapVersion
  The version number of the installed Nmap program.
• hostsScanned
  The number of scanned addresses.
• hostsUp
  The number of available network devices.
• knownHosts
  The number of known network devices.
• scanDuration
  The scan time in seconds.
• state
  
  • Initialized
    Nmap has been defined or enabled.
  • running
    A network scan is running.
  • done
    Network scan completed successfully.
  • aborted
    The network scan was aborted due to a timeout or by the user.
  • disabled
    Nmap has been disabled.

Host-specific readings:
• <metaReading>_alias
  Alias ​​which is specified under the attribute "devAlias" for the network device. If no alias is specified, the hostname is displayed.
• <metaReading>_hostname
  Hostname of the network device. If this can not be determined, the IPv4 address is displayed.
• <metaReading>_ip
  IPv4 address of the network device.
• <metaReading>_lastSeen
  The time at which the network device was last seen as.
• <metaReading>_macAddress
  MAC address of the network device. This can only be determined if the scan is executed with root privileges.
• <metaReading>_macVendor
  Probable manufacturer of the network device. This can only be determined if the scan is executed with root privileges.
• <metaReading>_state
  State of the network device. Can be either "absent" or "present".
• <metaReading>_uptime
  Time in seconds since the network device is reachable.
• <metaReading>_uptimeText
  Time in "d days, hh hours, mm minutes, ss seconds" since the network device is reachable.

Attributes

• absenceThreshold <n>
  The number of network cans that must result in "absent" before the state of a network device changes to "absent". With this function you can verify the absence of a device before the status is changed to "absent". If this attribute is set to a value >1, the reading "<metaReading>_state" remains on "present" until the final status changes to "absent".
• args <args>
  Arguments for the Nmap scan.
  The default is "-sn".
• deleteOldReadings <s>
  After a network scan, all host-specific readings older than <s> seconds are deleted
• devAlias <ID>:<ALIAS> <ID2>:<ALIAS2> ...
  A whitespace separated list of <ID>:<ALIAS> pairs that can be used to give an alias to network devices.
  The ID can be MAC address, hostname or IPv4 address.
  Examples:
  MAC address: attr <name> devAlias 5C:51:88:A5:94:1F:Michaels_Handy_byMAC
  Hostname: attr <name> devAlias android-87c7a6221093d830:Michaels_Handy_byHOST
  IPv4 address: attr <name> devAlias 192.168.1.130:Michaels_Handy_byIP
  
• disable 1
  A running scan is canceled and no new scans are started.
• excludeHosts <target specification>
  All target hosts in the <target specification> are skipped during the scan.
• interval <seconds>
  Interval in seconds in which the scan is performed.
  The default value is 900 seconds and the minimum value is 30 seconds.
• keepReadings 1
  If a new IP address is recognized for a device with a known MAC address, the invalid readings are deleted unless this attribute is set.
• leadingZeros 1
  For the readings, the IPv4 addresses are displayed with leading zeros.
• metaReading <metaReading>
  You can specify "alias", "hostname", "ip" or "macAddress" as <metaReading> and is the identifier for the readings.
  The default is "ip".
• path
  Path under which the Nmap program is to be reached.
  The default is "/urs/bin/nmap".
• readingFnAttributes
• sudo 1
  The scan runs with root privileges.
  The prerequisite is that the user has these rights under the FHEM. For the user "fhem", on a Debian (based) system, they can be set in the "/etc/sudoers" file. For this, the line "fhem ALL=(ALL) NOPASSWD: /usr/bin/nmap" must be inserted in the section "#User privilege specification".

NotifyAndroidTV

[EN DE]

This module allows you to send notifications to the Notifications for Android TV and Notifications for Fire TV apps.

set <name> msg bkgcolor=amber interrupt=true position=top-left transparency=0% duration=2 offset=10 icon=fhemicon title="der titel" das ist ein test

Define
define <name> NotifyAndroidTV <host>


Set
• msg [options] <message>
  possible options are: bkgcolor, interrupt, position, transparency, duration, offset, offsety, width, type, fontsize, icon, image, title, imageurl. use set <name> notify to see valid values.
  set nb msg ? shows a help text
  it is better to use imageurl instad of image as it is non blocking!
  image can be given as image={<perlCode>}

Get
none

Attr
none

OBIS

[EN DE]

This module is for SmartMeters, that report their data in OBIS-Standard. It doesn't matter, whether the data comes as PlainText or SML-encoded.

Define
define <name> OBIS device|none [MeterType]

<device> specifies the serial port or hostname/ip-address:port to communicate with the smartmeter. For Tibber Pulse and requesting via HTTP, specify the URL in the LAN. In case of a serial device and with Linux:
• the device will be named /dev/ttyUSBx, where x is a number.
• or - to avoid wrong numbering on server reboots - use the ID of the USB device, e.g. /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A106Q3OW-if00-port0
You may specify the baudrate used after the @ char, 9600 is common

If you use a ser2net connection, <device> is ip-address:port or hostname:port.

Optional: MeterType can be of
• VSM102 -> Voltcraft VSM102
• E110 -> Landis&&;Gyr E110
• E350USB -> Landis&&;Gyr E350 USB-Version
• MT382 -> ISKRA MT382
• Standard -> Data comes as plainText
• SML -> Smart Message Language

Example:
define myPowerMeter OBIS /dev/ttyPlugwise@9600,7,E,1 VSM102
define myPowerMeter OBIS 192.168.0.12:1234 Standard


Attributes
• offset_feed
offset_energy
  If your smartmeter is BEHIND the meter of your powersupplier, then you can hereby adjust the total-reading of your SM to that of your official one.
• channels
  With this, you can rename the reported channels.
  e.g.: attr myOBIS channels {"1.0.96.5.5.255"=>"Status","1.0.0.0.0.255"=>"Info","16.7"=>"Verbrauch"}
• directions
  Some Meters report feeding/comnsuming of power in a statusword. If this is set, you get an extra reading dir_total_consumption which defaults to "in" and "out".
  Here, you can change this text with, e.g.: attr myOBIS directions {">" => "pwr consuming", "<"=>"pwr feeding"}
• extChannels
  Possible values:
  auto (default). The values 0 and 255 will give the base counter name like with off. Values from 96 to 100 add a postfix "_last1d" / "_last7d", "_last30d", "_last365d" and "_since_rst" to the reading. Other values lead to results like "on".
  off Historical values are not considered and might overwrite current values.
  on Every counter-reading gets appended by the extChannel-number, e.g. total_consumption becomes total_consumption.255
• interval
  The polling-interval in seconds. (Only useful in Polling-Mode)
• alignTime
  Aligns the intervals to a given time. Each interval is repeatedly calculated. So if alignTime=00:00 and interval=600 aligns the interval to xx:00:00, xx:10:00, xx:20:00 etc....
• pollingMode
  Changes from direct-read to polling-mode. Useful with meters, that send a continous datastream. Reduces CPU-load.
• unitReadings
  Adds the units to the readings like w, wH, A etc.
• valueBracket
  Sets, if to use the value from the first or the second bracket, if applicable. Standard is "second"
• resetAfterNoDataTime
  If on a TCP-connection no data was received for the given time, the connection is closed and reopened
• httpAuthorization
  If the SML data is fetched by HTTP (Usecase: e.g. Tibber Pulse), this attribute is used to authenticate the HTTP-request. The format must be :, e.g. for Tibber Pulse something like "admin:"
• nohacks
  For DZG- and HOLY-Meters a workaround was implemented to avoid certain bugs in encoding. Latest DZG meters seem to have fixed the bug. By setting "nohacks" to "1", the workarounds are disabled.

ONKYO_AVR

[EN DE]

Define
define <name> ONKYO_AVR <ip-address-or-hostname[:PORT]> [<protocol-version>]
define <name> ONKYO_AVR <devicename[@baudrate]> [<protocol-version>]

This module controls ONKYO A/V receivers in real-time via network connection.
Some newer Pioneer A/V models seem to run ONKYO's ISCP protocol as well and therefore should be fully supported by this module.
Use ONKYO_AVR_ZONE to control slave zones.

Instead of IP address or hostname you may set a serial connection format for direct connectivity.


Example:

define avr ONKYO_AVR 192.168.0.10

# With explicit port
define avr ONKYO_AVR 192.168.0.10:60128

# With explicit protocol version 2013 and later
define avr ONKYO_AVR 192.168.0.10 2013

# With protocol version prior 2013
define avr ONKYO_AVR 192.168.0.10 pre2013
# With protocol version prior 2013 and serial connection
define avr ONKYO_AVR /dev/ttyUSB1@9600 pre2013


Set
set <name> <command> [<parameter>]

Currently, the following commands are defined:

• channel   -   set active network service (e.g. Spotify)
• currentTrackPosition   -   seek to specific time for current track
• input   -   switches between inputs
• inputDown   -   switches one input down
• inputUp   -   switches one input up
• mute on,off   -   controls volume mute
• muteT   -   toggle mute state
• next   -   skip track
• off   -   turns the device in standby mode
• on   -   powers on the device
• pause   -   pause current playback
• play   -   start playback
• power on,off   -   set power mode
• preset   -   switches between presets
• presetDown   -   switches one preset down
• presetUp   -   switches one preset up
• previous   -   back to previous track
• rawCommand Send raw command to device. No space between command and value (eg. TFRB+9 to set bass level to +9)
• remoteControl Send specific remoteControl command to device
• repeat off,all,all-folder,one   -   set repeat setting
• repeatT   -   toggle repeat state
• shuffle off,on,on-album,on-folder   -   set shuffle setting
• shuffleT   -   toggle shuffle state
• sleep 1..90,off   -   sets auto-turnoff after X minutes
• stop   -   stop current playback
• toggle   -   switch between on and off
• volume 0...100   -   set the volume level in percentage
• volumeUp   -   increases the volume level
• volumeDown   -   decreases the volume level

Other set commands may appear dynamically based on previously used "get avr remoteControl"-commands and resulting readings.
See "get avr remoteControl <Set-name> help" to get more information about possible readings and set values.


Get
get <name> <what>

Currently, the following commands are defined:


• createZone   -   creates a separate ONKYO_AVR_ZONE device for available zones of the device
• remoteControl   -   sends advanced remote control commands based on current zone; you may use "get avr remoteControl <Get-command> help" to see details about possible values and resulting readings. In Case the device does not support the command, just nothing happens as normally the device does not send any response. In case the command is temporarily not available you may see according feedback from the log file using attribute verbose=4.
• statusRequest   -   clears cached settings and re-reads device XML configurations


Attributes
• connectionCheck   1..120,off   Pings the device every X seconds to verify connection status. Defaults to 60 seconds.
• inputs   -   List of inputs, auto-generated after first connection to the device. Inputs may be deleted or re-ordered as required. To rename an input, one needs to put a comma behind the current name and enter the new name.
• model   -   Contains the model name of the device. Cannot not be changed manually as it is going to be overwritten be the module.
• volumeSteps   -   When using set commands volumeUp or volumeDown, the volume will be increased or decreased by these steps. Defaults to 1.
• volumeMax   1...100   When set, any volume higher than this is going to be replaced by this value.
• wakeupCmd   -   In case the device is unreachable and one is sending set command "on", this FHEM command will be executed before the actual "on" command is sent. E.g. may be used to turn on a switch before the device becomes available via network.


Generated Readings/Events:

• audin_* - Shows technical details about current audio input
• brand - Shows brand name of the device manufacturer
• channel - Shows current network service name when (e.g. streaming services like Spotify); part of FHEM-4-AV-Devices compatibility
• currentAlbum - Shows current Album information; part of FHEM-4-AV-Devices compatibility
• currentArtist - Shows current Artist information; part of FHEM-4-AV-Devices compatibility
• currentMedia - currently no in use
• currentTitle - Shows current Title information; part of FHEM-4-AV-Devices compatibility
• currentTrack* - Shows current track timer information; part of FHEM-4-AV-Devices compatibility
• deviceid - Shows device name as set in device settings
• deviceyear - Shows model device year
• firmwareversion - Shows current firmware version
• input - Shows currently used input; part of FHEM-4-AV-Devices compatibility
• mute - Reports the mute status of the device (can be "on" or "off")
• playStatus - Shows current network service playback status; part of FHEM-4-AV-Devices compatibility
• power - Reports the power status of the device (can be "on" or "off")
• presence - Reports the presence status of the receiver (can be "absent" or "present"). In case of an absent device, control is not possible.
• repeat - Shows current network service repeat status; part of FHEM-4-AV-Devices compatibility
• screen* - Experimental: Gives some information about text that is being shown via on-screen menu
• shuffle - Shows current network service shuffle status; part of FHEM-4-AV-Devices compatibility
• sleep - Reports current sleep state (can be "off" or shows timer in minutes)
• state - Reports current network connection status to the device
• stateAV - Zone status from user perspective combining readings presence, power, mute and playStatus to a useful overall status.
• volume - Reports current volume level of the receiver in percentage values (between 0 and 100 %)
• vidin_* - Shows technical details about current video input before image processing
• vidout_* - Shows technical details about current video output after image processing
• zones - Shows total available zones of device

Using remoteControl get-command might result in creating new readings in case the device sends any data.

ONKYO_AVR_ZONE

[EN DE]

Define
define <name> ONKYO_AVR_ZONE [<zone-id>]

This is a supplement module for ONKYO_AVR representing zones.

Example:

define avr ONKYO_AVR_ZONE

# For zone2
define avr ONKYO_AVR_ZONE 2

# For zone3
define avr ONKYO_AVR_ZONE 3

# For zone4
define avr ONKYO_AVR_ZONE 4


Set
set <name> <command> [<parameter>]

Currently, the following commands are defined:

• channel   -   set active network service (e.g. Spotify)
• input   -   switches between inputs
• inputDown   -   switches one input down
• inputUp   -   switches one input up
• mute on,off   -   controls volume mute
• muteT   -   toggle mute state
• next   -   skip track
• off   -   turns the device in standby mode
• on   -   powers on the device
• pause   -   pause current playback
• play   -   start playback
• power on,off   -   set power mode
• preset   -   switches between presets
• presetDown   -   switches one preset down
• presetUp   -   switches one preset up
• previous   -   back to previous track
• remoteControl Send specific remoteControl command to device
• repeat off,all,all-folder,one   -   set repeat setting
• repeatT   -   toggle repeat state
• shuffle off,on,on-album,on-folder   -   set shuffle setting
• shuffleT   -   toggle shuffle state
• sleep 1..90,off   -   sets auto-turnoff after X minutes
• stop   -   stop current playback
• toggle   -   switch between on and off
• volume 0...100   -   set the volume level in percentage
• volumeUp   -   increases the volume level
• volumeDown   -   decreases the volume level

Other set commands may appear dynamically based on previously used "get avr remoteControl"-commands and resulting readings.
See "get avr remoteControl <Set-name> help" to get more information about possible readings and set values.


Get
get <name> <what>

Currently, the following commands are defined:


• createZone   -   creates a separate ONKYO_AVR_ZONE device for available zones of the device
• remoteControl   -   sends advanced remote control commands based on current zone; you may use "get avr remoteControl <Get-command> help" to see details about possible values and resulting readings. In Case the device does not support the command, just nothing happens as normally the device does not send any response. In case the command is temporarily not available you may see according feedback from the log file using attribute verbose=4.


Attributes
• inputs   -   List of inputs, auto-generated after first connection to the device. Inputs may be deleted or re-ordered as required. To rename an input, one needs to put a comma behind the current name and enter the new name.
• volumeSteps   -   When using set commands volumeUp or volumeDown, the volume will be increased or decreased by these steps. Defaults to 1.
• volumeMax   1...100   When set, any volume higher than this is going to be replaced by this value.
• wakeupCmd   -   In case the device is unreachable and one is sending set command "on", this FHEM command will be executed before the actual "on" command is sent. E.g. may be used to turn on a switch before the device becomes available via network.


Generated Readings/Events:

• channel - Shows current network service name when (e.g. streaming services like Spotify); part of FHEM-4-AV-Devices compatibility
• currentAlbum - Shows current Album information; part of FHEM-4-AV-Devices compatibility
• currentArtist - Shows current Artist information; part of FHEM-4-AV-Devices compatibility
• currentMedia - currently no in use
• currentTitle - Shows current Title information; part of FHEM-4-AV-Devices compatibility
• currentTrack* - Shows current track timer information; part of FHEM-4-AV-Devices compatibility
• input - Shows currently used input; part of FHEM-4-AV-Devices compatibility
• mute - Reports the mute status of the device (can be "on" or "off")
• playStatus - Shows current network service playback status; part of FHEM-4-AV-Devices compatibility
• power - Reports the power status of the device (can be "on" or "off")
• presence - Reports the presence status of the receiver (can be "absent" or "present"). In case of an absent device, control is not possible.
• repeat - Shows current network service repeat status; part of FHEM-4-AV-Devices compatibility
• shuffle - Shows current network service shuffle status; part of FHEM-4-AV-Devices compatibility
• state - Reports current network connection status to the device
• stateAV - Zone status from user perspective combining readings presence, power, mute and playStatus to a useful overall status.
• volume - Reports current volume level of the receiver in percentage values (between 0 and 100 %)

Using remoteControl get-command might result in creating new readings in case the device sends any data.

OPENWEATHER

[EN DE]

The module extracts weather data via the openweather API of www.wetter.com.
It requires a registration on this website to obtain the necessary parameters.
It uses the perl modules HTTP::Request, LWP::UserAgent, HTML::Parse and Digest::MD5.

Define

define <name> OPENWEATHER <project> <cityCode> <apiKey> [language]
Example:
define wetter OPENWEATHER projectx DE0001020 3c551bc20819c19ee88d

To obtain the below parameter you have to create a new project on www.wetter.com.


• <project>
  Name of the 'openweather' project (create with a user account on wetter.com).


• <cityCode>
  Code of the location for which the forecast is requested. The code is part of the URL of the weather forecast page. For example DE0009042 in:
  http://www.wetter.com/wetter_aktuell/aktuelles_wetter/deutschland/rostock/DE0009042.html


• <apiKey>
  Secret key that is provided when the user creates a 'openweather' project on wetter.com.


• [language]
  Optional. Default language of weather description is German. Change with en to English or es to Spanish.

The function OPENWEATHER_Html creates a HTML code for a vertically arranged weather forecast.
Example:
define MyForecast weblink htmlCode { OPENWEATHER_Html("MyWeather") }


Set


• set <name> update
  The weather data are immediately polled from the website.


Get


• get <name> apiResponse
  Shows the response of the web site.


Attributes


• disable <0 | 1>
  Automatic update is stopped if set to 1.


• INTERVAL <seconds>
  Polling interval for weather data in seconds (default and smallest value is 3600 = 1 hour). 0 will stop automatic updates.


• readingFnAttributes

Forecast readings
Note! The forecast values (in brackets) have first to be selected on the project setup page on wetter.com.
 

• fc0|1|2_... - forecast values for today|tomorrow|in 2 days
• fc0_...06|11|17|23 - forecast values for today at 06|11|17|23 o'clock
• fc1_tempMin|Max - minimal|maximal temperature for tomorrow in °C (tn,tx)
• fc0_tempMin06 - minimal temperaturetoday at 06:00 o'clock in °C
• fc0_chOfRain - chance of rain today in % (pc)
• fc0_valHours06 - validity period in hours of the forecast values starting at 06:00 o'clock (p)
• fc0_weather - weather situation today in German (w_txt)
• fc0_weatherCode - code of weather situation today (w)
• fc0_wday - German abbreviation of week day of today (d)
• fc0_wind - wind speed today in km/h (ws)
• fc0_windDir - wind direction today in ° (degree) (wd)
• fc0_windDirTxt - wind direction today in text form (wd_txt
• etc.

OREGON

[EN DE]

The OREGON module interprets Oregon sensor messages received by a RFXCOM or SIGNALduino or CUx receiver. You need to define a receiver (RFXCOM, SIGNALduino or CUx) first. See RFXCOM. See SIGNALduino.

Define
define <name> OREGON <deviceid>

<deviceid> is the device identifier of the Oregon sensor. It consists of the sensors name and a one byte hex string (00-ff) that identifies the sensor. The define statement with the deviceid is generated automatically by autocreate. The following sensor names are used: BTHR918, BTHR918N, PCR800 RGR918, RTGR328N, THN132N, THGR228N, THGR328N, THGR918, THR128, THWR288A, THGR810, UV138, UVN800, WGR918, WGR800, WTGR800_A, WTGR800_T.
The one byte hex string is generated by the Oregon sensor when is it powered on. The value seems to be randomly generated. This has the advantage that you may use more than one Oregon sensor of the same type even if it has no switch to set a sensor id. For exampple the author uses three BTHR918 sensors at the same time. All have different deviceids. The drawback is that the deviceid changes after changing batteries.

Example:
define Kaminzimmer OREGON BTHR918N_ab


Set
N/A

Get
N/A

Attributes
• IODev
• do_not_notify
• ignore
• showtime
• readingFnAttributes

OW2SMSGUARD.

[EN DE]

FHEM Forum : 1Wire
Define

define <name> OW2S0SMSGUARD <IO Device> [interval]

Example :
define myOW2S0 OW2S0SMSGUARD /dev/ttyUSB0@38400
define myOW2S0 OW2S0SMSGUARD /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A702PE1J-if00-port0@38400
define myOW2S0 OW2S0SMSGUARD 192.168.0.100:2000 (socat, ser2net)

Set

• reset IO device ( master only )


• S0-reset : reset of both S0 counters ( master only )


• deleteDS2401 : deletes reading and defined sub device ( master only )

Get

• list of found OW devices ( master only )

Attributes

• A_calc_mode ( master only ) after, before, never, default before
  
  
• B_calc_mode ( master only ) after, before, never, default before
  
  
• A_calc_current ( master only ) default 0, A_calc_mode must be after or before
  
  
• B_calc_current ( master only ) default 0, B_calc_mode must be after or before
  
  
• A_offset ( master only )
  
  
• B_offset ( master only )
  
  
• DS2401_Timeout ( master only ) , default 1.5 x Interval
  
  
• mapOWIDs ( master only )
  Comma separeted list of ID=Name pairs
  Example : 10D64CBF02080077=Badezimmer, 01E5D9370B00005D=Kellerfenster
  
  
• model
  only for FHEM modul statistics at https://fhem.de/stats/statistics.html
  
  
• useSubDevices ( master only ) , default 0
  create for each found device on the bus a separate subdevice
  
  
• delay ( master only ) , default 0.5 seconds to read OW device values
  
  

OWAD

[EN DE]

FHEM module to commmunicate with 1-Wire A/D converters


This 1-Wire module works with the OWX interface module or with the OWServer interface module (prerequisite: Add this module's name to the list of clients in OWServer). Please define an OWX device or OWServer device first.





Example

define OWX_AD OWAD 724610000000 45
attr OWX_AD DAlarm high
attr OWX_AD DName humidity
attr OWX_AD DUnit %
attr OWX_AD DFunction VD*31.907097-0.8088
attr OWX_AD DHigh 50.0





Define

define <name> OWAD [<model>] <id> [<interval>] or
define <name> OWAD <fam>.<id> [<interval>]

Define a 1-Wire A/D converter.



• [<model>]
  Defines the A/D converter model (and thus 1-Wire family id), currently the following values are permitted:
  • model DS2450 with family id 20 (default if the model parameter is omitted)
• <fam>
  2-character unique family id, see above
• <id>
  12-character unique ROM id of the converter device without family id and CRC code
• <interval>
  Measurement interval in seconds. The default is 300 seconds, a value of 0 disables the automatic update.



Set

• set <name> initialize
  Re-initialize the sensor device (range, resolution etc.). Necessary after power loss.
• set <name> (A|B|C|D)Alarm (none|low|high|both) Set the device into alarme status if none, the high, low or both voltage limits are reached.
• set <name> (A|B|C|D)(Low|High) <voltage value> Set one of the voltage limits for alarm status
• set <name> interval <int>
  Measurement interval in seconds. The default is 300 seconds, a value of 0 disables the automatic update.



Get

• get <name> id
  Returns the full 1-Wire device id OW_FAMILY.ROM_ID.CRC
• get <name> reading
  Obtain the measuement values.
• get <name> alarm
  Obtain the alarm values.
• get <name> status
  Obtain the i/o status values.



Attributes

• attr <name> stateAL0 <string>
  character string for denoting low normal condition, default is empty
• attr <name> stateAH0 <string>
  character string for denoting high normal condition, default is empty
• attr <name> stateAL1 <string>
  character string for denoting low alarm condition, default is ↓
• attr <name> stateAH1 <string>
  character string for denoting high alarm condition, default is ↑
• attr <name> interval <int>
  Measurement interval in seconds. The default is 300 seconds, a value of 0 disables the automatic update.
For each of the following attributes, the channel identification A,B,C,D may be used.
• attr <name> <channel>Name <string>[|<string>]
  name for the channel [|short name used in state reading].
• attr <name> <channel>Unit <string>
  unit of measurement for this channel used in state reading (default "V", set to "none" for empty).
• attr <name> <channel>Function <string>
  arbitrary functional expression involving the variables VA,VB,VC,VD. VA is replaced by the (raw) measured voltage in channel A, etc. This attribute allows linearization of measurement curves as well as the mixing of various channels.
• attr <name> <channel>Alarm <string>
  alarm setting in this channel, either both, low, high or none (default).
• attr <name> <channel>Low <float>
  measurement value for low alarm.
• attr <name> <channel>High <float>
  measurement value for highalarm.
• readingFnAttributes

OWCOUNT

[EN DE]

FHEM module to commmunicate with 1-Wire Counter/RAM DS2423 or its emulation DS2423emu

This 1-Wire module works with the OWX interface module or with the OWServer interface module (prerequisite: Add this module's name to the list of clients in OWServer). Please define an OWX device or OWServer device first.





Example


define OWC OWCOUNT 1D.CE780F000000 60
attr OWC AName energy|W
attr OWC AUnit kWh
attr OWC APeriod hour
attr OWC ARate power|P
attr OWX_AMode daily



Define

define <name> OWCOUNT [<model>] <id> [<interval>] or
define <name> OWCOUNT <fam>.<id> [<interval>]

Define a 1-Wire counter.



• [<model>]
  Defines the counter model (and thus 1-Wire family id), currently the following values are permitted:
  • model DS2423 with family id 1D (default if the model parameter is omitted)
  • model DS2423enew with family id 1D - emulator, works like DS2423
  • model DS2423eold with family id 1D - emulator, works like DS2423 except that the internal memory is not present
• <fam>
  2-character unique family id, see above
• <id>
  12-character unique ROM id of the converter device without family id and CRC code
• <interval>
  Measurement interval in seconds. The default is 300 seconds, a value of 0 disables the automatic update.



Set

• set <name> interval <int>
  Measurement interval in seconds. The default is 300 seconds, a value of 0 disables the automatic update. Log line after each interval <date> <name> <channel>: <value> <unit> <value> / <unit>/<period> <channel>: <value> <unit> / <value> <unit>/<period>
  example: 2012-07-30_00:07:55 OWX_C Taste: 17.03 p 28.1 p/h B: 7.0 cts 0.0 cts/min
• set <name> memory <page> <string>
  Write 32 bytes to memory page 0..13
• set <name> midnight <channel-name> <val>
  Write the day's starting value for counter <channel> (A, B or named channel, see below)
• set <name> counter <channel-name> <val>
  Correct the midnight value such that counter <channel> (A, B or named channel, see below) displays value <val>



Get

• get <name> id
  Returns the full 1-Wire device id OW_FAMILY.ROM_ID.CRC
• get <name> memory <page>
  Obtain 32 bytes from memory page 0..13 and store in cache $hash->{owg_str}->[page] as well as in reading "memory"
• get <name> mcache <page>
  Obtain 32 bytes from cache $hash->{owg_str}->[page] and display.
• get <name> midnight <channel-name>
  Obtain the day's starting value for counter <channel> (A, B or named channel, see below)
• get <name> month
  Returns cumulated and averaged monthly value if mode=daily, otherwise last day's and averaged value
• get <name> year
  Returns cumulated and averaged yearly value if mode=daily, otherwise last months's and averaged value
• get <name> raw <channel-name>
  Obtain the current raw value for counter <channel> (A, B or named channel, see below)
• get <name> counters
  Obtain the current value both counters



Attributes

• attr <name> LogM <string>
  device name (not file name) of monthly log file. Log line after midnight <new date> <name> <old day> <old date> <channel>: <value> <unit> <channel>: <value> <unit>
  example: 2012-07-30_00:00:57 OWX_C D29: 2012-7-29_23:59:59 Taste: 110.0 p, B: 7.0 cts
• attr <name> LogY <string>
  device name (not file name) of yearly log file.
• attr <name> interval <int>
  Measurement interval in seconds. The default is 300 seconds, a value of 0 disables the automatic update.
• attr <name> nomemory 0|1
  when set to 1, midnight values will be stored in files instead of the internal memory.

For each of the following attributes, the channel identification A,B may be used.

• attr <name> <channel>Name <string>[|<string>]
  name for the channel [|short name used in state reading].
• attr <name> <channel>Unit <string&
  unit of measurement used in state reading (default "cts", set to "none" for empty).
• attr <name> <channel>Rate <string>[|<string>]
  name for the channel rate [|short name used in state reading]
• attr <name> <channel>Offset <float>
  offset added to the reading in this channel.
• attr <name> <channel>Factor <float>
  factor multiplied to (reading+offset) in this channel.
• attr <name> <channel>Mode daily | normal
  determines whether counter is nulled at start of day or running continuously
• attr <name> <channel>Period hour(default) | minute | second
  period for rate calculation
• readingFnAttributes

OWDevice

[EN DE]

Define
define <name> OWDevice <address> [<interval>]

Defines a 1-wire device. The 1-wire device is identified by its <address>. It is served by the most recently defined OWServer.

Devices beyond 1-wire hubs (DS2409, address family 1F) need to be addressed by the full path, e.g. 1F.0AC004000000/main/26.A157B6000000 (no leading slash). They are not automatically detected.

If <interval> is given, the OWServer is polled every <interval> seconds for a subset of readings.

OWDevice is a generic device. Its characteristics are retrieved at the time of the device's definition. The available readings that you can get or set as well as those that are regularly retrieved by polling can be seen when issuing the list <name> command.

The following devices are currently supported:
• DS2401 - Silicon Serial Number
• DS1990A - Serial Number iButton
• DS2405 - Addressable Switch
• DS18S20 - High-Precision 1-Wire Digital Thermometer
• DS1920 - iButton version of the thermometer
• DS2406, DS2407 - Dual Addressable Switch with 1kbit Memory
• DS2436 - Battery ID/Monitor Chip
• DS2423 - 4kbit 1-Wire RAM with Counter
• DS2450 - Quad A/D Converter
• DS1822 - Econo 1-Wire Digital Thermometer
• DS2433 - 4kbit 1-Wire RAM
• DS2415 - 1-Wire Time Chip
• DS1904 - RTC iButton
• DS2438 - Smart Battery Monitor
• DS2417 - 1-Wire Time Chip with Interrupt
• DS18B20 - Programmable Resolution 1-Wire Digital Thermometer
• DS2408 - 1-Wire 8 Channel Addressable Switch
• DS2413 - Dual Channel Addressable Switch
• DS1825 - Programmable Resolution 1-Wire Digital Thermometer with ID
• DS2409 - Microlan Coupler (no function implemented)
• EDS0066 - Multisensor for temperature and pressure
• LCD - LCD controller by Louis Swart


Adding more devices is simple. Look at the code (subroutine OWDevice_GetDetails).

This module is completely unrelated to the 1-wire modules with names all in uppercase.

Note:The state reading never triggers events to avoid confusion.

Example:
define myOWServer OWServer localhost:4304

get myOWServer devices
10.487653020800 DS18S20

define myT1 OWDevice 10.487653020800

list myT1 10.487653020800
Internals:
...
Readings:
2012-12-22 20:30:07 temperature 23.1875
Fhem:
...
getters:
address
family
id
power
type
temperature
templow
temphigh
polls:
temperature
setters:
alias
templow
temphigh
...



Set
• set <name> interval <value>

value modifies the interval for polling data. The unit is in seconds.
• set <name> <reading> <value>
  
  Sets <reading> to <value> for the 1-wire device <name>. The permitted values are defined by the underlying 1-wire device type.
  
  Example:
  set myT1 templow 5
  
  
  
Get
get <name> <reading> <value>

Gets <reading> for the 1-wire device <name>. The permitted values are defined by the underlying 1-wire device type.

Example:
get myT1 temperature



Attributes
• IODev: Set the OWServer device which should be used for sending and receiving data for this OWDevice. Note: Upon startup fhem assigns each OWDevice to the last previously defined OWServer. Thus it is best if you define OWServer and OWDevices in blocks: first define the first OWServer and the OWDevices that belong to it, then continue with the next OWServer and the attached OWDevices, and so on.
• trimvalues: removes leading and trailing whitespace from readings. Default is 1 (on).
• cstrings: interprets reading as C-style string, i.e. stops reading on the first zero byte. Default is 0 (off).
• polls: a comma-separated list of readings to poll. This supersedes the list of default readings to poll.
• disable: set to 1 to disable polling.
• interfaces: supersedes the interfaces exposed by that device.
• model: preset with device type, e.g. DS18S20.
• resolution: resolution of temperature reading in bits, can be 9, 10, 11 or 12. Lower resolutions allow for faster retrieval of values from the bus. Particularly reasonable for large 1-wire installations to reduce busy times for FHEM.
• eventMap
• readingFnAttributes

OWID

[EN DE]

FHEM module for 1-Wire devices that know only their unique ROM ID

This 1-Wire module works with the OWX interface module or with the OWServer interface module Please define an OWX device or OWServer device first.





Example




define ROM1 OWX_ID OWCOUNT 09.CE780F000000 10





Define

define <name> OWID <fam> <id> [<interval>] or
define <name> OWID <fam>.<id> [<interval>]

Define a 1-Wire device.



• <fam>
  2-character unique family id, see above
• <id>
  12-character unique ROM id of the converter device without family id and CRC code
• <interval>
  Interval in seconds for checking the presence of the device. The default is 300 seconds.



Set

• set <name> interval <int>
  Interval in seconds for checking the presence of the device. The default is 300 seconds.



Get

• get <name> id
  Returns the full 1-Wire device id OW_FAMILY.ROM_ID.CRC
• get <name> present
  Returns 1 if this 1-Wire device is present, otherwise 0.

Attributes

• attr <name> interval <int>
  Measurement interval in seconds. The default is 300 seconds, a value of 0 disables the automatic update.
• readingFnAttributes

OWLCD

[EN DE]

FHEM module to commmunicate with the 1-Wire LCD controller from Louis Swart (1-Wire family id FF). See also the corresponding Wiki page.

Note:
This 1-Wire module so far works only with the OWX interface module. Please define an OWX device first.





Example

define OWX_LCD OWLCD 9F0700000100





Define

define <name> OWLCD <id> or
define <name> OWLCD FF.<id>

Define a 1-Wire LCD device.



• <id>
  12-character unique ROM id of the converter device without family id and CRC code



Set

• set <name> icon <int> on|off|blink
  Set one of the icons 0..14 on, off or blinking
• set <name> icon 15 0..6
  Set icon 15 to one of its values
• set <name> icon none
  Set all icons off
• set <name> line <int> <string>
  Write LCD line 0..3 with some content
• set <name> memory <page> <string>
  Write memory page 0..6
• set <name> gpio <value>
  Write state for all three gpio pins (value = 0..7, for each bit 0=ON, 1=OFF)
• set <name> gpiobit <bit> <value>
  Write state for gpio pin no. 1..3, possible values are 0=ON, 1=OFF
• set <name> backlight ON|OFF
  Switch backlight on or off
• set <name> lcd ON|OFF
  Switch LCD power on or off
• set <name> reset
  Reset the display
• set <name> test
  Test the display



Get

• get <name> id
  Returns the full 1-Wire device id OW_FAMILY.ROM_ID.CRC
• get <name> memory <page>
  Read memory page 0..6
• get <name> gpio
  Obtain state of all four input channels (15 = all off, 0 = all on)
• get <name> counter
  Obtain state of all four input counters (4 x 16 Bit)
• get <name> version
  Obtain firmware version of the controller



Attributes

• attr <name> lcdgeometry <string>
  LCD geometry, values are 0-32-64-96 (default) or 0-64-20-84
• attr <name> lcdcontroller <string>
  LCD geometry, values are KS0073 (default) HD44780
• readingFnAttributes

OWMULTI

[EN DE]

FHEM module to commmunicate with 1-Wire smart battery monitor DS2438

This 1-Wire module works with the OWX interface module or with the OWServer interface module (prerequisite: Add this module's name to the list of clients in OWServer). Please define an OWX device or OWServer device first.

Example

In this example, the DS2438 is used to monitor a rechargeable battery of 8.5 V and 8.8 Ah capacity. For this capacity the data sheet of the DS2438 suggests a resistor of 0.015 Ohm across the Vsense+ ... Vsense- terminals.

define USV OWMULTI 7C5034010000 30
attr USV VName battery voltage|Vbatt
attr USV WName battery current|Ibatt
attr USV WUnit mA
attr USV WFunction 1000*W/0.015
attr USV XName battery capacity|Cbatt
attr USV XUnit mAh
attr USV XFunction 8800-1000*(255/2048.-X)/0.015

Notes:
• The voltage at the VAD terminal must be in the range from 2.4 ... 10 V
• The voltage between the Vsense+ and Vsense- terminals must be in the range from -0.25 ... 0.25 V
• For calibration of the Vsense measurement:
  1. Execute the command set <name> offset 0 to clear the offset register
  2. Force zero voltage across the Vsense+ and Vsense- terminals (=zero current)
  3. Execute the command set <name> calibrate to set the offset register
• Due to the limitations of the integration process, the value functions for the sense channel WFunction and for the sense integrated channel XFunction must be functions involving a linear and a constant term, see example above.
• To obtain the proper current in A, one must set WFunction to the value of (W/resistor value).
• The maximum value for the Vsense.t integration is 255/2048 = 0.1245117 Vh. This value is put into the register by executing the command set <name> startdischarge. To obtain the proper remaining battery capacity in Ah, one must set XFunction to the value of (max. battery capacity (in Ah) - (255/2048-X)/resistor value).
• The time register is incremented by 1 each second, see commands below.

Define

define <name> OWMULTI [<model>] <id> [<interval>] or
define <name> OWMULTI <fam>.<id> [<interval>]

Define a 1-Wire smart battery monitor

• [<model>]
  Defines the model (and thus 1-Wire family id), currently the following values are permitted:
  • model DS2438 with family id 26 (default if the model parameter is omitted) or DS2438a with family id A6. For both, a temperature value T, an external voltage VAD (1.5V < VAD < 2 VDD), the supply voltage VDD and a sense voltage Vsens (-0.25V < Vsens < 0.25V) are measured. Calculated are running time in seconds and time integrated sense voltage Vsens.t.
• <fam>
  2-character unique family id, see above
• <id>
  12-character unique ROM id of the converter device without family id and CRC code
• <interval>
  Measurement interval in seconds. The default is 300 seconds, a value of 0 disables the automatic update.

Set

• set <name> calibrate
  Write the inverse value of the Vsense register into the offset register, see notes above
• set <name> offset [-1,-2,-1,0,1,2,3]
  Write this value into the offset register, see notes above
• set <name> inittime
  Write a zero into the time register, see notes above
• set <name> startdischarge
  Write the maximum value into the time integrated sense register, see notes above
• set <name> interval <int>
  Measurement interval in seconds. The default is 300 seconds, a value of 0 disables the automatic update.

Get

• get <name> id
  Returns the full 1-Wire device id OW_FAMILY.ROM_ID.CRC
• get <name> reading
  Obtain all measurement values.
• get <name> temperature
  Obtain the temperature value.
• get <name> VDD
  Obtain the actual supply voltage.
• get <name> raw
  Obtain the raw readings for VAD=V, Vsense=W and VSense.t=X.

Attributes

• attr <name> interval <int>
  measurement interval in seconds. The default is 300 seconds, a value of 0 disables the automatic update.
• attr <name> VName <string>[|<string>]
  name for the voltage channel [|short name used in state reading].
• attr <name> VUnit <string>
  unit of measurement for the voltage channel used in state reading (default "V", set to "none" for empty).
• attr <name> VFunction <string>
  arbitrary functional expression involving the values VDD, V and T:
  • VDD is replaced by the measured supply voltage in Volt,
  • V by the measured external voltage channel VAD,
  • T by the measured and corrected temperature in its unit
• attr <name> WName <string>[|<string>]
  name for the sense channel [|short name used in state reading]
• attr <name> WUnit <string>
  unit of measurement for the sense channel used in state reading (default "V", set to "none" for empty).
• attr <name> WFunction <string>
  linear functional expression involving the value W which is replaced by the measured external sense channel Vsense
• attr <name> XName <string>[|<string>]
  name for the time integrated sense channel [|short name used in state reading].
• attr <name> XUnit <string>
  unit of measurement for the time integrated sense channel used in state reading (default "Vs", set to "none" for empty).
• attr <name> XFunction <string>
  linear functional expression involving the value X which is replaced by the time integrated external sense channel Vsense.t
• attr <name> tempOffset <float>
  temperature offset in K added to the raw temperature reading.
• attr <name> tempUnit Celsius|Kelvin|Fahrenheit
  unit of measurement (temperature scale), default is Celsius = °C
• readingFnAttributes

OWSWITCH

[EN DE]

FHEM module to commmunicate with 1-Wire Programmable Switches

This 1-Wire module works with the OWX interface module or with the OWServer interface module (prerequisite: Add this module's name to the list of clients in OWServer). Please define an OWX device or OWServer device first.

Example

define OWX_S OWSWITCH DS2413 B5D502000000 60
attr OWX_S AName light-a|la
attr OWX_S AUnit AN|AUS

Define

define <name> OWSWITCH [<model>] <id> [<interval>] or
define <name> OWSWITCH <fam>.<id> [<interval>]

Define a 1-Wire switch.



• [<model>]
  Defines the switch model (and thus 1-Wire family id), currently the following values are permitted:
  • model DS2413 with family id 3A (default if the model parameter is omitted). 2 Channel switch with onboard memory
  • model DS2406 with family id 12. 2 Channel switch
  • model DS2408 with family id 29. 8 Channel switch
• <fam>
  2-character unique family id, see above
• <id>
  12-character unique ROM id of the device without family id and CRC code
• <interval>
  Measurement interval in seconds. The default is 300 seconds, a value of 0 disables the automatic update.

Set

• set <name> interval <int>
  Measurement interval in seconds. The default is 300 seconds, a value of 0 disables the automatic update.
• set <name> output <channel-name> on | off | on-for-timer <time> | off-for-timer <time>
  Set value for channel (A,B,... or defined channel name). 1 = off, 0 = on in normal usage. See also the note above.
  on-for-timer/off-for-timer will set the desired value only for the given time, either given as hh:mm:ss or as integers seconds and then will return to the opposite value.
• set <name> gpio <value>
  Set values for channels (For 2 channels: 3 = A and B off, 1 = B on 2 = A on 0 = both on)
• set <name> init yes
  Re-initialize the device

Get

• get <name> id
  Returns the full 1-Wire device id OW_FAMILY.ROM_ID.CRC
• get <name> input <channel-name>
  state for channel (A,B, ... or defined channel name) This value reflects the measured value, not necessarily the one set as output state, because the output transistors are open collector switches. A measured state of 1 = OFF therefore corresponds to an output state of 1 = OFF, but a measured state of 0 = ON can also be due to an external shortening of the output, it will be signaled by appending the value of the attribute stateS to the reading.
• get <name> gpio
  Obtain state of all channels

Attributes

• attr <name> interval <int>
  Measurement interval in seconds. The default is 300 seconds, a value of 0 disables the automatic update.
For each of the following attributes, the channel identification A,B,... may be used.
• <name> stateS <string>
  character string denoting external shortening condition (default is X, set to "none" for empty).
• attr <name> <channel>Name <string>[|<string>]
  name for the channel [|short name used in state reading]
• attr <name> <channel>Unit <string>|<string>
  display for on | off condition
• readingFnAttributes

OWServer

[EN DE]

Define
define <name> OWServer <protocol> [<version>]

Defines a logical OWServer device which connects to an owserver. owserver is the server component of the owfs 1-Wire Filesystem. It serves as abstraction layer for any 1-wire devices on a host. <protocol> has format <hostname>:<port>. For details see owserver documentation.

The OWServer device uses OWNet.pm from Sourceforge to connect to the owserver. Currently, OWNet modules for versions 2.8p17 and 3.1p5 are deployed with FHEM. You can manually add more versions by extracting OWNet.pm from one of the available versions and saving it as as FHEM/lib/OWNet-<version>.pm in the FHEM directory structure.

The first connection to the owserver is made using version 3.1p5 unless you explicitely suggest another version using the optional <version> parameter. You should suggest a OWNet module version matching your actual owserver version if FHEM hangs after connecting to the owserver.

The OWServer device autodetects the owserver version and chooses a matching OWNet module from the list of available OWNet modules. If no matching OWNet module is found, the initially suggested version is used. The nightmare situation of two OWServer devices connecting to owserver instances with different versions is not handled correctly. The server and module versions are stored in the internals of the OWServer device for your reference.

The ow* version 3.1p5 packages provided with Debian Stretch and the ow* version 2.8p17 packages provided with Debian Jessie are fine. The ow* version 2.9 packages provided with Debian Jessie in combination with OWNet.pm as deployed with FHEM might have issues (feedback welcome). For Debian Jessie you could unzip owfs_2.8p17-1_all.zip and install owserver, dependencies and what else you require with dpkg -i <package>.deb.

Please report issues and successes related to versions in the 1Wire board of the FHEM Forum.

A typical working configuration file /etc/owfs.conf looks as follows:

# server uses device /dev/onewire
server: device = /dev/onewire
# clients other than server use server
! server: server = localhost:4304
# port
server: port = 4304
# owhttpd
http: port = 2121
# owftpd
ftp: port = 2120


The actual 1-wire devices are defined as OWDevice devices. If autocreate is enabled, all the devices found are created at start of FHEM automatically.

This module is completely unrelated to the 1-wire modules with names all in uppercase.

Examples:

define myLocalOWServer OWServer localhost:4304
define myRemoteOWServer OWServer raspi:4304 2.8p17



Notice: if you get no devices add both localhost and the FQDN of your owserver as server directives to the owserver configuration file on the remote host.


Set
set <name> <value>

where value is one of


• reopen
  Reopens the connection to the owserver.
• owserver (OWFS) specific settings:
  • timeout/directory
  • timeout/ftp
  • timeout/ha7
  • timeout/network
  • timeout/presence
  • timeout/serial
  • timeout/server
  • timeout/stable
  • timeout/uncached
  • timeout/usb
  • timeout/volatile
  • timeout/w1
  • units/pressure_scale
  • units/temperature_scale
For further informations have look on owserver manual).



Get
get <name> <value>

where value is one of


• devices
  Lists the addresses and types of all 1-wire devices provided by the owserver. Also shows the corresponding OWDevice if one is defined for the respective 1-wire devices.
• errors
  List a view of error statistics.
• owserver (OWFS) specific settings:
  • /settings/timeout/directory
  • /settings/timeout/ftp
  • /settings/timeout/ha7
  • /settings/timeout/network
  • /settings/timeout/presence
  • /settings/timeout/serial
  • /settings/timeout/server
  • /settings/timeout/stable
  • /settings/timeout/uncached
  • /settings/timeout/usb
  • /settings/timeout/volatile
  • /settings/timeout/w1
  • /settings/units/pressure_scale
  • /settings/units/temperature_scale
  • /uncached/alarm
For further informations have look on owserver manual).



Attributes
• nonblocking
  Get all readings (OWServer / OWDevice) via a child process. This ensures, that FHEM is not blocked during communicating with the owserver.
  Example:
  attr <name> nonblocking 1
• eventMap
• readingFnAttributes


Note: unset nonblocking if you experience lockups of FHEM.

OWTHERM

[EN DE]

FHEM module to commmunicate with 1-Wire bus digital thermometer devices

This 1-Wire module works with the OWX interface module or with the OWServer interface module (prerequisite: Add this module's name to the list of clients in OWServer). Please define an OWX device or OWServer device first.

Example

define OWX_T OWTHERM DS18B20 E8D09B030000 300
attr OWX_T tempUnit Kelvin

Define

define <name> OWTHERM [<model>] <id> [<interval>] or
define <name> OWTHERM <fam>.<id> [<interval>]

Define a 1-Wire digital thermometer device.

• [<model>]
  Defines the thermometer model (and thus 1-Wire family id) currently the following values are permitted:
  • model DS1820 with family id 10 (default if the model parameter is omitted)
  • model DS1822 with family id 22
  • model DS18B20 with family id 28
• <fam>
  2-character unique family id, see above
• <id>
  12-character unique ROM id of the thermometer device without family id and CRC code
• <interval>
  Temperature measurement interval in seconds. The default is 300 seconds.

Set

• set <name> interval <int>
  Temperature readout interval in seconds. The default is 300 seconds, a value of 0 disables the automatic update. Attention:This is the readout interval. Whether an actual temperature measurement is performed, is determined by the tempConv attribute
• set <name> tempHigh <float>
  The high alarm temperature (on the temperature scale chosen by the attribute value)
• set <name> tempLow <float>
  The low alarm temperature (on the temperature scale chosen by the attribute value)

Get

• get <name> id
  Returns the full 1-Wire device id OW_FAMILY.ROM_ID.CRC
• get <name> temperature
  Obtain the temperature.
• get <name> alarm
  Obtain the alarm temperature values.

Attributes

• attr <name> stateAL <string>
  character string for denoting low alarm condition, default is ↓
• attr <name> stateAH <string>
  character string for denoting high alarm condition, default is ↑
• attr <name> tempConv onkick|onread
  determines, whether a temperature measurement will happen when "kicked" through the OWX backend module (all temperature sensors at the same time), or on reading the sensor (1 second waiting time, default).
• attr <name> tempOffset <float>
  temperature offset in °C added to the raw temperature reading.
• attr <name> tempUnit none|Celsius|Kelvin|Fahrenheit
  unit of measurement (temperature scale) for state reading (default is Celsius = °C, use "none" for empty).
• attr <name> resolution 9|10|11|12
  Temperature resolution in bit, only relevant for DS18B20
• attr <name> interval <int>
  Temperature readout interval in seconds. The default is 300 seconds. Attention:This is the readout interval. Whether an actual temperature measurement is performed, is determined by the tempConv attribute
• attr <name> tempHigh <float>
  high alarm temperature (on the temperature scale chosen by the attribute value).
• attr <name> tempLow <float>
  low alarm temperature (on the temperature scale chosen by the attribute value).
• readingFnAttributes

OWVAR

[EN DE]

FHEM module to commmunicate with 1-Wire bus digital potentiometer devices of type DS2890

This 1-Wire module works with the OWX interface module, but not yet with the OWServer interface module.

Example

define OWX_P OWVAR E8D09B030000
attr OWX_P Function 1.02 * V + 0.58 | (U-0.58) / 1.02





Define

define <name> OWVAR <id> or
define <name> OWVAR <fam>.<id>

Define a 1-Wire digital potentiometer device.

• <fam>
  2-character unique family id, must be 2C
• <id>
  12-character unique ROM id of the thermometer device without family id and CRC code

Set

• set <name> value <float>
  The value of the potentiometer resistance against ground. Arguments may be in the range of [0,100] without a Function attribute, or in the range needed for a Function



Get

• get <name> id
  Returns the full 1-Wire device id OW_FAMILY.ROM_ID.CRC



Attributes

• attr <name> Name <string>[|<string>]
  name for the reading [|name used in state reading].
• attr <name> Unit <string>[|<string>]
  unit of measurement used in state reading.
• attr <name> Function <string>|<string>
  The first string is an arbitrary functional expression u(V) involving the variable V. V is replaced by the raw potentiometer reading (in the range of [0,100]). The second string must be the inverse function v(U) involving the variable U, such that U can be replaced by the value given in the Set argument. Care has to taken that v(U) is in the range [0,100]. No check on the validity of these functions is performed, singularities may crash FHEM. Example see above.
• readingFnAttributes

OWX

[EN DE]

Backend module to commmunicate with 1-Wire bus devices

• via an active DS2480/DS9097U bus master interface attached to an USB port or
• via an active DS2480 bus master interface attached to a TCP/IP-UART interface
• via a network-attached CUNO or through a COC on the RaspBerry Pi
• via an Arduino running OneWireFirmata
Internally these interfaces are vastly different, read the corresponding Wiki pages . The passive DS9097 interface is no longer suppoorted.

Define

To define a 1-Wire interface to communicate with a 1-Wire bus, several possibilities exist:

• define <name> OWX <serial-device>, i.e. specify the serial device (e.g. USB port) to which the 1-Wire bus is attached, for example
  define OWio1 OWX /dev/ttyUSB1
• define <name> OWX <tcpip>[:<port>], i.e. specify the IP address and port to which the 1-Wire bus is attached. Attention: no socat program needed. Example:
  define OWio1 OWX 192.168.0.1:23
• define <name> OWX <cuno/coc-device>, i.e. specify the previously defined COC/CUNO to which the 1-Wire bus is attached, for example
  define OWio2 OWX COC
• define <name> OWX <firmata-device>:<firmata-pin>, i.e. specify the name and 1-Wire pin of the previously defined FRM device to which the 1-Wire bus is attached, for example
  define OWio3 OWX FIRMATA:10

Set

• set <name> reopen
  re-opens the interface and re-initializes the 1-Wire bus.



Get

• get <name> alarms
  performs an "alarm search" for devices on the 1-Wire bus and, if found, generates an event in the log (not with all interface types).
• get <name> devices
  redicovers all devices on the 1-Wire bus. If a device found has a previous definition, this is automatically used. If a device is found but has no definition, it is autocreated. If a defined device is not on the 1-Wire bus, it is autodeleted.
• get <name> version
  internal version number



Attributes

• attr <name> asynchronous 0(default)|1
  if 1 the interface will run asynchronously;if 0 (default) then not
• attr <name> timeout <number>
  time in seconds waiting for response of any 1-Wire device, or 1-Wire interface,default 5 s
• attr <name> opendelay <number>
  time in seconds waiting until a reopen ist attempted, default 60 s
• attr <name> dokick 0|1
  if 1, the interface regularly kicks thermometers on the bus to do a temperature conversion, and to make an alarm check; if 0 (default) then not
• attr <name> interval <number>
  time interval in seconds for kicking temperature sensors and checking for alarms, default 300 s
• readingFnAttributes

OWX_ASYNC

[EN DE]

FHEM module to commmunicate with 1-Wire bus devices

• via an active DS2480 bus master interface attached to an USB port or
• via an Arduino running ConfigurableFirmata attached to USB
• via an Arduino running ConfigurableFirmata connecting to FHEM via Ethernet

Internally these interfaces are vastly different, read the corresponding Wiki pages

OWX_ASYNC does pretty much the same job as OWX does, but using an asynchronous mode of communication

Example

define OWio1 OWX_ASYNC /dev/ttyUSB1
define OWio3 OWX_ASYNC 10

Define

define <name> OWX_ASYNC <serial-device> or
define <name> OWX_ASYNC <cuno/coc-device> or
define <name> OWX_ASYNC <arduino-pin>

Define a 1-Wire interface to communicate with a 1-Wire bus.

• <serial-device> The serial device (e.g. USB port) to which the 1-Wire bus is attached.
• <cuno-device> The previously defined CUNO to which the 1-Wire bus is attached.
• <arduino-pin> The pin of the previous defined FRM to which the 1-Wire bus is attached. If there is more than one FRM device defined use IODev attribute to select which FRM device to use.

Set

• set <name> interval <value>
  sets the time period in seconds for "kicking" the 1-Wire bus when the dokick attribute is set (default is 300 seconds).
• set <name> followAlarms on|off
  
  instructs the module to start an alarm search in case a reset pulse discovers any 1-Wire device which has the alarm flag set.

Get

• get <name> alarms
  
  performs an "alarm search" for devices on the 1-Wire bus and, if found, generates an event in the log (not with CUNO).
• get <name> devices
  
  redicovers all devices on the 1-Wire bus. If a device found has a previous definition, this is automatically used. If a device is found but has no definition, it is autocreated. If a defined device is not on the 1-Wire bus, it is autodeleted.

Attributes

• attr <name> dokick 0|1
  1 if the interface regularly kicks thermometers on the bus to do a temperature conversion, and to perform an alarm check, 0 if not
• attr <name> buspower real|parasitic
  parasitic if there are any devices on the bus that steal power from the data line.
  Ensures that never more than a single device on the bus is talked to (throughput is throttled noticable!)
  Automatically disables attribute 'dokick'.
• attr <name> IODev <FRM-device>
  assignes a specific FRM-device to OWX_ASYNC when working through an Arduino.
  Required only if there is more than one FRM defined.
• attr <name> maxtimeouts <number>
  maximum number of timeouts (in a row) before OWX_ASYNC disconnects itself from the busmaster and tries to establish a new connection
• Standard attributes alias, comment, event-on-update-reading, event-on-change-reading, room, eventMap, webCmd

OWX_CCC

[EN DE]

See OWX

OWX_FRM

[EN DE]

See OWX

OWX_SER

[EN DE]

See OWX

OWX_TCP

[EN DE]

See OWX

OctoPrint

[EN DE]

OilFox

Requirements


• This module allows the communication between the Oilfox Cloud and FHEM.

Define
define <name> OilFox

Example:

define myOilFox OilFox
attr myOilFox email YOUR_EMAIL
attr myOilFox password YOUR_PASSWORD



You must set both attributes email and password. These are the same that you use to login via the OilFox App.

Attributes
• email - Email that is used in OilFox App
• password - Password that is used in OilFox App

Optional attributes
• oilfox - ID of OilFox, if more that one is registered. Default: 0
• timeout - Connection timeout
• interval - Time in seconds that is used to get new data from OilFox Cloud. Default: 300

Readings
• access_token_expires - date when session of OilFox Cloud expires
• oilfox_hwid - Id of the OilFox
• oilfox_name - Name of the OilFox
• oilfox_daysReach - Estimated days until the storage runs empty
• oilfox_tankVolume - Tank Volume in liters
• oilfox_metering_battery - enum of the battery level
• FULL - Full battery level
• GOOD - Good battery level
• MEDIUM - Medium battery level
• WARNING - Low battery level
• CRITICAL - Critical battery level
• oilfox_metering_value - Tank Value
• oilfox_metering_fillingPercentage - Tank filling Percentage
• oilfox_metering_liters - Tank filling liters
• oilfox_metering_currentOilHeight - Tank current Oil Height
• oilfox_currentMeteringAt - Timestamp of measurement
• oilfox_nextMeteringAt - Timestamp of next measurement
• validationError - enum with errors regarding the measurement
• NO_METERING - No measurement yet
• EMPTY_METERING - Incorrect Measurement
• NO_EXTRACTED_VALUE - No fill level detected
• SENSOR_CONFIG - Faulty measurement
• MISSING_STORAGE_CONFIG - Storage configuration missing
• INVALID_STORAGE_CONFIG - Incorrect storage configuration
• DISTANCE_TOO_SHORT - Measured distance too small
• ABOVE_STORAGE_MAX - Storage full
• BELOW_STORAGE_MIN - Calculated filling level implausible

PCA301

[EN DE]

The PCA301 is a RF controlled AC mains plug with integrated power meter functionality from ELV.

It can be integrated in to FHEM via a JeeLink as the IODevice.

The JeeNode sketch required for this module can be found in .../contrib/arduino/36_PCA301-pcaSerial.zip.

Define
define <name> PCA301 <addr> <channel>

addr is a 6 digit hex number to identify the PCA301 device. channel is a 2 digit hex number to identify the PCA301 device.

Note: devices are autocreated on reception of the first message.


Set
• on
• off
• identify
  Blink the status led for ~5 seconds.
• reset
  Reset consumption counters
• statusRequest
  Request device status update.
• set extensions are supported.

Get

Readings
• power
• consumption
• consumptionTotal
  will be created as a default user reading to have a continous consumption value that is not influenced by the regualar reset or overflow of the normal consumption reading

Attributes
• forceOn
  try to switch on the device whenever an off status is received.
• offLevel
  a power level less or equal offLevel is considered to be off. used only in conjunction with readonly.
• readonly
  if set to a value != 0 all switching commands (on, off, toggle, ...) will be disabled.
• ignore
  1 -> ignore this device.

PET

[EN DE]

Define
define <rp_PetName> PET [<device name(s) of resident group(s)>]

Provides a special virtual device to represent a pet in your home.
Based on the current state and other readings, you may trigger other actions within FHEM.

Used by superior module RESIDENTS but may also be used stand-alone.

Use comma separated list of resident device names for multi-membership (see example below).

Example:

# Standalone
define rp_Pet PET

# Typical group member
define rp_Pet PET rgr_Residents # to be member of resident group rgr_Residents

# Member of multiple groups
define rp_Pet PET rgr_Residents,rgr_Pets # to be member of resident group rgr_Residents and rgr_Pets
Für gewöhnlich sind das keine Fische oder Kleintiere in Käfigen
Note: A pet that is generally "worth" to be represented as a device in FHEM is an animal that usually leaves and re-enters home on a regular basis and that might stay alone at home from time to time. It is supposed to be an animal that you want your home to behave differently based on the pets presence or home status. Usually that is not a fish or small animals in cages, but something more like a dog in particular. Cats might not be worth to be tracked either, depending on their character and your daily family life.


Set
set <rp_PetName> <command> [<parameter>]

Currently, the following commands are defined.

• location   -   sets reading 'location'; see attribute rp_locations to adjust list shown in FHEMWEB
• mood   -   sets reading 'mood'; see attribute rp_moods to adjust list shown in FHEMWEB
• state   home,gotosleep,asleep,awoken,absent,gone   switch between states; see attribute rp_states to adjust list shown in FHEMWEB
• create
• locationMap   add a pre-configured weblink device using showing a Google Map if readings locationLat+locationLong are present.
• wakeuptimer   add several pre-configurations provided by RESIDENTS Toolkit. See separate section in RESIDENTS module commandref for details.
Note: If you would like to restrict access to admin set-commands (-> create) you may set your FHEMWEB instance's attribute allowedCommands like 'set,set-user'. The string 'set-user' will ensure only non-admin set-commands can be executed when accessing FHEM using this FHEMWEB instance.



Possible states and their meaning


This module differs between 6 states:


• home - individual is present at home and awake
• gotosleep - individual is on it's way to bed
• asleep - individual is currently sleeping
• awoken - individual just woke up from sleep
• absent - individual is not present at home but will be back shortly
• gone - individual is away from home for longer period



Presence correlation to location


Under specific circumstances, changing state will automatically change reading 'location' as well.

Whenever presence state changes from 'absent' to 'present', the location is set to 'home'. If attribute rp_locationHome was defined, first location from it will be used as home location.

Whenever presence state changes from 'present' to 'absent', the location is set to 'underway'. If attribute rp_locationUnderway was defined, first location from it will be used as underway location.



Auto Gone


Whenever an individual is set to 'absent', a trigger is started to automatically change state to 'gone' after a specific timeframe.
Default value is 16 hours.

This behaviour can be customized by attribute rp_autoGoneAfter.



Synchronizing presence with other PET, GUEST or ROOMMATE devices


If you always leave or arrive at your house together with other roommates, guests or pets, you may enable a synchronization of your presence state for certain individuals.
By setting attribute rp_passPresenceTo, those individuals will follow your presence state changes to 'home', 'absent' or 'gone' as you do them with your own device.

Please note that individuals with current state 'gone' or 'none' (in case of guests) will not be touched.



Synchronizing state with other PET, GUEST or ROOMMATE devices


To sync each and every status change that is _not_ related to leaving or arriving at your house, you may set attribute rp_passStateTo.

Please note that individuals with current state 'gone' or 'none' (in case of guests) will not be touched.



Location correlation to state


Under specific circumstances, changing location will have an effect on the actual state as well.

Whenever location is set to 'home', the state is set to 'home' if prior presence state was 'absent'. If attribute rp_locationHome was defined, all of those locations will trigger state change to 'home' as well.

Whenever location is set to 'underway', the state is set to 'absent' if prior presence state was 'present'. If attribute rp_locationUnderway was defined, all of those locations will trigger state change to 'absent' as well. Those locations won't appear in reading 'lastLocation'.

Whenever location is set to 'wayhome', the reading 'wayhome' is set to '1' if current presence state is 'absent'. If attribute rp_locationWayhome was defined, LEAVING one of those locations will set reading 'wayhome' to '1' as well. So you actually have implicit and explicit options to trigger wayhome.
Arriving at home will reset the value of 'wayhome' to '0'.

If you are using the GEOFANCY module, you can easily have your location updated with GEOFANCY events by defining a simple NOTIFY-trigger like this:

define n_rp_Pet.location notify geofancy:currLoc_Pet.* set rp_Pet:FILTER=location!=$EVTPART1 location $EVTPART1

By defining geofencing zones called 'home' and 'wayhome' in the iOS app, you automatically get all the features of automatic state changes described above.


Attributes

• rp_autoGoneAfter - hours after which state should be auto-set to 'gone' when current state is 'absent'; defaults to 16 hours
• rp_geofenceUUIDs - comma separated list of device UUIDs updating their location via GEOFANCY. Avoids necessity for additional notify/DOIF/watchdog devices and can make GEOFANCY attribute devAlias obsolete. (using more than one UUID/device might not be a good idea as location my leap)
• rp_lang - overwrite global language setting; helps to set device attributes to translate FHEMWEB display text
• rp_locationHome - locations matching these will be treated as being at home; first entry reflects default value to be used with state correlation; separate entries by space; defaults to 'home'
• rp_locationUnderway - locations matching these will be treated as being underway; first entry reflects default value to be used with state correlation; separate entries by comma or space; defaults to "underway"
• rp_locationWayhome - leaving a location matching these will set reading wayhome to 1; separate entries by space; defaults to "wayhome"
• rp_locations - list of locations to be shown in FHEMWEB; separate entries by comma only and do NOT use spaces
• rp_moodDefault - the mood that should be set after arriving at home or changing state from awoken to home
• rp_moodSleepy - the mood that should be set if state was changed to gotosleep or awoken
• rp_moods - list of moods to be shown in FHEMWEB; separate entries by comma only and do NOT use spaces
• rp_noDuration - may be used to disable continuous, non-event driven duration timer calculation (see readings durTimer*)
• rp_passStateTo - synchronize home state with other PET, GUEST or ROOMMATE devices; separte devices by space
• rp_passPresenceTo - synchronize presence state with other PET, GUEST or ROOMMATE devices; separte devices by space
• rp_presenceDevices - take over presence state from any other FHEM device. Separate more than one device with comma meaning ALL of them need to be either present or absent to trigger update of this PET device. You may optionally add a reading name separated by :, otherwise reading name presence and state will be considered.
• rp_realname - whenever PET wants to use the realname it uses the value of attribute alias or group; defaults to group
• rp_showAllStates - states 'asleep' and 'awoken' are hidden by default to allow simple gotosleep process via devStateIcon; defaults to 0
• rp_states - list of states to be shown in FHEMWEB; separate entries by comma only and do NOT use spaces; unsupported states will lead to errors though
• rp_wakeupDevice - reference to enslaved DUMMY devices used as a wake-up timer (part of RESIDENTS Toolkit's wakeuptimer)
• subType - specifies a specific class of a pet for the device. This will be considered for home alone status calculation. Defaults to "generic"



Generated Readings/Events:

• durTimerAbsence - timer to show the duration of absence from home in human readable format (hours:minutes:seconds)
• durTimerAbsence_cr - timer to show the duration of absence from home in computer readable format (minutes)
• durTimerPresence - timer to show the duration of presence at home in human readable format (hours:minutes:seconds)
• durTimerPresence_cr - timer to show the duration of presence at home in computer readable format (minutes)
• durTimerSleep - timer to show the duration of sleep in human readable format (hours:minutes:seconds)
• durTimerSleep_cr - timer to show the duration of sleep in computer readable format (minutes)
• lastArrival - timestamp of last arrival at home
• lastAwake - timestamp of last sleep cycle end
• lastDeparture - timestamp of last departure from home
• lastDurAbsence - duration of last absence from home in human readable format (hours:minutes:seconds)
• lastDurAbsence_cr - duration of last absence from home in computer readable format (minutes)
• lastDurPresence - duration of last presence at home in human readable format (hours:minutes:seconds)
• lastDurPresence_cr - duration of last presence at home in computer readable format (minutes)
• lastDurSleep - duration of last sleep in human readable format (hours:minutes:seconds)
• lastDurSleep_cr - duration of last sleep in computer readable format (minutes)
• lastLocation - the prior location
• lastMood - the prior mood
• lastSleep - timestamp of last sleep cycle begin
• lastState - the prior state
• lastWakeup - time of last wake-up timer run
• lastWakeupDev - device name of last wake-up timer
• location - the current location
• mood - the current mood
• nextWakeup - time of next wake-up program run
• nextWakeupDev - device name for next wake-up program run
• presence - reflects the home presence state, depending on value of reading 'state' (can be 'present' or 'absent')
• state - reflects the current state
• wakeup - becomes '1' while a wake-up program of this resident is being executed
• wayhome - depending on current location, it can become '1' if individual is on his/her way back home

PHC

[EN DE]

PHC provides a way to communicate with the PHC bus from Peha. It listens to the communication on the PHC bus, tracks the state of output modules in readings and can send events to the bus / "Steuermodul" by simulating PHC input modules.
It can import the channel list file that is exportable from the Peha "Systemsoftware" to get names of existing modules and channels.
This module can not replace a Peha "Steuermodul". It is also not possible to directly send commands to output modules on the PHC bus. If you want to interact with output modules then you have to define the action on the Peha "Steuermodul" and send the input event to it through a virtual input module.
If you define a virtual input module then it needs to be given a unique address in the allowed range for input modules and this address must not be used by existing input modules.

Prerequisites


• This module requires the Perl modules Device::SerialPort or Win32::SerialPort and Digest::CRC.
  To connect to the PHC bus it requires an RS485 adapter that connects directly to the PHC bus with GND, +data and -data.

Define
define <name> PHC <Device>
The module connects to the PHC bus with the specified device (RS485 adapter)

Examples:


define MyPHC PHC /dev/ttyRS485



Configuration of the module


The module doesn't need configuration to listen to the bus and create readings.
Only if you want to send input to the bus, you need to define a virtual input module with an address that is not used by real modules.
Virtual input modules and their channels are defined using attributes.
Example:


        attr MyPHC virtEMD25C2Name VirtLightSwitch
        

Defines a virtual light switch as channel 2 on the virtual input nodule with address 25. This light switch can then be used with set comands like

        set MyPHC VirtualLightSwitch ein>0
        

The set options offered here are the event types that PHC knows for input modules. They are ein>0, ein>1, ein>2, aus, aus<1. To react on such events in the PHC system you need to add a reaction to the programming of your PHC control module.

Set-Commands

• importChannelList
reads an xml file that is exportable by the Peha "Systemsoftware" that contains addresses and names of existing modules and channels on the PHC bus.
The path to the filename to import is relative to the Fhem base directory.
Example:


            set MyPHC importChannelList Kanalliste.xml
            

If Kanalliste.xml is located in /opt/fhem.


more set options are created based on the attributes defining virtual input modules / channels
Every input channel for which an attribute like virtEMDxyCcName is defined will create a valid set option with name specified in the attribute.


Get-Commands

none so far

Attributes


• do_not_notify
• readingFnAttributes
• BusEvents
  this attribute controls what kind of events are generated when messages are received from the PHC bus regardless of any readings that might be created. If set to simple (which is the default) then short events like EMD12i01: Ein > 0 will be generated. If set to long then instead of EMD12i01 the module will use a name specified with a channel description attribue (see above). If set to none then no events will be created except the ones that result from readings that are created when output modules send their channel state.
• HTTPMOD
  Name of an HTTPMOD-device which is defined as http://your-stm-ip:6680/ 0
• STM_ADR
  Address of the control module (typically 0) to be used in the XMLRPC communication to directly set an output (STM Version 3 with ethernet connection only)
• EMDReadings
  if this attribute is set to 1 then the module will create readings for each input channel. These readings will contain the last command received from an input, e.g. ein>0
  These readings will not create events because by default any input message on the bus will create an event anyway (see BusEvents).
• sendEcho
  controls if bus commands sent should be fed back to the read function.
• virtEMD[0-9]+C[0-9]+Name Defines a virtual input module with a given address and a name for a channel of that input module.
  For example:
  

              attr MyPHC virtEMD25C1Name LivingRoomLightSwitch
              attr MyPHC virtEMD25C2Name KitchenLightSwitch
              

• module[0-9]+description
  this attribute is typically created when you import a channel list with set MyPHCDevice importChannelList.
  It gives a name to a module. This name is used for better readability when logging at verbose level 4 or 5.
• module[0-9]+type
  this attribute is typically created when you import a channel list with set MyPHCDevice importChannelList.
  It defines the type of a module. This information is needed since some module types (e.g. EMD and JRM) use the same address space but a different protocol interpretation so parsing is only correct if the module type is known.
• channel(EMD|AMD|JRM|DIM|UIM|MCC|MFN)[0-9]+[io]?[0-9]+description
  this attribute is typically created when you import a channel list with set MyPHCDevice importChannelList.
  It defines names for channels of modules. These names are used for better readability when logging at verbose level 4 or 5. They also define the names of readings that are automatically created when the module listens to the PHC bus.
• channel(EMD|AMD|JRM|DIM|UIM|MCC|MFN)[0-9]+[io]?[0-9]+set
  Only for STM version 3! This allows sending commands to output modules (so far tested with AMD, JRM or DIM) through the XML-RPC interface of a version 3 STM. To work this feature needs an HTTPMOD device which is defined as http://your-stm-ip:6680/ 0
  The name of this HTTPMOD device then needs to be linked here via an attr named HTTPMOD.
• silentReconnect
  this attribute controls at what loglevel reconnect messages from devIO will be logged. Without this attribute they will be logged at level 3. If this attribute is set to 1 then such messages will be logged at level 4.

PHILIPS_AUDIO

[EN DE]

Define


define <name> PHILIPS_AUDIO <device model> <ip-address> [<status_interval>]

define <name> PHILIPS_AUDIO <device model> [<off_status_interval>] [<on_status_interval>]

This module controls a Philips Audio Player e.g. MCi, Streamium or Fidelio and potentially any other device controlled by the "myRemote" app.
You might also check, opening the following URL in the browser: http://[ip number of your device]:8889/index

(Tested on: AW9000, NP3500, NP3700 and NP3900)

Example:


define player PHILIPS_AUDIO NP3900 192.168.0.15

# With custom status interval of 60 seconds
define PHAUDIO_player PHILIPS_AUDIO NP3900 192.168.0.15 60

# With custom "off"-interval of 60 seconds and "on"-interval of 10 seconds
define PHAUDIO_player PHILIPS_AUDIO NP3900 192.168.0.15 60 10

Note: Due to slow command processing by the player itself the minimum interval is limited to 5 seconds. More frequent polling might cause device freezes.

Set
set <name> <command> [<parameter>]

Note: Commands and parameters are case sensitive.



• favoriteAdd – Adds currently played Internet Radio stream to favorites
• favoriteRemove – Removes currently played Internet Radio stream from favorites
• getFavorites – Reads stored favorites from the device (may take some time...)
• getMediaRendererDesc – Reads device specific information (stored in the deviceInfo reading)
• getPresets – Reads stored presets from the device (may take some time...)
• input – Selects the following input
• analogAux – Selects the analog AUX input (AW9000 only)
• digital1Coaxial – Selects the digital coaxial input (AW9000 only)
• digital2Optical – Selects the digital optical input (AW9000 only)
• internetRadio – Selects the Internet Radio input
• mediaLibrary – Selects the Media Library input (UPnP/DLNA server) (not available on AW9000)
• mp3Link – Selects the analog MP3 Link input (not available on AW9000)
• onlineServices – Selects the Online Services input
• mute [ on | off ] – Mutes/unmutes the device
• player – Player related commands
• next – Selects next audio stream
• prev – Selects previous audio stream
• play-pause – Plays/pauses the current audio stream
• stop – Stops the current audio stream
• repeat [ single | all | off] – Selects the repeate mode
• selectFavorite [ name ] – Selects a favorite. Empty if no favorites found. (see also getFavorites)
• selectFavoriteByNumber [ number ] – Selects a favorite by its number. Empty if no favorites found. (see also getFavorites)
• selectPreset [ name ] – Selects a preset. Empty if no presets found. (see also getPresets)
• selectPresetByNumber [ number ] – Selects a preset by its number. Empty if no presets found. (see also getPresets)
• selectStream [ name ] – Context-sensitive. Selects a stream depending on the current input and player list content. A 'c'-prefix represents a 'container' (directory). An 'i'-prefix represents an 'item' (audio stream).
• shuffle [ on | off ] – Sets the shuffle mode
• standbyButton – Emulates the standby button. Toggles between standby and power on
• volume – Sets the relative volume 0...100%
• volumeDown – Sets the device specific volume by one decrement
• volumeStraight – Sets the device specific absolute volume 0...64
• volumeUp – Sets the device specific volume by one increment

Get
get <name> <reading> <reading name>


• deviceInfo – Returns device specific information
• reading
• input – Returns current input or '-' if not playing
• listItem_xxx – Returns player list item (limited to 999 entries)
• networkError – Shows an occured current network error
• networkRequest – Shows current network activity (idle/busy)
• power – Returns power status (on/off)
• playerAlbum – Returns the album name of played stream
• playerAlbumArt – Returns the album art of played audio stream
• playerListStatus – Returns current player list status (busy/ready)
• playerListTotalCount – Returns number of player list entries
• playerPlayTime – Returns audio stream duration
• playerPlaying – Returns current player playing state (yes/no)
• playerRadioStation – Returns the name of played radio station
• playerRadioStationInfo – Returns additional info of the played radio station
• playerRepeat – Returns current repeat mode (off/single/all)
• playerShuffle – Returns current shuffle mode (on/off)
• playerState – Returns current player state (home/browsing/playing)
• playerStreamFavorite – Shows if audio stream is a favorite (yes/no)
• playerStreamRating – Shows rating of the audio stream
• playerTitle – Returns audio stream's title
• playerTotalTime – Shows audio stream's total time
• presence – Returns peresence status (present/absent)
• state – Returns current state (on/off)
• totalFavorites – Returns total number of stored favorites (see getFavorites)
• totalPresets – Returns total number of stored presets (see getPresets)
• volume – Returns current relative volume (0...100%)
• volumeStraight – Returns current device absolute volume (0...64)


Attributes


• autoGetFavorites – Automatically read favorites from device if none available (default off)
• autoGetPresets – Automatically read presets from device if none available (default off)
• do_not_notify
• httpBufferTimeout – Optional attribute defing the internal http buffer timeount (default 10)
• maxListItems – Defines max. number of player list items (default 100)
• playerBrowsingTimeout – Defines the inactivity timeout for browsing. After that timeout the player returns to the state 'home' in which the readings are updated automaically again. (default 180 seconds)
• readingFnAttributes
• requestTimeout – Optional attribute defining the http response timeout (default 4 seconds)

PHTV

[EN DE]

Define
define <name> PHTV <ip-address-or-hostname> [<poll-interval>]

This module controls Philips TV devices and their Ambilight via network connection.

Defining a PHTV device will schedule an internal task (interval can be set with optional parameter <poll-interval> in seconds, if not set, the value is 45 seconds), which periodically reads the status of the device and triggers notify/filelog commands.

Example:

define PhilipsTV PHTV 192.168.0.10

# With custom interval of 20 seconds
define PhilipsTV PHTV 192.168.0.10 20


Note: Some older devices might need to have the API activated first. If you get no response from your device, try to input "5646877223" on the remote while watching TV (which spells jointspace on the digits). A popup might appear stating the API was successfully enabled.


Set
set <name> <command> [<parameter>]

Currently, the following commands are defined.

• on   -   powers on the device and send a WoL magic package if needed
• off   -   turns the device in standby mode
• toggle   -   switch between on and off
• channel channel,0...999,sRef   -   zap to specific channel or service reference
• channelUp   -   zap to next channel
• channelDown   -   zap to previous channel
• volume 0...100   -   set the volume level in percentage
• volumeStraight 1...60   -   set the volume level in device specific range
• volumeUp   -   increases the volume level
• volumeDown   -   decreases the volume level
• mute on,off,toggle   -   controls volume mute
• input ...   -   switches between inputs
• statusRequest   -   requests the current status of the device
• remoteControl UP,DOWN,...   -   sends remote control commands; see remoteControl help
• ambiHue on,off   -   activates/disables Ambilight+Hue function
• ambiMode internal,manual,expert   -   set source register for Ambilight
• ambiPreset   -   set Ambilight to predefined state
• rgb HEX,LED address   -   set an RGB value for Ambilight
• hue 0-65534   -   set the color hue value Ambilight
• sat 0-255   -   set the saturation value for Ambilight
• bri 0-255   -   set the brightness value for Ambilight
• play   -   starts/resumes playback
• pause   -   starts/resumes playback
• stop   -   stops current playback
• record   -   starts recording of current channel
Note: If you would like to restrict access to admin set-commands (-> statusRequest) you may set your FHEMWEB instance's attribute allowedCommands like 'set,set-user'. The string 'set-user' will ensure only non-admin set-commands can be executed when accessing FHEM using this FHEMWEB instance.



Advanced Ambilight Control


If you would like to specificly control color for individual sides or even individual LEDs, you may use special addressing to be used with set command 'rgb':


LED addressing format:
<Layer><Side><LED number>

Examples:

# set LED 0 on left side within layer 1 to color RED
set PhilipsTV rgb L1L0:FF0000

# set LED 0, 2 and 4 on left side within layer 1 to color RED
set PhilipsTV rgb L1L0:FF0000 L1L2:FF0000 L1L4:FF0000

# set complete right side within layer 1 to color GREEN
set PhilipsTV rgb L1R:00FF00

# set complete layer 1 to color BLUE set PhilipsTV rgb L1:0000FF







Advanced Ambilight+HUE Control


Linking to your HUE devices within attributes ambiHueLeft, ambiHueTop, ambiHueRight and ambiHueBottom uses some defaults to calculate the actual color.
More than one HUE device may be added using blank.
The following settings can be fine tuned for each HUE device:


• LED(s) to be used as color source
  either 1 single LED or a few in a raw like 2-4. Defaults to use the middle LED and it's left and right partners. Counter starts at 1. See readings ambiLED* for how many LED's your TV has.
• saturation in percent of the original value (1-99, default=100)
• brightness in percent of the original value (1-99, default=100)


Use the following addressing format for fine tuning:
devicename:<LEDs$gt;:<saturation$gt;:<brightness$gt;

Examples:

# to push color from top to 2 HUE devices
attr PhilipsTV ambiHueTop HUEDevice0 HUEDevice1

# to use only LED 4 from the top as source
attr PhilipsTV ambiHueTop HUEDevice0:4

# to use a combination of LED's 1+2 as source
attr PhilipsTV ambiHueTop HUEDevice0:1-2

# to use LED's 1+2 and only 90% of their saturation
attr PhilipsTV ambiHueTop HUEDevice0:1-2:90

# to use LED's 1+2 and only 50% of their brightness
attr PhilipsTV ambiHueTop HUEDevice0:1-2::50

# to use LED's 1+2, 90% saturation and 50% brightness
attr PhilipsTV ambiHueTop HUEDevice0:1-2:90:50

# to use default LED settings but only adjust their brightness to 50%
attr PhilipsTV ambiHueTop HUEDevice0:::50




Get
get <name> <what>

Currently, the following commands are defined:


channel
mute
power
input
volume
rgb



Attributes

• ambiHueLeft - HUE devices that should get the color from left Ambilight.
• ambiHueTop - HUE devices that should get the color from top Ambilight.
• ambiHueRight - HUE devices that should get the color from right Ambilight.
• ambiHueBottom - HUE devices that should get the color from bottom Ambilight.
• ambiHueLatency - Controls the update interval for HUE devices in milliseconds; defaults to 200 ms.
• channelsMax - Maximum amount of channels shown in FHEMWEB. Defaults to 80.
• disable - Disable polling (true/false)
• drippyFactor - Adds some delay in seconds after low-performance devices came up to allow more time to become responsive (default=0)
• inputs - Presents the inputs read from device. Inputs can be renamed by adding ,NewName right after the original name.
• jsversion - JointSpace protocol version; e.g. pre2014 devices use 1, 2014 devices use 5 and >=2015 devices use 6. defaults to 1
• sequentialQuery - avoid parallel queries for low-performance devices
• timeout - Set different polling timeout in seconds (default=7)



Generated Readings/Events:

• ambiHue - Ambilight+Hue status
• ambiLEDBottom - Number of LEDs of bottom Ambilight
• ambiLEDLayers - Number of physical LED layers
• ambiLEDLeft - Number of LEDs of left Ambilight
• ambiLEDRight - Number of LEDs of right Ambilight
• ambiLEDTop - Number of LEDs of top Ambilight
• ambiMode - current Ambilight color source
• channel - Shows the service name of current channel; part of FHEM-4-AV-Devices compatibility
• country - Set country
• currentMedia - The preset number of this channel; part of FHEM-4-AV-Devices compatibility
• frequency - Shows current channels frequency
• input - Shows currently used input; part of FHEM-4-AV-Devices compatibility
• language - Set menu language
• model - Device model
• mute - Reports the mute status of the device (can be "on" or "off")
• onid - The ON ID
• power - Reports the power status of the device (can be "on" or "off")
• presence - Reports the presence status of the receiver (can be "absent" or "present"). In case of an absent device, control is basically limited to turn it on again. This will only work if the device supports Wake-On-LAN packages, otherwise command "on" will have no effect.
• receiveMode - Receiving mode (analog or DVB)
• rgb - Current Ambilight color if ambiMode is not set to internal and all LEDs have the same color
• rgb_X - Current Ambilight color of a specific LED if ambiMode is not set to internal
• serialnumber - Device serial number
• servicename - Name for current channel
• sid - The S-ID
• state - Reports current power state and an absence of the device (can be "on", "off" or "absent")
• systemname - Device system name
• tsid - The TS ID
• volume - Reports current volume level of the receiver in percentage values (between 0 and 100 %)
• volumeStraight - Reports current volume level of the receiver in device specific range

PID20

[EN DE]

Define

define <name> PID20 <sensor[:reading[:regexp]]> <actor:cmd >

This module provides a PID device, using <sensor> and <actor>



Set-Commands


set <name> desired <value>


Set desired value for PID


set <name> start


Start PID processing again, using frozen values from former stop.


set <name> stop


PID stops processing, freezing all values.


set <name> restart <value>


Same as start, but uses value as start value for actor




Get-Commands


get <name> params


Get list containing current parameters.




Attributes


• readingFnAttributes
• disable
• disabledForIntervals


• pidActorValueDecPlaces - number of demicals, possible values: 0..5; default: 0


• pidRoundReadings - round readings to number of demicals, possible values: 2..5; default: not rounded


• pidActorInterval - number of seconds to wait between to commands sent to actor; default: 180
• pidActorTreshold - threshold to be reached before command will be sent to actor; default: 1
• pidActorErrorAction - required action on error, possible values: freeze,errorPos; default: freeze
• pidActorErrorPos - actor's position to be used in case of error; default: 0
• pidActorKeepAlive - number of seconds to force command to be sent to actor; default: 1800
• pidActorLimitLower - lower limit for actor; default: 0
• pidActorLimitUpper - upper limit for actor; default: 100
• pidCalcInterval - interval (seconds) to calculate new pid values; default: 60
• pidDeltaTreshold - if delta < delta-threshold the pid will enter idle state; default: 0
• pidDesiredName - reading's name for desired value; default: desired
• pidFactor_P - P value for PID; default: 25
• pidFactor_I - I value for PID; default: 0.25
• pidFactor_D - D value for PID; default: 0
• pidMeasuredName - reading's name for measured value; default: measured
• pidSensorTimeout - number of seconds to wait before sensor will be recognized n/a; default: 3600
• pidReverseAction - reverse PID operation mode, possible values: 0,1; default: 0
• pidUpdateInterval - number of seconds to wait before an update will be forced for plotting; default: 300
• pidActorCallBeforeSetting - an optional callback-function,which can manipulate the actorValue; default: not defined

          # Exampe for callback-function
          # 1. argument = name of PID20
          # 2. argument = current actor value
            sub PIDActorSet($$)
            {
                my ( $name, $actValue ) = @_;
                if ($actValue>70)
                {
                  $actValue=100;
                }
                return $actValue;
            }

• pidIPortionCallBeforeSetting - an optional callback-function, which can manipulate the value of I-Portion; default: not defined

          # Exampe for callback-function
          # 1. argument = name of PID20
          # 2. argument = current i-portion value
            sub PIDIPortionSet($$)
            {
                my ( $name, $actValue ) = @_;
                if ($actValue>70)
                {
                  $actValue=70;
                }
                return $actValue;
            }

• pidActorMapCmd - add an optional hash for mapping actuation value to user-defined actor command.

  Example: attr <device> pidActorMapCmd {'1'=>'on-for-timer 90','0'=>'off','default'=>'off'}
  
  This will map an actuation value 0 to "off", resulting in "set <actor> off" being sent,
  an actuation value 1 will be mapped to "on-for-timer 90", resulting in "set <actor> on-for-timer 90" being sent,
  any other actuation value will be mapped to "off".
  
  You can use any dummy-command in define syntax, which will be ignored, if this attribut is set.
  



Generated Readings/Events:


• actuation - real actuation set to actor
• actuationCalc - internal actuation calculated without limits
• delta - current difference desired - measured
• desired - desired value
• measured - measured value
• p_p - p value of pid calculation
• p_i - i value of pid calculation
• p_d - d value of pid calculation
• state - current device state

Names for desired and measured readings can be changed by corresponding attributes (see above).



Additional information


• Discussion in FHEM forum


• Information in FHEM wiki

PIFACE

The PIFACE module managed the Raspberry Pi extension board PiFace Digital.
PIFACE controls the input ports 0..7 and output ports 0..7.
• The relays 0 and 1 have corresponding output port 0 and 1.
• The switches 0..3 have corresponding input ports 0..3 and must be read with attr portMode<0..7> = up
The status of the ports can be displayed periodically. The update of the states via interrupt is not supported.
The module can be periodically monitored by a watchdog function.
The ports can be read and controlled individually by the function readingsProxy.
PIFACE is tested with the Raspbian OS, Debian version 11 (bullseye) 32 bit and wiringpi_3.2-bullseye_armhf.
Raspberry 5 and Raspbian OS Bookworm may work but is not tested.

Preparatory Work
The use of PIFACE module requires some preparatory work. The module needs the Wiring Pi tool.

Raspberry Pi OS Bullseye
The current WiringPi software package can be found at https://github.com/WiringPi/WiringPi/. Please note the current version number for the download path and the file name.
.
• Install 64 bit version with
  wget https://github.com/WiringPi/WiringPi/releases/download/x.y/wiringpi-x.y-arm64.deb
dpkg -i wiringpi-x.y-arm64.deb
  
• Install 32 bit version with
  wget https://github.com/WiringPi/WiringPi/releases/download/x.y/wiringpi-x.y-armhf.deb
dpkg -i wiringpi-x.y-armhf.deb
  
• PiFace Digital need the SPI pins on the Raspberry Pi to be enabled in order to function. Start sudo raspi-config and set the SPI option to "Yes".
• The function of the PiFace Digital can be tested at OS command line. For example:
  gpio -x mcp23s17:200:0:0 readall
gpio -x mcp23s17:200:0:0 read 200
gpio -x mcp23s17:200:0:0 write 201 0 or gpio -x mcp23s17:200:0:0 write 201 1
  
• The watchdog function monitors the input port 7 and the output port 7.
  If the watchdog is enabled, this ports can not be used for other tasks. In order to monitor the input port 7, it must be connected to the ground!
  The OS command "shutdown" must be enable for fhem if an OS restart is to be executed in case of malfunction. For example, with chmod +s /sbin/shutdown or sudo chmod +s /sbin/shutdown.
  

Raspberry Pi OS Jessie / Stretch / Buster

• Install it with
  sudo apt-get install wiringpi
  
• PiFace Digital need the SPI pins on the Raspberry Pi to be enabled in order to function. Start sudo raspi-config and set the SPI option to "Yes".
• The function of the PiFace Digital can be tested at OS command line. For example:
  gpio -x mcp23s17:200:0:0 readall
gpio -x mcp23s17:200:0:0 read 200
gpio -x mcp23s17:200:0:0 write 201 0 or gpio -x mcp23s17:200:0:0 write 201 1
  
• The watchdog function monitors the input port 7 and the output port 7.
  If the watchdog is enabled, this ports can not be used for other tasks. In order to monitor the input port 7, it must be connected to the ground!
  The OS command "shutdown" must be enable for Fhem if an OS restart is to be executed in case of malfunction. For example, with the help of the shutdown ACLs (Access Control Lists). This allows you to privilege a maximum of 32 users to boot the computer. To do this, edit the file /etc/shutdown.allow and insert the authorized user fhem there (each the login name per line). Now Fhem can reboot the operating system with /sbin/shutdown -a -r now.
  

Define

define <name> PIFACE


Set


set <name> <port> <value>


• set single port n to 1 (on) or 0 (off)
  
  Examples:
  set <name> 3 1 => set port 3 on
  set <name> 5 0 => set port 5 off
  


• set all ports in one command by bitmask
  
  Example:
  set <name> all 255 => set all ports on
  set <name> all 0 => set all ports off
  set <name> all 170 => bitmask(170) = 10101010 => set ports 1 3 5 7 on, ports 0 2 4 6 off
  
  
  port 76543210
bit  10101010

Get


get <name> <port>


• get state of single port
  
  Example:
  get <name> 3 => get state of port 3
  


• get state of input ports and update changed readings
  
  Example:
  get <name> in => get state of all input ports
  


• get state of out ports and update changed readings
  
  Example:
  get <name> out => get state of all output ports
  


• get state of input and out ports and update all readings
  
  Example:
  get <name> all => get state of all ports
  

Attributes


• defaultState last|off|0|1, [defaultState] = off is default.
  Restoration of the status of the output port after a Fhem reboot.
• disable 0|1
  If applied set commands will not be executed.
• disabledForIntervals HH:MM-HH:MM HH:MM-HH-MM...
  Space separated list of HH:MM tupels. If the current time is between the two time specifications, set commands will not be executed. Instead of HH:MM you can also specify HH or HH:MM:SS. To specify an interval spawning midnight, you have to specify two intervals, e.g.:
  23:00-24:00 00:00-01:00
• pollInterval off|0.5|0.75|1,1.5,2,...,9,10, [pollInterval] = off is default.
  Define the polling interval of the input ports in seconds.
• portMode0
  portMode1
  portMode2
  portMode3
  portMode4
  portMode5
  portMode6
  portMode7 tri|up, [portMode<0..7>] = tri is default.
  This enables (up) or disables (tri) the internal pull-up resistor on the given input port. You need to enable the pull-up if you want to read any of the on-board switches on the PiFace board.
• readingFnAttributes
• shutdownClearIO no|yes, [shutdownClearIO] = no is default.
  Clear IO ports during shutdown.
• watchdog off|on|silent, [watchdog] = off is default.
  The function of the PiFace extension can be monitored periodically. The watchdog module checks the function of ports in7 and out7. If the watchdog function is to be used, ports in7 and out7 are reserved for this purpose. The port 7 must be connected to ground.
  If [watchdog] = on, the result of which is periodically logged and written to the reading watchdog.
  If [watchdog] = silent, FHEM is restarted after the first error detected. If the error could not be eliminated, then the Raspberry operating system is restarted. If the error is not corrected as well, the monitoring function is disabled and the error is logged.
• watchdogInterval 10..65535, [watchdogInterval] = 60 is default.
  Interval between two monitoring tests in seconds.

Generated Events:


• <all>: 0...255
  state of all output port as bitmap
• <out0..out7>: 0|1
  state of output port 0..7
• <in0..in7>: 0|1
  state of input port 0..7
• watchdog: off|ok|error|restart|start
  state of the watchdog function
• state: active|error

PIONEERAVR

[EN DE]

This module allows to remotely control a Pioneer AV receiver (only the Main zone, other zones are controlled by the module PIONEERAVRZONE) equipped with an Ethernet interface or a RS232 port. It enables Fhem to
• switch ON/OFF the receiver
• adjust the volume
• set the input source
• and configure some other parameters


This module is based on the Pioneer documentation and tested with a Pioneer AV receiver VSX-923 from Pioneer.

Note: this module requires the Device::SerialPort or Win32::SerialPort module if the module is connected via serial Port or USB.

This module tries to
• keep the data connection between Fhem and the Pioneer AV receiver open. If the connection is lost, this module tries to reconnect once
• forwards data to the module PIONEERAVRZONE to control the ZONEs of a Pioneer AV receiver
As long as Fhem is connected to the Pioneer AV receiver no other device (e.g. a smart phone) can connect to the Pioneer AV receiver on the same port. Some Pioneer AV receivers offer more than one port though. From Pioneer recommend port numbers:00023,49152-65535, Invalid port numbers:00000,08102

Define
define <name> PIONEERAVR telnet <IPAddress:Port>

or

define <name> PIONEERAVR serial <SerialDevice>[<@BaudRate>]

Defines a Pioneer AV receiver device (communication interface and main zone control). The keywords telnet or serial are fixed. Default port on Pioneer AV receivers is 23 (according to the above mentioned Pioneer documetation) or 8102 (according to posts in the Fhem forum)
Note: PIONEERAVRZONE devices to control zone2, zone3 and/or HD-zone are autocreated on reception of the first message for those zones.

Examples:
define VSX923 PIONEERAVR telnet 192.168.0.91:23
define VSX923 PIONEERAVR serial /dev/ttyS0
define VSX923 PIONEERAVR serial /dev/ttyUSB0@9600



Set
set <name> <what> [<value>]

where <what> is one of
• bass <-6 ... 6> - Bass from -6dB to + 6dB (is only available if tone = on and the ListeningMode supports it)
• channel <1 ... 9> - To change the tuner preset. Only available for input = 2 (Tuner)
• channelDown - Changes to the next lower tuner preset. Only available for input = 2 (Tuner)
• channelStraight -
To change the tuner preset with values as they are shown in the display of the Pioneer AV receiver eg. "A1". Only available for input = 2 (Tuner)
• channelUp - Changes to the next higher tuner preset. Only available for input = 2 (Tuner)
• down - "arrow key down". Available for the same inputs as "play"
• enter - "Enter key". Available for the same inputs as "play"
• eq - Turns the equalizer on or off
• fwd - Fast forward. Available for the same inputs as "play"
• hdmiOut <1+2|1|2|off> - Switches the HDMI output 1 and/or 2 of the Pioneer AV Receivers on or off.
• input The list of possible (i.e. not deactivated) inputs is read in during Fhem start and with get statusRequest. Renamed inputs are shown with their new (renamed) name
• inputDown - Select the next lower input for the Main Zone
• inputSkip [0|1] - Enables/disables the input (0: enable , 1: disable )
• inputUp - Select the next higher input for the Main Zone
• left - "Arrow key left". Available for the same inputs as "play"
• listeningMode - Sets a ListeningMode e.g. autoSourround, direct, action,...
• mcaccMemory <1...6> - Sets one of the 6 predefined MCACC settings for the Main Zone
• menu - "Menu-key" of the remote control. Available for the same inputs as "play"
• mute - Mute the Main Zone of the Pioneer AV Receiver. "mute = on" means: Zero volume
• networkStandby - Turns Network standby on or off. To turn on a Pioneer AV Receiver with this module from standby, Network Standby must be "on". set <name> networkStandby on should do this
• next - Available for the same inputs as "play"
• off - Switch the Main Zone to standby
• on - Switch the Main Zone on from standby. This can only work if "Network Standby" is "on" in the Pioneer AV Receiver. Refer to "networkStandby" above.
• pause - Pause replay. Available for the same inputs as "play"
• play - Starts replay for the following inputs:
  • usbDac
  • ipodUsb
  • xmRadio
  • homeMediaGallery
  • sirius
  • adapterPort
  • internetRadio
  • pandora
  • mediaServer
  • favorites
  • mhl
• prev - Changes to the previous title. Available for the same inputs as "play".
• raw - Sends the command <PioneerCommand> unchanged to the Pioneer AV receiver. A list of all available commands is available in the Pioneer documentation mentioned above
• renameInputAlias - Renames the input as it is displayed on the Pioneer AV receiver (and as it is listed in this module)
• remoteControl - where is one of:
  • cursorDown
  • cursorRight
  • cursorLeft
  • cursorEnter
  • cursorReturn
  • homeMenu
  • statusDisplay
  • audioParameter
  • hdmiOutputParameter
  • videoParameter
  • homeMenu
  Simulates the keys of the remote control. Warning: The cursorXX keys cannot change the inputs -> set up ... can be used for this
• reopen - Tries to reconnect Fhem to the Pioneer AV Receiver
• repeat - Repeat for the following inputs: AdapterPort, Ipod, Favorites, InternetRadio, MediaServer. Cycles between
  • no repeat
  • repeat current title
  • repeat all titles
• return - "Return key". Available for the same inputs as "play"
• rev - "rev key". Available for the same inputs as "play"
• right - "Arrow key right". Available for the same inputs as "play"
• selectLine01 - selectLine08 - Available for the same inputs as "play". If there is an OSD you can select the lines directly
• shuffle - Random replay. For the same inputs available as "repeat". Toggles between random on and off
• signalSelect - Signal select function
• speakers - Turns speaker A and or B on or off.
• standingWave - Turns Standing Wave on or off for the Main Zone
• statusRequest - Asks the Pioneer AV Receiver for information to update the modules readings
• stop - Stops replay. Available for the same inputs as "play"
• toggle - Toggle the Main Zone to/from Standby
• tone - Turns tone on or in bypass
• treble <-6 ... 6> - Treble from -6dB to + 6dB (works only if tone = on and the ListeningMode permits it)
• up - "Arrow key up". Available for the same inputs as "play"
• volume <0 ... 100> - Volume of the Main Zone in % of the maximum volume
• volumeDown - Reduce the volume of the Main Zone by 0.5dB
• volumeUp - Increase the volume of the Main Zone by 0.5dB
• volumeStraight<-80.5 ... 12> - Set the volume of the Main Zone with values from -80 ... 12 (As it is displayed on the Pioneer AV receiver
• set extensions are supported (except <blink> )


Example:
set VSX923 on


set <name> reopen

Closes and reopens the device. Could be handy if the connection between Fhem and the Pioneer AV receiver is lost and cannot be reestablished automatically.


Get does not return any value but asks the Pioneer AVR for the current status (e.g. of the volume). As soon as the Pioneer AVR replies (the time, till the Pioneer AVR replies is unpredictable), the readings or internals of this pioneerAVR modul are updated.
• loadInputNames - reads the names of the inputs from the Pioneer AV receiver and checks if those inputs are enabled
• audioInfo - get the current audio parameters from the Pioneer AV receiver (e.g. audioInputSignal, audioInputFormatXX, audioOutputFrequency)
• display - updates the reading 'display' and 'displayPrevious' with what is shown on the display of the Pioneer AV receiver
• bass - updates the reading 'bass'
• channel -
• currentListIpod - updates the readings currentAlbum, currentArtist, etc.
• currentListNetwork -
• display -
• input -
• listeningMode -
• listeningModePlaying -
• macAddress -
• avrModel - get the model of the Pioneer AV receiver, eg. VSX923
• mute -
• networkPorts - get the open tcp/ip ports of the Pioneer AV Receiver
• networkSettings - get the IP network settings (ip, netmask, gateway,dhcp, dns1, dns2, proxy) of the Pioneer AV Receiver. The values are stored as INTERNALS not as READINGS
• networkStandby - get the current setting of networkStandby -> the value of networkStandby (on|off) is stored as an INTERNAL not as a READING
• power - get the Power state of the Pioneer AV receiver
• signalSelect -
• softwareVersion - get the software version of the software currently running in the Pioneer AV receiver. The value is stored as INTERNAL
• speakers -
• speakerSystem -
• tone -
• tunerFrequency - get the current frequency the tuner is set to
• tunerChannelNames -
• treble -
• volume -


Attributes


• connectionCheck   1..120,off   Pings the Pioneer AVR every X seconds to verify connection status. Defaults to 60 seconds.
• timeout   1,2,3,4,5,7,10,15   Max time in seconds till the Pioneer AVR replies to a ping. Defaults to 3 seconds.
• checkStatusStart <enable|disable> - Enables/disables the status update (read all values from the Pioneer AV receiver, can take up to one minute) when the module is loaded.(Default: enable)
• checkStatusReconnect <enable|disable> - Enables/disables the status update (read all values from the Pioneer AV receiver, can take up to one minute) when the connection to the Pioneer AV receiver is reestablished.(Default: enable)
• logTraffic <loglevel> - Enables logging of sent and received datagrams with the given loglevel. Control characters in the logged datagrams are escaped, i.e. a double backslash is shown for a single backslash, \n is shown for a line feed character,...
• verbose - 0: log es less as possible, 5: log as much as possible
• volumeLimit <0 ... 100> - limits the volume to the given value
• volumeLimitStraight <-80 ... 12> - limits the volume to the given value


Generated Readings/Events:


• audioAutoPhaseControlMS - currently configured Auto Phase Control in ms
• audioAutoPhaseControlRevPhase - acurrently configured Auto Phase Control reverse Phase -> 1 means: reverse phase
• audioInputFormat - Shows if the channel XXX is available in the audio input signal (1 means: is available)
• audioInputFrequency - Frequency of the input signal
• audioInputSignal - Type of the input signal (z.B. ANALOG, PCM, DTS,...)
• audioOutputFormat - Shows if the channel XXX is available in the audio output sgnal (1 means: is available)
• audioOutputFrequency - Frequency of the audio output signal
• bass - currently set bass
• channel - Tuner Preset (1...9)
• channelStraight - Tuner Preset as diplayed in the display of the Pioneer AV Receiver, e.g. A2
• display - Currently dispayed text in the display of the Pioneer AV Receiver
• displayPrevious - Previous displayed text
• eq - Equalizer status of the Pioneer AV Receiver (on|off)
• hdmiOut - Shows the currently selected HDMI-output(s)?
• input - shows the currently selected input
• inputsList - ":" separated list of all activated inputs
• listeningMode - Currently set Listening Mode
• listeningModePlaying - Currently used Listening Mode
• mcaccMemory - MCACC Setting
• mute - Mute (on|off)
• power - Main Zone on or standby?
• pqlsWorking - currently set PQLS
• presence - Is the Pioneer AV Receiver reachable via ethernet?
• screenHirarchy - Hirarchy of the currently shown On Screen Displays (OSD)
• screenLine01...08 - Content of the lines 01...08 of the OSD
• screenLineHasFocus - Which line of the OSD has the focus?
• screenLineNumberFirst - Long lists are shown in the OSD in smaller pages with 8 lines. This shows which elemnt of the lang list is the currently shown first line.
• screenLineNumberLast - Long lists are shown in the OSD in smaller pages with 8 lines. This shows which elemnt of the lang list is the currently shown last line.
• screenLineNumbersTotal - How many lines has the full list
• screenLineNumbers - How many lines has the OSD
• screenLineType01...08 - Which type has line 01...08? E.g. "directory", "Now playing", "current Artist",...
• screenName - Name of the OSD
• screenReturnKey - Is the "Return-Key" in this OSD available?
• screenTopMenuKey - Is the "Menu-Key" in this OSD available?
• screenToolsKey - Is the "Tools-Key" (Menu, edit, ipod control) in this OSD available?
• screenType - Type of the OSD, e.g. "message", "List", "playing(play)",...
• speakerSystem - Shows how the rear surround speaker connectors and the B-speaker connectors are used
• speakers - Which speaker output connectors are active?
• standingWave - Standing wave
• state - Is set while connecting from fhem to the Pioneer AV Receiver (disconnected|innitialized|off|on|opened)
• stateAV - Status from user perspective combining readings presence, power, mute and playStatus to a useful overall status (on|off|absent|stopped|playing|paused|fast-forward|fast-rewind).
• tone - Is the tone control turned on?
• treble - Current value of treble
• tunerFrequency - Tuner frequency
• volume - Current value of volume (0%-100%)
• volumeStraight - Current value of volume os displayed in the display of the Pioneer AV Receiver
• alternateVolumeControl <enable|disable> - Enables/disables alternate volume control for devices that don't support direct volume setting (e.g. VSX-52x/VSX-82x)

PIONEERAVRZONE

[EN DE]

Define
define <name> PIONEERAVRZONE <zone>

Defines a Zone (zone2, zone3 or hdZone) of a PioneerAVR device.
Note: devices to control zone2, zone3 and/or HD-zone are autocreated on reception of the first message for those zones.

Normally, the PIONEERAVRZONE device is attached to the latest previously defined PIONEERAVR device for I/O. Use the IODev attribute of the PIONEERAVRZONE device to attach to any PIONEERAVR device, e.g. attr myPioneerAvrZone2 IODev myPioneerAvr.

Examples:
define myPioneerAvrZone2 PIONEERAVRZONE zone2
attr myPioneerAvrZone2 IODev myPIONEERAVR


Set
set <name> <what> [<value>]

where <what> is one of
• reopen
• off
  put zone into standby
• on
  turn zone on from standby
• toggle
  toggles zone power
• volume <0 ... 100>
  zone volume in % of the maximum volume
• volumeUp
  increases the zone volume by 0.5dB
• volumeDown
  decreases the zone volume by 0.5dB
• volumeStraight<-80.5 ... 12>
  same values for zone volume as shown on the display of the Pioneer AV receiver
• mute
• input
  the list of possible (i.e. not deactivated) inputs is read in during Fhem start and with get statusRequest
• inputUp
  change zone input to next input
• inputDown
  change zone input to previous input
• set extensions are supported (except <name>)


Example:
set VSX923Zone2 on




Get
• get <name> input
  
  Update the reading for the zone input


Attributes


• IOdev Name of the device which communicates with the phisical Pioneer AV receiver via ethernet or rs232
• verbose

POKEYS

[EN DE]

The POKEYS module is used to control the LAN POKEYS device (POKEYS56e) which supports up to 56 digital input, analog inputs, counter inputs and digital outputs. Each port/pin has to be configured before it can be used.

Define
define <name> POKEYS <ip-address> <pin> <io-state> [<time in ms>]

<ip-address> the IP address where the POKEYS device can be accessed
<pin> the pin number which should be configured
<io-state> the new io state of the pin Obsolete(=undef) DigIn DigOut AdcIn DigInCtRise DigInCtFall ExtDigOut GetBasic
<time in ms> optional else 1000ms: cyclic update time for Input pin

Example:
define PoInfo POKEYS 192.168.178.34 0 GetBasic
# creates a virtual pin for getting infos about the device with the get command
define Pin44in POKEYS 192.168.178.34 44 DigIn 200
# creates a digitial input port on pin 44
define Pin25out POKEYS 192.168.178.34 25 DigOut
# creates a digial output port on pin 25


Set
set <name> <state> [<time in ms>]

<state> can be OFF ON OFF_PULSE ON_PULSE
<time in ms> optional else 1000ms hold time for the ON_PULSE OFF_PULSE state

Example:
set Pin25out ON
# sets Pin25out to ON (0V)


Get
get <name> <type>

only supported for pins of type GetBasic
<type> can be Version DevName Serial User CPUload

Example:
get PoInfo Version
# gets the version of the POKEYS device


Attributes
todo

PRESENCE

[EN DE]

The PRESENCE module provides several possibilities to check the presence of mobile phones or similar mobile devices such as tablets.

This module provides several operational modes to serve your needs. These are:


• lan-ping - A presence check of a device via network ping in your LAN/WLAN.
• fritzbox - A presence check by requesting the device state from the FritzBox internals (only available when running FHEM on a FritzBox!).
• local-bluetooth - A presence check by searching directly for a given bluetooth device nearby.
• function - A presence check by using your own perl function which returns a presence state.
• shellscript - A presence check by using an self-written script or binary which returns a presence state.
• event - A presence check by listening to FHEM events of other definitions.
• lan-bluetooth - A presence check of a bluetooth device via LAN network by connecting to a presenced or collectord instance.

Each mode can be optionally configured with a specific check interval and a present check interval.


• check-interval - The interval in seconds between each presence check. Default value: 30 seconds
• present-check-interval - The interval in seconds between each presence check in case the device is present. Otherwise the normal check-interval will be used.


Define


Mode: lan-ping

define <name> PRESENCE lan-ping <ip-address> [ <check-interval> [ <present-check-interval> ] ]

Checks for a network device via PING requests and reports its presence state.

Example

define iPhone PRESENCE lan-ping 192.168.179.21

Mode: fritzbox

define <name> PRESENCE fritzbox <device-name/mac-address> [ <check-interval> [ <present-check-interval> ] ]

Checks for a network device by requesting the internal state on a FritzBox via ctlmgr_ctl. The device-name must be the same as shown in the network overview of the FritzBox or can be substituted by the MAC address with the format XX:XX:XX:XX:XX:XX

This check is only applicable when FHEM is running on a FritzBox! The detection of absence can take about 10-15 minutes!

Example

define iPhone PRESENCE fritzbox iPhone-6
define iPhone PRESENCE fritzbox 00:06:08:05:0D:00

Mode: local-bluetooth

define <name> PRESENCE local-bluetooth <bluetooth-address> [ <check-interval> [ <present-check-interval> ] ]

Checks for a bluetooth device and reports its presence state. For this mode the shell command "hcitool" is required (provided with a bluez installation under Debian via APT), as well as a functional bluetooth device directly attached to your machine.

Example

define iPhone PRESENCE local-bluetooth 0a:8d:4f:51:3c:8f

Mode: function

define <name> PRESENCE function {...} [ <check-interval> [ <present-check-interval> ] ]

Checks for a presence state via perl-code. You can use a self-written perl function to obtain the presence state of a specific device (e.g. via SNMP check).

The function must return 0 (absent) or 1 (present). An example can be found in the FHEM-Wiki.

Example

define iPhone PRESENCE function {snmpCheck("10.0.1.1","0x44d77429f35c")}

Mode: shellscript

define <name> PRESENCE shellscript "<path> [<arg1>] [<argN>]..." [ <check-interval> [ <present-check-interval> ] ]

Checks for a presence state via shell script. You can use a self-written script or binary in any language to obtain the presence state of a specific device (e.g. via SNMP check).

The shell must return 0 (absent) or 1 (present) on console (STDOUT). Any other values will be treated as an error

Example

define iPhone PRESENCE shellscript "/opt/check_device.sh iPhone"

Mode: event

define <name> PRESENCE event <absent-regexp> <present-regexp>

Listens for events of other FHEM definitions to determine a presence state. You must provide two event regexp's in the same style as for the notify module.

If an event matches one of the provides regexps, the presence state will be changed.

Example

define Presence_John PRESENCE event Door_Switch:off Door_Switch:on

Mode: lan-bluetooth

Checks for a bluetooth device with the help of presenced or collectord. They can be installed where-ever you like, just must be accessible via network. The given device will be checked for presence status.

define <name> PRESENCE lan-bluetooth <bluetooth-address> <ip-address>[:port] [ <check-interval> ]

The default port is 5111 (presenced). Alternatly you can use port 5222 (collectord)

Example

define iPhone PRESENCE lan-bluetooth 0a:4f:36:d8:f9:89 127.0.0.1:5222

presenced


The presence is a perl network daemon, which provides presence checks of multiple bluetooth devices over network. It listens on TCP port 5111 for incoming connections from a FHEM PRESENCE instance or a running collectord.


Usage:
  presenced [-d] [-p <port>] [-P <filename>]
  presenced [-h | --help]


Options:
  -p, --port
     TCP Port which should be used (Default: 5111)
  -P, --pid-file
     PID file for storing the local process id (Default: /var/run/presenced.pid)
  -d, --daemon
     detach from terminal and run as background daemon
  -n, --no-timestamps
     do not output timestamps in log messages
  -v, --verbose
     Print detailed log output
  -h, --help
     Print detailed help screen

It uses the hcitool command (provided by a bluez installation) to make a paging request to the given bluetooth address (like 01:B4:5E:AD:F6:D3). The devices must not be visible, but still activated to receive bluetooth requests.

If a device is present, this is send to FHEM, as well as the device name as reading.

The presenced is available as:


• direct perl script file: presenced
• .deb package for Debian/Raspbian (noarch): presenced-1.5.deb


lepresenced


lepresenced is a Perl network daemon that provides presence checks of multiple bluetooth devices over network. In contrast to presenced, lepresenced covers Bluetooth 4.0 (low energy) devices, i. e. Gigaset G-Tags, FitBit Charges. lepresenced listens on TCP port 5333 for connections of a PRESENCE definition or collectord.


Usage:
    lepresenced --bluetoothdevice <bluetooth device> --listenaddress <listen address> --listenport <listen port> --loglevel <log level> --daemon
    lepresenced -b <bluetooth device> -a <listen address> -p <listen port> -l <log level> -d

valid log levels:
    LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG. Default: LOG_INFO

Examples:
    lepresenced --bluetoothdevice hci0 --listenaddress 127.0.0.1 --listenport 5333 --daemon
    lepresenced --loglevel LOG_DEBUG --daemon

To detect the presence of a device, it uses the command hcitool lescan (package: bluez) to continuously listen to beacons of Bluetooth LE devices.

If a device is present, this is send to FHEM, as well as the device name as reading.

The presenced is available as:


• Perl script: lepresenced
• .deb package (noarch): contrib/PRESENCE/deb/


collectord


The collectord is a perl network daemon, which handles connections to several presenced installations to search for multiple bluetooth devices over network.

It listens on TCP port 5222 for incoming connections from a FHEM presence instance.

Usage:
  collectord -c <configfile> [-d] [-p <port>] [-P <pidfile>]
  collectord [-h | --help]


Options:
  -c, --configfile <configfile>
     The config file which contains the room and timeout definitions
  -p, --port
     TCP Port which should be used (Default: 5222)
  -P, --pid-file
     PID file for storing the local process id (Default: /var/run/collectord.pid)
  -d, --daemon
     detach from terminal and run as background daemon
  -n, --no-timestamps
     do not output timestamps in log messages
  -v, --verbose
     Print detailed log output
  -l, --logfile <logfile>
     log to the given logfile
  -h, --help
     Print detailed help screen

Before the collectord can be used, it needs a config file, where all different rooms, which have a presenced detector, will be listed. This config file looks like:



    # room definition
    # ===============
    #
    [room-name]              # name of the room
    address=192.168.0.10     # ip-address or hostname
    port=5111                # tcp port which should be used (5111 is default)
    presence_timeout=120     # timeout in seconds for each check when devices are present
    absence_timeout=20       # timeout in seconds for each check when devices are absent

    [living room]
    address=192.168.0.11
    port=5111
    presence_timeout=180
    absence_timeout=20

If a device is present in any of the configured rooms, this is send to FHEM, as well as the device name as reading and the room which has detected the device.

The collectord is available as:


• direct perl script file: collectord
• .deb package for Debian (noarch): collectord-1.8.1.deb




Set
• statusRequest - Schedules an immediatly check.
• power - Executes the given power command which is set as attribute to power (on or off) the device (only when attribute "powerCmd" is set)
• overrideInterval - Override the check interval to the given number of seconds. (not applicable in mode "event" and "lan-bluetooth")
• clearOverride - clear an active check interval override (only if set command overrideInterval was executed before)

Get
N/A

Attributes


• do_not_notify
• readingFnAttributes


• disable
If this attribute is activated, an active check will be disabled.

Possible values: 0 => not disabled , 1 => disabled
Default Value is 0 (not disabled)


• absenceThreshold

(not applicable in mode "event" )
The number of checks that have to result in "absent" before the state of the PRESENCE definition is changed to "absent". This can be used to verify the absence of a device with multiple check runs before the state is finally changed to "absent". If this attribute is set to a value >1, the reading state and presence will be set to "maybe absent" during the absence verification.

Default Value is 1 (no absence verification)


• presenceThreshold

(not applicable in mode "event" )
The number of checks that have to result in "present" before the state of the PRESENCE definition is changed to "present". This can be used to verify the permanent presence of a device with multiple check runs before the state is finally changed to "present". If this attribute is set to a value >1, the reading state and presence will be set to "maybe present" during the presence verification.

Default Value is 1 (no presence verification)


• absenceTimeout

(only in mode "event" applicable)
The timeout after receiving an "absent" event, before the state of the PRESENCE definition is switched to "absent". This can be used to verify the permanent absence by waiting a specific time frame to not receive an "present" event. If this timeout is reached with no "present" event received in the meantime, the presence state will finally be set to "absent". The timeout is given in HH:MM:SS format, where hours and minutes are optional. If this attribute is set to a valid value, the reading state and presence will be set to "maybe absent" during the absence verification.

Default Value is 0 (no absence verification)


• presenceTimeout

(only in mode "event" applicable)
The timeout after receiving an "present" event, before the state of the PRESENCE definition is switched to "present". This can be used to verify the permanent presence by waiting a specific time frame to not receive an "absent" event. If this timeout is reached with no "absent" event received in the meantime, the presence state will finally be set to "present". The timeout is given in HH:MM:SS format, where hours and minutes are optional. If this attribute is set to a valid value, the reading state and presence will be set to "maybe present" during the presence verification.

Default Value is 0 (no presence verification)


• retryInterval

(Not applicable in mode "event" or "lan-bluetooth")
The check interval in case a check is prematurely aborted and was unable to check the presence. In this case, PRESENCE reschedules the next check as retry within the given retry interval in seconds (usually lower than the regular check interval).

Default Value is 10 seconds


• retryCount

(Not applicable in mode "event" or "lan-bluetooth")
The maximum number of checks to perform within the retryInterval in case a check is prematurely aborted and was unable to check the presence. PRESENCE will try to retry after a failed check to a maximum of the given number of tries. If all retries fails also, it will uses afterwards the regular check interval.

Default Value is 3 (number of check retries)


• pingCount
(Only in mode "ping" applicable)
Changes the count of the used ping packets to recognize a present state. Depending on your network performance sometimes a packet can be lost or blocked.

Default Value is 4 (packets)


• bluetoothHciDevice
(Only in Mode "local-bluetooth" applicable)
Set a specific bluetooth HCI device to use for scanning. If you have multiple bluetooth modules connected, you can select a specific one to use for scanning (e.g. hci0, hci1, ...).


• fritzboxCheckSpeed
(Only in Mode "fritzbox" applicable)
When this attribute is enabled, the network speed is checked in addition to the device state.
This only makes sense for wireless devices connected directly to the FritzBox.

Possible values: 0 => do not check speed, 1 => check speed when device is active
Default value is 0 (no speed check)


• powerCmd

Define a FHEM command, which powers on or off the device.

When executing the powerCmd (set command: power) following placeholders will be replaced by there corresponding values:


• $NAME - name of the PRESENCE definition
• $ADDRESS - the address of the PRESENCE definition as given in the define statement
• $ARGUMENT - the argument given to the power set command (e.g. "on" or "off)

Example FHEM commands:


• set PowerSwitch_1 on
• set PowerSwitch_1 $ARGUMENT
• "/opt/power_on.sh $ADDRESS"
• {powerOn("$ADDRESS", "username", "password")}

Generated readings/events:


General readings/events:


• state: (absent|maybe absent|present|maybe present|disabled|error|timeout) - The state of the device, check errors or "disabled" when the disable attribute is enabled
• presence: (absent|maybe absent|present|maybe present) - The presence state of the device. The value "maybe absent" only occurs if absenceThreshold is activated. The value "maybe present" only occurs if presenceThreshold is activated.
• powerCmd: (executed|failed) - power command was executed or has failed


Bluetooth specific readings/events:


• device_name: $name - The name of the Bluetooth device in case it's present


FRITZ!Box specific readings/events:


• speed: $speed - The current speed of the checked device if attribute fritzboxCheckSpeed is activated


presenced/collectord specific readings/events:


• command_accepted: $command_accepted (yes|no) - Was the last command acknowleged and accepted by the presenced or collectord?
• room: $room - If the module is connected with a collector daemon this event shows the room, where the device is located (as defined in the collectord config file)

PRESENCE2

[EN DE]

The PRESENCE2 module provides several possibilities to check the PRESENCE2 devices such as mobile phones or tablets.
Furthermore FHEM or system level actions can be executed and parsed periodicaly
Additional FHEM entites can be superviced for regular activity.

This module provides several operational modes to serve your needs. These are:


• lan-ping - device PRESENCE2 check utilizing network ping.
• function - executing user defined FHEM command.
• shellscript - executing user defined OS command.
• bluetooth - bluetooth device scan from FHEM server .
• lan-bluetooth - device PRESENCE2 check via LAN network by connecting to a PRESENCE2d or collectord instance.

Daemon entity: A daemon entity is auto-created if not definition of a PRESENCE2 entity.
The daemon schedules and executes the ping and scan actions for all entites except lan-bluetooth. It cyclic executes as defined by attr intervalNormal.
Since the daemon executes the scan activities (except lan-bluetooth) any report and detection cannot be faster than the deamon cycle.


Define
Mode: lan-ping
define <name> PRESENCE2 lan-ping <ip-address>
Checks for a network device via PING requests and reports its PRESENCE2 state.
Example
define iPhone PRESENCE2 lan-ping 192.168.179.21

Mode: function
define <name> PRESENCE2 function cmd:<command> scan:<scanExpression>
Executes the FHEM command and parses the reply for scanExpression.

• command can be any FHEM expression such as
  get PsnceDaemon list normal
{ReadingsVal("PsnceDaemon","state","empty")}

• scanExpression is a string or regex to parse the reply
  
Example
define iPhone PRESENCE2 function cmd:{snmpCheck("10.0.1.1","0x44d77429f35c")} scan:1

Mode: shellscript
define <name> PRESENCE2 shellscript cmd:<command> scan:<scanExpression>
Executes the OS command and parses the reply for scanExpression.
Example
define iPhone PRESENCE2 shellscript cmd:/opt/check_device.sh iPhone scan:1

Mode: bluetooth
define <name> PRESENCE2 bluetooth <address>
Scans for the MAC address on the FHEM server's BT interface.
Example
define iPhone PRESENCE2 bluetooth 0a:8d:4f:51:3c:8f

Mode: lan-bluetooth
define <name> PRESENCE2 lan-bluetooth cmd:<address> scan:<ip-address>
Checks for a bluetooth device with the help of PRESENCE2d or collectord. They can be installed where-ever you like, however accessible via network. The given device will be checked for PRESENCE2 status.
The default port is 5111 (PRESENCE2d). Alternatly you can use port 5222 (collectord)
Example
define iPhone PRESENCE2 lan-bluetooth 0a:4f:36:d8:f9:89 127.0.0.1:5222

PRESENCE2d

PRESENCE2 is a perl network daemon, which provides PRESENCE2 checks of multiple bluetooth devices over network. It listens on TCP port 5111 for incoming connections from a FHEM PRESENCE2 instance or a running collectord.
Executes the OS command and parses the reply for scanExpression.
Example
define iPhone PRESENCE2 lan-bluetooth 0a:8d:4f:51:3c:8f


Usage:
  PRESENCE2d [-d] [-p <port>] [-P <filename>]
  PRESENCE2d [-h | --help]

Options:
  -p, --port
     TCP Port which should be used (Default: 5111)
  -P, --pid-file
     PID file for storing the local process id (Default: /var/run/PRESENCE2d.pid)
  -d, --daemon
     detach from terminal and run as background daemon
  -n, --no-timestamps
     do not output timestamps in log messages
  -v, --verbose
     Print detailed log output
  -h, --help
     Print detailed help screen

It uses the hcitool command (provided by a bluez installation) to make a paging request to the given bluetooth address (like 01:B4:5E:AD:F6:D3). The devices must not be visible, but still activated to receive bluetooth requests.

If a device is present, this is send to FHEM, as well as the device name as reading.

The PRESENCE2d is available as:


• direct perl script file: PRESENCE2d
• .deb package for Debian/Raspbian (noarch): PRESENCE2d-1.5.deb


lePRESENCE2d

lePRESENCE2d is a Perl network daemon that provides PRESENCE2 checks of multiple bluetooth devices over network. In contrast to PRESENCE2d, lePRESENCE2d covers Bluetooth 4.0 (low energy) devices, i. e. Gigaset G-Tags, FitBit Charges. lePRESENCE2d listens on TCP port 5333 for connections of a PRESENCE2 definition or collectord.
To detect the PRESENCE2 of a device, it uses the command hcitool lescan (package: bluez) to continuously listen to beacons of Bluetooth LE devices.

If a device is present, this is send to FHEM, as well as the device name as reading.

The PRESENCE2d is available as:


• Perl script: lePRESENCE2d
• .deb package (noarch): contrib/PRESENCE2/deb/


collectord

The collectord is a perl network daemon, which handles connections to several PRESENCE2d installations to search for multiple bluetooth devices over network.

It listens on TCP port 5222 for incoming connections from a FHEM PRESENCE2 instance.

Usage:
  collectord -c <configfile> [-d] [-p <port>] [-P <pidfile>]
  collectord [-h | --help]

Options:
  -c, --configfile <configfile>
     The config file which contains the room and timeout definitions
  -p, --port
     TCP Port which should be used (Default: 5222)
  -P, --pid-file
     PID file for storing the local process id (Default: /var/run/collectord.pid)
  -d, --daemon
     detach from terminal and run as background daemon
  -n, --no-timestamps
     do not output timestamps in log messages
  -v, --verbose
     Print detailed log output
  -l, --logfile <logfile>
     log to the given logfile
  -h, --help
     Print detailed help screen

Before the collectord can be used, it needs a config file, where all different rooms, which have a PRESENCE2d detector, will be listed. This config file looks like:


    # room definition
    # ===============
    #
    [room-name]              # name of the room
    address=192.168.0.10     # ip-address or hostname
    port=5111                # tcp port which should be used (5111 is default)
    PRESENCE2_timeout=120     # timeout in seconds for each check when devices are present
    absence_timeout=20       # timeout in seconds for each check when devices are absent

    [living room]
    address=192.168.0.11
    port=5111
    PRESENCE2_timeout=180
    absence_timeout=20

If a device is present in any of the configured rooms, this is send to FHEM, as well as the device name as reading and the room which has detected the device.

The collectord is available as:


• direct perl script file: collectord
• .deb package for Debian (noarch): collectord-1.8.1.deb

Set
• set <name> statusRequest
  Schedules an immediatly check.
  


• set <name> killChilds
  Kills all childs.
  


• For childs:
  
  set <name> clearCounts
  Reset counter values.
  
  For deamon:
  
  set <name> clearCounts <daemon|allEntities>
  <daemon> - clear all counts from deamon.
  <allEntities> - clear all counts from deamon and all PRESENCE2 entities.
  



Get
• set <name> list <normal|full>
  <normal> - execute list command.
  <full> - execute list command and include hidden entries.
  


• daemon only
  
  set <name> childInfo <PRESENCE2|all>
  <PRESENCE2> - Show all running forked processes started by PRESENCE2.
  <all> - Show all running forked processes.
  


• daemon only
  
  set <name> statusInfo <definition|status>
  <definition> - Return a table of the definition for all PRESENCE2 entities.
  <status> - Return a table of the status for all PRESENCE2 entities.
  



Attributes
• attr <name> FhemLog3Std <0 | 1>
  If set, the log information will be written in standard Fhem format.
  If the output to a separate log file was activated by a verbose 5, this will be ended.
  The separate log file and the associated FileLog device are deleted.
  If the attribute is set to 0 or deleted and the device verbose is set to 5, all log data will be written to a separate log file.
  Log file name: deviceName_debugLog.dlog
  In the INTERNAL Reading DEBUGLOG there is a link <DEBUG log can be viewed here> for direct viewing of the log.
  


• for future use
  set <name> intervalPresent <seconds>
  Time in seconds to check status if the device is in state present. It is adjusted to the deamons cycle.
  Not applicable for daemon entity
  


• set <name> intervalNormal <seconds>
  Time in seconds to check status if the device is in state present. It is adjusted to the deamons cycle.
  Not applicable for daemon entity
  


• nonblockingTimeOut <30..240>
  
  timeout for regularly checking presende. Default is 60 (seconds).


• set <name> bluetoothHciDevice <hci[0..n]>
  (Only applicable in local “bluetooth” mode and not applicable to Daemon device)
  
  Set a specific bluetooth HCI device to use for scanning. If you have multiple bluetooth modules connected,
  you can select a specific one to use for scanning (e.g. hci0, hci1, ...).
  


• set <name> hcitoolParam <name|info>
  (Only applicable in local “bluetooth” mode and not applicable to Daemon device)
  
  Selection of which parameter the hcitool should use to recognize a connected bluetooth device
  Default is <name>


• set <name> disable <0|1>
  If activated, any check is disabled and state is set to disabled.
  


• set <name> prGroup <static|dynamic|...>
  By defining a group, several presence devices can be assigned to a group and monitored.
  <static> predefined.
  <dynamic> predefined.
  You can define your own groups.
  


• set <name> prGroupDisp <condense|verbose>
  <condense> - Shows presence group information in condensed mode. [default]
  <verbose> - Shows presence group information in verbose mode.
  


• child only
  set <name> thresholdAbsence <seconds>


• presentCycle
This attribut may be set to any (ANY) instance in FHEM. It defines the requested cycle time that a reading of the entiy needs to be renewed. The daemon will check the reading's update in its interval. Upon violation of the required timing the reading will toggle to absent.
The Reading to be superviced is defined in attr presentReading and defaults to state.

• presentReading
This attribut may be set to any (ANY) instance in FHEM. It defines the reading name that is supervices by presentCycle.


Readings/events:


General

• state: (absent|present|disabled) - The state of the device, check errors or "disabled" when the disable attribute is enabled
• PRESENCE2: (absent|maybe absent|present|maybe present) - The PRESENCE2 state of the device. The value "maybe absent" only occurs if thresholdAbsence is activated.
• appearCnt: count of entering availale
• lastAppear: timestamp of last appearence
• lastDisappear: timestamp of last disappearence
• thresHldCnt: current thresdold counter. 0 = threshold not active

Daemon specific readings/events:


• daemonMaxScanTime: maximum time the scan job used. Should be less than intervalNormal to avoid skip.
• daemonSkipCnt: counter of skipping the daemon job due to collision.
• pGrp_<group>: counter summary of entites assigned to <group>
• pGrp_<group>_ab: verbose counter summary of entites assigned to <group> : absent entities
• pGrp_<group>_dis: verbose counter summary of entites assigned to <group> : disabled entities
• pGrp_<group>_pres: verbose counter summary of entites assigned to <group> : present entities
• pr_<entity>: status of the PRESENT supervision - see presentCycle
• evt_<entiy>: status of the event supervision - see presentCycle


Bluetooth specific readings/events:

• device_name: $name - The name of the Bluetooth device in case it's present

PROPLANTA

[EN DE]

The module extracts weather data from www.proplanta.de.
The website provides a forecast for 12 days, for the first 7 days in a 3-hours-interval.
This module causes a high CPU load. It is recommended to reduce the number of captured forecast days.
It uses the perl modules HTTP::Request, LWP::UserAgent and HTML::Parse.

Define

define <name> PROPLANTA [City] [CountryCode]
Example:
define wetter PROPLANTA Bern ch
define wetter PROPLANTA Wittingen+(Niedersachsen)
 
• [City]
  Optional. The city must be selectable on www.proplanta.de.
  Please pay attention to the Capital letters in the city names. Spaces within the name are replaced by a + (plus).


• [CountryCode]
  Optional. Possible values: de (default), at, ch, fr, it

The function PROPLANTA_Html and PROPLANTA_Html_Landscape creates a HTML code for a weather forecast for the given days (default is 3).
Example:
define HTMLForecast weblink htmlCode { PROPLANTA_Html("ProPlanta_Wetter"[, days])}



Set


• set <name> update
  The weather data are immediately polled from the website.



Attributes


• forecastDays <4-14>
  Number of days for which the forecast data shall be fetched. Default is 14 days (incl. today).


• INTERVAL <seconds>
  Poll interval for weather data in seconds (default 3600 = 1 hour)


• URL <internet address>
  URL to extract information from. Overwrites the values in the 'define' term.


• readingFnAttributes

Forecast readings


• fc0|1|2|3|...|13_... - forecast values for today|tommorrow|in 2|3|...|13 days
• fc0_...00|03|06|09|12|15|18|21 - forecast values for today at 00|03|06|09|12|15|18|21 o'clock
• fc0_chOfRainDay|Night - chance of rain today by day|night in %
• fc0_chOfRain15 - chance of rain today at 15:00 in %
• fc0_cloud15 - cloud coverage today at 15:00 in %
• fc0_dew - dew formation today (0=none, 1=small, 2=medium, 3=strong)
• fc0_evapor - evaporation today (0=none, 1=small, 2=medium, 3=strong)
• fc0_frost - ground frost today (0=no, 1=yes)
• fc0_gust15 - maximal wind gusts today at 15:00 o'clock in km/h
• fc0_moonRise|Set - moon rise|set today
• fc0_rad - global radiation today
• fc0_rain15 - amount of rainfall today at 15:00 o'clock in mm
• fc0_sun - relative sun shine duration today in % (between sun rise and set)
• fc0_tempMin|Max - minimal|maximal temperature today in °C
• fc0_temp15 - temperatur today at 15:00 o'clock in °C
• fc0_uv - UV-Index today
• fc0_weatherMorning|Day|Evening|Night - weather situation today morning|during day|in the evening|during night
• fc0_weatherDayIcon - icon of weather situation today by day
• fc0_wind15 - wind speed today at 15:00 Uhr in km/h
• fc0_windDir15 - wind direction today at 15:00 Uhr in °
• etc.

PWM

[EN DE]

The PMW module implements temperature regulation for heating systems only capeable of switching on/off. PWM is based on Pulse Width Modulation which means valve position 70% is implemented in switching the device on for 70% and off for 30% in a given timeframe. PWM defines a calculation unit and depents on objects based on PWMR which define the rooms to be heated.

Define
define <name> PWM [<interval>] [<cycletime>] [<minonofftime>] [<maxPulse>] [<maxSwitchOnPerCycle>,<maxSwitchOffPerCycle>] [<roomStayOn>,<roomStayOff>,<stayOnThreshold>] [<overallHeatingSwitch>[,<pulseThreshold>[,<followUpTime>[,<h_regexp_on>[,<delayTimeOn>]]]]]

eg. define fb PWM 60 900 120 1 99,99 0,0,0 pumpactor

Define a calculation object with the following parameters:

• interval
  Calculate the pulses every interval seconds. Default is 60 seconds.
  
• cycletime
  Timeframe to which the pulses refere to. Default is 900 seconds (=15 Minutes). "valve position" of 100% calculates to "on" for this period.
  
• minonofftime
  Default is 120 seconds. Floor heating systems are driven by thermomechanic elements which react very slow. on/off status changes for lower periods are ignored.
  
• maxPulse
  Default is 1, which means that a device can be switched on for the full cylcetime period.
  For energy saving reasons it may be wanted to prevent situations were all rooms are switched on (high energy usage) and afterwards off.
  In this case maxPulse is set to 0.85 (=12:45 minutes) which forces a room with a pulse of 1 (=100%) to be switched off after 12:45 minutes to give another room the chance to be switched on.
  
• maxSwitchOnPerCycle,maxSwitchoffPerCycle
  Defaults are 99 for both values. This means that 99 PWMR object can be switched on or off at the same time.
  To prevent energy usage peaks followend by "no energy consumption" situations set both values to "1".
  This means after the room the the least energy required is switched off the next will be switched off.
  Rooms are switched on or off one after the other (in cycles) and not all at one time.
  Waiting times are honored by a addon to the pulse.
  
  
• roomStayOn,roomStayOff,stayOnThreshold
  Defauts:
  roomStayOn = 0 ... all rooms can be switched off at the same time.
  roomStayOff = 0 ... all rooms can be switched on at the same time.
  stayOnThreshold = 0 ... no impact.
  For energy saving reasons the following may be set: "4,1,0.25". This means:
  The room with the least pulse will be kept off (roomsStayOff=1)
  If the average pulse for the (roomsStayOn=4) rooms with the most heating required is greater than (stayOnThreshold=0.25) then maxRoomStayOn will be kept in state "on", even if the time for the current pulse is reached. If the threshold is not reached (not so much heating required) then all rooms can be switched off at the same time.
  
  
• <overallHeatingSwitch>[,<pulseThreshold>[,<followUpTime>[,<regexp_on>[,<delayTimeOn>]]]]
  Universal switch to controll eg. pumps or the heater itself. It will be set to "off" if no heating is required and otherwise "on".
  pulseThreshold defines a threshold which is applied to reading pulseMax, pulseSum, pulseAvg, pulseAvg2 or pulseAvg3 of the PWM object to decide if heating is required. If (calculated pulse > threshold) then actor is set to "on", otherwise "off".
  If pulseThreshold is set to 0 (or is not defined) then the decision is based on roomsOn. If (roomsOn > 0) then actor is set to "on", otherwise "off".
  followUpTime defines a number of seconds which is used to delay the status change from "on" to "off". This can be used to prevent a toggling switch.
  regexp_on defines a regular expression to be applied to the state of the actor. Default is "on". If state matches the regular expression it is handled as "on", otherwise "off".
  delayTimeOn defines a number of seconds which is used to delay the status change from "off" to "on". This can be used to give the valves time to open before switching..
  The pulse used for comparision is defined by attribute overallHeatingSwitchRef. Default is maxPulse.
  
  

Example:

define fh PWM
which is equal to
define fh PWM 60 900 120 1 99,99 0,0,0
Energy saving definition might be
define fh PWM 60 900 120 0.85 1,1 4,1,0.25



Set
• cycletime
  Temporary change of parameter cycletime.


• interval
  Temporary change of parameter interval.


• recalc
  Cause recalculation that normally appeary every interval seconds.


• maxOffTimeCalculation
  Defines whether parameter maxOffTime for rooms (PWMR objects) is evaluated or not. Possible Values are "on" or "off". Sets attribute maxOffTimeCalculation and internal values c_maxOffTimeCalculation and c_maxOffTimeMode.
  


Get
• status
  Retrieve content of variable STATE.


• timers
  Retrieve values from the readings "timer?_??" from the attached rooms..
  The readings define start and end times for different room temperatures.
  This funktion will retrieve the first start and the last end time. STATE.



Attributes
• disable
  Set to 1 will disable all calculations and STATE will be set to "disabled".
  


• valveProtectIdlePeriod
  Protect Valve by switching on actor for 300 seconds.
  After valveProtectIdlePeriod number of days without switching the valve the actor is set to "on" for 300 seconds. overallHeatingSwitch is not affected.


• overallHeatingSwitchRef
  Defines which reading is used for threshold comparision for OverallHeatingSwitch calculation. Possible values are:
  pulseMax, pulseSum, pulseAvg, pulseAvg2, pulseAvg3, avgPulseRoomsOn
  pulseAvg is an average pulse of all rooms which should be switched to "on".
  pulseAvg2 and pulseAvg3 refer to the 2 or 3 romms with highest pulses.


• overallHeatingSwitchThresholdTemp
  Defines a reading for a temperature and a maximum value that prevents the overallHeatingSwitch from switching to "on".
  Value has the following format: tsensor[:reading[:t_regexp]],maxValue.
  tsensor defines the temperature sensor for the actual temperature.
  reading defines the reading of the temperature sensor. Default is "temperature"
  t_regexp defines a regular expression to be applied to the reading. Default is '(\d[\d\.]+)'.
  if maxValue is reached as a temperature from tsensor then overallHeatingSwitch will not be switch to "on".
  Example: tsensor,44 or tsensor:temperature,44 or tsensor:temperature:(\d+).*,44
  The reading OverallHeatingSwitchTT_Off will be set to 1 if temperature from tsensor prevents overallHeatingSwitch from switching to "on".
  Please be aware that temperatures raising to high will seriously harm your heating system and this parameter should not be used as the only protection feature.
  Using this parameter is on your own risk. Please test your settings very carefully.
  


• maxOffTimeCalculation
  Defines whether parameter maxOffTime for rooms (PWMR objects) is evaluated or not. Possible Values are "on" or "off". Sets internal values c_maxOffTimeCalculation and c_maxOffTimeMode.
  


• maxOffTimeMode
  Defines the strategy for maxOffTime handling if maxOffTimeCalculation is set. Sets internal value c_maxOffTimeMode.
  max: try to activate as many rooms as possible. If one room switches to on and a second waited half of his maxOffTime, the second will be switched on as well.
  1, 2, 3: defines how many rooms can be switched on at the same time.
  

PWMR

[EN DE]

The PMWR module defines rooms to be used for calculation within module PWM. PWM is based on Pulse Width Modulation which means valve position 70% is implemented in switching the device on for 70% and off for 30% in a given timeframe. PWM defines a calculation unit and depents on objects based on PWMR which define the rooms to be heated. PWMR objects calculate a desired temperature for a room based on several rules, define windows, a temperature sensor and an actor to be used to switch on/off heating.

Define
define <name> PWMR <IODev> <factor[,offset]> <tsensor[:reading:[t_regexp]]> <actor>[:<a_regexp_on>] [<window|dummy>[,<window>[:<w_regexp>]] [ <usePID=0> | <usePID=1>:<PFactor>:<IFactor>[,<ILookBackCnt>]:<DFactor>[,<DLookBackCnt>] | <usePID=2>:<PFactor>:<IFactor>:<DFactor>[,<DLookBackCnt>] ]

Define a calculation object with the following parameters:

• IODev
  Reference to an object of TYPE PWM. This object will switch on/off heating.
  
• factor[,offset]
  Pulse for PWM will be calculated as ((delta-temp * factor) ** 2) + offset.
  offset defaults to 0.11
  factor can be used to weight rooms.
  
• tsensor[:reading[:t_regexp]]
  tsensor defines the temperature sensor for the actual room temperature.
  reading defines the reading of the temperature sensor. Default is "temperature"
  t_regexp defines a regular expression to be applied to the reading. Default is '(\d[\d\.]+)'.
  
• actor[:<a_regexp_on>]
  The actor will be set to "on" of "off" to turn on/off heating.
  a_regexp_on defines a regular expression to be applied to the state of the actor. Default is 'on". If state matches the regular expression it is handled as "on", otherwise "off"
  
• <window|dummy>[,<window>[:<w_regexp>]
  window defines several window devices that can prevent heating to be turned on.
  If STATE matches the regular expression then the desired-temp will be decreased to frost-protect temperature.
  'dummy' can be used as a neutral value for window and will be ignored when processing the configuration.
  w_regexp defines a regular expression to be applied to the reading. Default is '.*[Oo]pen.*'.
  
• <usePID=0>
  usePID 0: calculate Pulse based on parameters factor and offset.
  Internals c_factor and c_foffset will reflect the values used for calculatio. Defaults are 1 and 0.11 (if not specified)
  Readings PWMOnTime and PWMPulse will reflect the actual calculated Pulse.
  
• <usePID=1>:<PFactor>:<IFactor>[,<ILookBackCnt>]:<DFactor>[,<DLookBackCnt>]
  PFactor: Konstant for P. Default is 0.8.
  IFactor: Konstant for I. Default is 0.3
  DFactor: Konstant for D. Default is 0.5
  ILookBackCnt: Buffer size to store previous temperatures. For I calculation all values will be used. Default is 5.
  DLookBackCnt: Buffer size to store previous temperatures. For D calculation actual and oldest temperature will be used. Default is 10.
  Internals c_PID_PFactor, c_PID_IFactor, c_PID_ILookBackCnt, c_PID_DFactor, c_PID_DLookBackCnt and c_PID_useit will reflect the above configuration values.
  Readings PID_DVal, PID_IVal, PID_PVal, PID_PWMOnTime and PID_PWMPulse will reflect the actual calculated PID values and Pulse.
  
• <usePID=2>:<PFactor>:<IFactor>:<DFactor>[,<DLookBackCnt>]
  PFactor: Konstant for P. Default is 0.8.
  IFactor: Konstant for I. Default is 0.01
  DFactor: Konstant for D. Default is 0
  DLookBackCnt: Buffer size to store previous temperatures. For D calculation actual and oldest temperature will be used. Default is 10.
  Internals c_PID_PFactor, c_PID_IFactor, c_PID_DFactor, c_PID_DLookBackCnt and c_PID_useit will reflect the above configuration values.
  Readings PID_DVal, PID_IVal, PID_PVal, PID_PWMOnTime and PID_PWMPulse will reflect the actual calculated PID values and Pulse.
  

Example:

define roomKitchen PWMR fh 1,0.11 tempKitchen relaisKitchen
define roomKitchen PWMR fh 1,0.11 tempKitchen relaisKitchen windowKitchen1,windowKitchen2
define roomKitchen PWMR fh 1,0.11 tempKitchen relaisKitchen windowKitchen1,windowKitchen2:.*Open.*
define roomKitchen PWMR fh 1,0.11 tempKitchen relaisKitchen windowKitchen1,windowKitchen2
define roomKitchen PWMR fh 1,0.11 tempKitchen relaisKitchen dummy 0
define roomKitchen PWMR fh 0 tempKitchen relaisKitchen dummy 1:0.8:0.3:0.5
define roomKitchen PWMR fh 0 tempKitchen relaisKitchen dummy 1:0.8:0.3,5:0.5,10
define roomKitchen PWMR fh 0 tempKitchen relaisKitchen dummy 2:0.8:0.01:00
define roomKitchen PWMR fh 0 tempKitchen relaisKitchen dummy 2:0.8:0.01:0.1,10



Set
• factor
  Temporary change of parameter factor.


• actor
  Set the actor state for this room to on or off. This is only a temporary change that will be overwritten by PWM object.


• desired-temp
  If desired-temp is automatically calculated (attribute autoCalcTemp not set or 1) then the desired temperature is set for a defined period.
  Default for this period is 60 minutes, but it can be changed by attribute autoCalcTemp.
  If desired-temp is not automatically calculated (attribute autoCalcTemp is 0) then this will set the actual target temperature.
  Using the commandline a second parameter can also specify the period. Format one of: mm (period in minutes, eg. 120 for two hours), xxh (period in hours, eg. 2h), hh:mm (end time).
  


• manualTempDuration
  Define the period how long desired-temp manually set will be valid. Default is 60 Minutes.
  


• interval
  Temporary change INTERVAL which defines how often desired-temp is calculated in autoCalcMode. Default is 300 seconds (5:00 Minutes).


• frostProtect
  Sets attribute frostProtect to 1 (on) or 0 (off).


Get
• previousTemps
  Get conent of buffers defined by ILookBackCnt and DLookBackCnt.


Attributes
• disable
  PWMR objects with attribute disable set to 1 will be excluded in the calculation loop of the PWM object.


• frostProtect
  Switch on (1) of off (0) frostProtectMode. desired-temp will be set to tempFrostProtect in autoCalcMode.


• autoCalcTemp
  Switch on (1) of off (0) autoCalcMode. desired-temp will be set based on the below temperatures and rules in autoCalcMode.
  Default is on.


• tempDay
  Define day temperature. This will be referenced as "D" in the rules.


• tempNight
  Define night temperature. This will be referenced as "N" in the rules.


• tempCosy
  Define cosy temperature. This will be referenced as "C" in the rules.


• tempEnergy
  Define energy saving temperature. This will be referenced as "E" in the rules.


• tempFrostProtect
  Define temperature for frostProtectMode. See also frostProtect.


• tempRule1 ... tempRule5
  Rule to calculate the desired-temp in autoCalcMode.
  Format is: <weekday>[-<weekday>] <time>,<temperatureSelector>
  weekday is one of Mo,Di,Mi,Do,Fr,Sa,So
  time is in format hh:mm, e.g. 7:00 or 07:00
  temperatureSelector is one of D,N,C,E
  
  Predefined are:
  tempRule1: Mo-Fr 6:00,D 22:00,N
  tempRule2: Sa-So 8:00,D 22:00,N
  This results in tempDay 6:00-22:00 from Monday to Friday and tempNight outside this time window.
  


• desiredTempFrom
  This can be used as an alternative instead of the calculation of desired-temp based on the tempRules - which will happen when autoCalcTemp is set to '1'.
  (Either by removing the attribute autoCalcTemp or explicitly setting it to '1'.).
  If set correctly the desired-temp will be read from a reading of another device.
  Format is <device>[:<reading>[:<regexp>]]
  device defines the reference to the other object.
  reading defines the reading that contains the value for desired-temp. Default is 'desired-temp'.
  regexp defines a regular expression to extract the value used for 'desired-temp'. Default is '(\d[\d\.]+)'. If regexp does not match (e.g. reading is 'off') then tempFrostProtect is used.
  Internals c_desiredTempFrom reflects the actual setting and d_name, d_reading und d_regexpTemp the values used.
  If this attribute is used then state will change from "Calculating" to "From <device>".
  Calculation of desired-temp is (like when using tempRules) based on the interval specified for this device (default is 300 seconds).
  Special values "on" and "off" of Homematic devices are handled as c_tempC (set by attribute tempCosy) and c_tempFrostProtect (set by attribute tempFrostProtect).


• valueFormat
  Defines a map to format values within PWMR.
  The following reading can be formated using syntax of sprinf: temperature
  Example: { "temperature" => "%0.2f" }


• maxOffTime
  Defines a maximum time the room can be set to 'off'. After this period the room is forced to be switched to 'on'. This is to prevent the floor to be cooled out too much if desired-temp is already reached. Ranges of tempRule can be used to specify if this should also happen eg. during the night.
  Format is: <maximum time the room can be off>[,<list of temperatureSelectors which are D,N,C and E>][,<period for "on" state>][,<temperature limit>]
  See also "set maxOffTimeCalculation [on|off]" for the associated PWM object.
  temperature limit: if "current temperature" is greater than "desired temperature" + "temperature limit" then maxOffTime is ignored (not evaluated).
  Examples:
  maxOffTime 4:00
  This room will be forced to "on" for 60 Minutes after 4 Hours being in state "off".
  maxOffTime 4:00,D
  This room will be forced to "on" for 60 Minutes after 4 Hours being in state "off". Only applies is desired temp is currently derived from tempDay.
  maxOffTime 4:00,D,0:30
  This room will be forced to "on" for 30 Minutes after 4 Hours being in state "off". Only applies is desired temp is currently derived from tempDay.
  maxOffTime 4:00,DCE
  This room will be forced to "on" for 60 Minutes after 4 Hours being in state "off". Only applies is desired temp is currently derived from tempDay or tempCosy or tempEnergy (=not tempNight).
  

PW_Circles

[EN DE]

The PW_Circles module is invoked by Plugwise. You need to define a Plugwise-Stick first. See Plugwise.

Define
define <name> PW_Circle <ShortAddress>

<ShortAddress>
specifies the short (last 4 Bytes) of the Circle received by the Plugwise-Stick.




Set
on / off

Turns the circle on or off


on-for-timer / off-for-timer sec

Turns the circle on or off for a given interval


syncTime

Syncronises the internal clock of the Circle with your PC's clock


removeNode

Removes this device from your Plugwise-network


ping

Ping the circle and write the Ping-Runtime to reading "ping" in format "q_in - q_out - pingTime"


status

Gets the current state of this cirle.




Attributes
interval

specifies the polling time for this circle



Example

define Circle_2907CC9 PW_Circle 2907CC9

PW_Scan

[EN DE]

The PW_Scan module is invoked by Plugwise. You need to define a Plugwise-Stick first. See PW_Scan.

Define
define <name> PW_Scan <ShortAddress>

<ShortAddress>
specifies the short (last 4 Bytes) of the PW_Scan received by the Plugwise-Stick.


Example:
define PW_Scan_2907CC9 PW_Scan 2907CC9

PW_Sense

[EN DE]

The PW_Sense module is invoked by Plugwise. You need to define a Plugwise-Stick first. See PW_Sense.

Define
define <name> PW_Sense <ShortAddress>

<ShortAddress>
specifies the short (last 4 Bytes) of the PW_Sense received by the Plugwise-Stick.


Example:
define PW_Sense_2907CC9 PW_Sense 2907CC9

PW_Switch

[EN DE]

The PW_Switch module is invoked by Plugwise. You need to define a Plugwise-Stick first. See PW_Switch.

Define
define <name> PW_Switch <ShortAddress>

<ShortAddress>
specifies the short (last 4 Bytes) of the Circle received by the Plugwise-Stick.


Example:
define PW_Switch_2907CC9 PW_Switch 2907CC9

Set
syncTime

Syncronises the internal clock of the Circle with your PC's clock


removeNode

Removes this device from your Plugwise-network


ping

Ping the circle and write the Ping-Runtime to reading "ping" in format "q_in - q_out - pingTime"

PiXtendV2

[EN DE]

PiXtend is a programmable logic controller (PLC) based on the Raspberry Pi. This FHEM-module allows to access the functions of the PiXtendV2-Board through the FHEM interface. PiXtend offers a variety of digital and analog inputs and outputs which are designed for industry standards and safe connections and thus is ideally suited for home automation. For more information about PiXtend(R) and this FHEM-module, see www.PiXtend.de or www.PiXtend.com.

Define
define <name> PiXtendV2 <optional>

The parameter "optional" is used to determine the hardware model, e.g. S or L. If the parameter is not used a FHEM device for model S is created automatically.

Example:
define pix PiXtendV2    => creates a FHEM device for model S
define pix PiXtendV2 S   => creates a FHEM device for model S
define pix PiXtendV2 L   => creates a FHEM device for model L


Set
Commands to configure the basic settings of the PiXtend start with an "_".
If a command supports multiple channels the "#"-sign has to be replaced with the channel number.
All Set-commands are case insensitive to guarantee an easy use.
For more information see the manuel for PiXtendV2 in the download section of our homepage.

Example:
set pix relayOut0 on
set pix Relayout0 On
set pix rElAyoUT0 oFf




• _GPIO#Ctrl [input,output,DHT11,DHT22]
  With this setting the GPIO can be configured as [input], [output] or as [DHT11] or [DHT22] as well, if a DHT sensor is connected to this GPIO. If a DHT is selected and connected, the GPIO can't simultaniously be used as a normal GPIO but the temperatur and humidity is read automatically.
  
  
• _GPIOPullupsEnable [yes,no]
  This setting enables [yes] or disables [no] the possibility to set the internal pullup resistors via GPIOOut setting for all GPIOs.
  
  
• _JumperSettingAI# [5V,10V]
  This setting affects the calculation of the voltage on the analog inputs and refers to the actual setting of the physical jumper on the PiXtend-Board [5V,10V]. The default value is [10V] if no jumper is used.
  
  
• _StateLEDDisable [yes,no]
  This setting disables [yes] or enables [no] the state LED on the PiXtend. If the LED is disabled it won't light up in case of an error.
  
  
• _WatchdogEnable [disable,125ms,1s,8s]
  This setting allows to configure the watchdog timer. If the watchdog is configured, the PiXtend will go to safe state if no valid data transfer has occured within the selected timeout and thus can't be accessed anymore without a reset.
  
  
• AnalogOut# []
  Sets the analog output to the selected voltage. The value can be a voltage between 0 V and 10 V or a raw value between 0 and 1023. To set the value to a voltage the value has to include a "." even if it is an even number.
  
  Example:
  set pix analogout0 2.5   => sets analog output 0 to 2.5 V
  set pix analogout0 4.0   => sets analog output 0 to 4 V
  set pix analogout0 223   => sets analog output 0 to 10*(233/1024) = 1.09 V
  
  
  
• DigitalDebounce# [0-255]
  Allows to debounce the digital inputs. A setting always affects two channels. So DigitalDebounce01 affects DigitalIn0 and DigitalIn1. The resulting delay is calculated by (selected value)*(100 ms). The selected value can be any number between 0 and 255. Debouncing can be useful if a switch or button is connected to this input.
  
  Example:
  set pix digitaldebounce01 20   => debounces DigitalIn0 and DigitalIn1 over (20*100ms) = 2s
  
  
  
• DigitalOut# [on,off,toggle]
  Set the digital output HIGH [on] or LOW [off] or [toggle]s it.
  
  
• GPIODebounce# [0-255]
  Allows to debounce the GPIO inputs. A setting always affects two channels. So GPIODebounce01 affects GPIOIn0 and GPIOIn1. The resulting delay is calculated by (selected value)*(100 ms). The selected value can be any number between 0 and 255. Debouncing can be useful if a switch or button is connected to this input.
  
  Example:
  set pix gpiodebounce23 33   => debounces GPIOIn2 and GPIOIn3 over (33*100ms) = 3.3s
  
  
  
• GPIOOut# [on,off,toggle]
  Set the GPIO to HIGH [on] or LOW [off] or [toggle]s it, if it is configured as an output. If it is configured as an input, this command can enable [on] or disable [off] or [toggle] the internal pullup resistor for that GPIO, but therefore pullups have to be enabled globally via _GPIOPullupsEnable.
  
  
• PWM
  The PiXtendV2 supports various PWM-Modes, which can be configured with this settings. For example a servo-mode to control servo-motors, a frequency-mode or a duty-cycle-mode are supported. For more information see the manuel for PiXtendV2 in the download section of our homepage.
  
  PWM#Ctrl0 needs a value between 0 and 255
  PWM#Ctrl1 needs a value between 0 and 65535 (or a value between 0 and 255, see exception for model -S-)
  PWM#A/B needs a value between 0 and 65535 (or a value between 0 and 255, see exception for model -S-)
  
  
• RelayOut# [on,off,toggle]
  Set the relay to HIGH [on] or LOW [off] or [toggle]s it.
  
  
• Reset
  Resets the controller on the PiXtend, for example if it is in safe state and allows to access it again.
  
  
• RetainCopy [on,off]
  If RetainCopy is enabled [on] the RetainDataOut that is written to the PiXtend will be received in RetainDataIn again. This can be useful in some situations to see which data was send to the PiXtend. If it is disabled [off] the last stored data will be received.
  
  
• RetainDataOut [0-(RetainSize-1)] [0-255]
  The PiXtendV2 supports the storage of retain data. If enabled, this data is stored in case of a power failure or if it is triggered by a watchdog timeout or the safe state command. The retain data is organized in bytes and each byte can be written individually with a value between 0 and 255.
  As first parameter the command needs the byte index which is between 0 and the (RetainSize-1). The RetainSize is shown in the "Internals". As the second parameter a value is expected which should be stored.
  
  Example:
  set pix retaindataout 0 34    => stores 34 in retain-data-byte 0
  set pix retaindataout 30 222   => stores 222 in retain-data-byte 30
  
  
  
• RetainEnable [on,off]
  The function of storing retain data on the PiXtend has to be enabled [on], otherwise no data is stored [off]. The memory in which the data is stored supports 10.000 write-cycles. So the storage of retain data should only be used if it is really necessary.
  
  
• SafeState
  This setting allows to force the PiXtend to enter the safe state . If retain storage is enabled the data will be stored. In safe state the PiXtend won't communicate with FHEM and can't be configured anymore. To restart the PiXtend a reset has to be done.
  
  

Get
If a command supports multiple channels the "#"-sign has to be replaced with the channel number.
All Get-commands are case insensitive to guarantee an easy use.
For more information see the manuel for PiXtendV2 in the download section of our homepage. The values can be returned as a string where the actual value is inside squared brackets or as raw values. To change the returned value the attribute "PiXtend_GetFormat" has to be set.


• AnalogIn#
  Returns the Value of the selected analog input. The result depends on the selected _JumperSettingAI# and the actual physical jumper position on the board, as well as the kind of measurement. For example AnalogIn4 and AnalogIn5 on model -L- are used to measure a current instead of a voltage.
  
  
• DigitalIn#
  Returns the state on (HIGH) or off (LOW) of the digital input.
  
  
• GPIOIn#
  Returns the state on (HIGH) or off (LOW) of the GPIO, independant of its configuration (input, output, ..).
  
  
• RetainDataIn [0-(RetainSize-1)]
  Returns the value of the selected RetainDataIn-byte.
  
  
• Sensor# [temperature,humidity]
  If a DHT-Sensor is connected to the corresponding GPIO and the _GPIO#Ctrl is set to DHT11 or DHT22 the temperature and humidity are measured and can be read.
  
  Example:
  set pix _GPIO0Ctrl DHT11
get pix Sensor0 temperature
  
  
  
• SysState
  Returns the system state [defined, active, error] of the FHEM module.
  
  
• UCState
  Returns the state of the PiXtend. If it is 1 everything is fine. If it is greater than 1 an error occured or is present and the PiXtend can't be configured. For more information see the manuel for PiXtendV2 in the download section of our homepage.
  
  
• UCWarnings
  Returns a value that represents the PiXtend warnings. For more information see the manuel for PiXtendV2 in the download section of our homepage.
  
  
• Version
  Returns the FHEM-module version and the microcontroller version [Model-Hardware-Firmware].
  
  

Readings
The FHEM-module for PiXtendV2 supports multiple readings from which most of them trigger an event when they have changed. The meaning of the readings is similar to the Get-commands.


• AnalogIn#
  Shows the result of the measurment on the analog inputs in V or mA.
  
  
• DigitalIn#
  Shows the state on (HIGH) or off (LOW) of the digital inputs.
  
  
• Firmware
  Shows the firmware version.
  
  
• GPIOIn#
  Shows the state on (HIGH) or off (LOW) of the GPIOs, independant of their configuration (input, output, ..).
  
  
• Hardware
  Shows the hardware version.
  
  
• Model
  Shows the model.
  
  
• RetainDataIn
  Shows the values of the RetainDataIn. The values of RetainDataIn are combined in one row, whereby the most left value represents Byte0 / RetainDataIn0. Each value is seperated by an " " and thus can be parsed very easy in perl:
  
  Example:
  my ($str) = ReadingsVal(pix, "RetainDataIn", "?")
if($str ne "?"){
 my @val = split(/ /, $str);   => $val[0] contains Byte0, $val[1] Byte1, ...
   ...
}
  
  
  
• Sensor#T/H
  Shows the temperature (T) in °C and the humidity (H) in % of the sensor that is connected to the corresponding GPIO.
  
  
• UCState
  Shows the state of the PiXtend. If it is 1 everything is fine. If it is greater than 1 an error occured or is present and the PiXtend can't be configured. For more information see the manuel for PiXtendV2 in the download section of our homepage.
  
  
• UCWarnings
  Shows a value that represents the PiXtend warnings. For more information see the manuel for PiXtendV2 in the download section of our homepage.
  
  

Attributes
The attribute name is case-sensitive.


• PiXtend_GetFormat [text,value]
  Changes the style in which the values of the Get commands are returned. They can be returned as a message [text] or as a raw [value]. Default is the presentation as a message.
  
  
• PiXtend_Parameter
  With this attribute the base configuration (Set commands with a leading "_") can be saved as an attribute. Attributes are stored in the config file. Single commands are seperated with a space " " and each value is seperated by a ":".
  
  Example:
  attr pix PiXtend_Parameter _gpio0ctrl:dht11 _gpio3ctrl:dht22
  
  
  

Plugwise

[EN DE]

This module is for the Plugwise-System.
Note: this module requires the Device::SerialPort or Win32::SerialPort module if the devices is connected via USB or a serial port. Also needed: digest:CRC You can install these modules using CPAN.

Define
define <name> Plugwise <device>


<device> specifies the serial port to communicate with the Plugwise-Stick. Normally on Linux the device will be named /dev/ttyUSBx, where x is a number. For example /dev/ttyUSB0. Please note that the Plugwise-Stick normally operates at 115200 baud. You may specify the baudrate used after the @ char.

Example:
define myPlugwise Plugwise /dev/ttyPlugwise@115200

Set

Scan_Circles
Initiates a scan for new devices and defines them.


syncTime
Syncs all reachable devices to the system-time.


reOpen
Closes and reopens the serial-Port. (useful in case of to many Errors)

Attributes

circlecount

Max. Number of Circles to be found by the Scan-Command


interval

standard polling-interval for new Circles


autosync

Sends every n seconds a SyncTime to each device


WattFormat

A string representing the format of the power-readings. If not defined, it defaults to %0.f


showCom

Writes the complete communication matching a RegEx into the reading "communication" (can be viewed in EventMonitor or used with a FileLog)

PostMe

[EN DE]

FHEM module to set up a system of sticky notes, similar to Post-Its™

Define

define <postit> PostMe
Defines the PostMe system, <postit> is an arbitrary name for the system.

Usage

See German Wiki page
An arbitrary number of lists may be added to the system with the create command.
List items may consist of one or more words, and are added/removed by the add and remove command, but no separator characters are allowed in one item
Attention: A comma "," is the default separator for list items, see attributes below.


Meta data for items (=annotations)may be included in the items by using "[" and "]"; characters, e.g.
set <postit> add <name> <item> [<attribute1>="<data1>" ...
These attribute-value pairs may be added, modified and removed with the modify command.

Special annotations will be evaluated further, either on creation or manually by executing the commands
get <postit> special <name> resp. get <postit> allspecial

• The attribute at="<timespec/datespec>", when given a timespec/datespec value, will result in a single or multiple reminding messages for this item. The syntax for this timespec/datespec value is
  (<HH:MM>|<HH:MM:SS>|<YYYY-MM-DD>T<HH:MM:SS>)[-<HH:MM>[P<number>]]
  The first part is the time/date specification when the item is due.
  The second optional part beginning with a "-"-sign denotes how much time befor this date you want to be alerted.
  The third optional part beginning with a "P" character allows to specify a <number> of periodic reminders, the period given by the second part.
  Processing this attribute means, that several at devices will be set up in the room hidden that are triggered when at the specified times. See documentation in Wiki for examples.
• The attribute notify="<eventspec>", when given an eventspec value, will result in a single or multiple reminding messages for this item.
  Processing this attribute means, that a notify device will be set up in the room hidden that is triggered when the event is detected.
The sticky notes may be integrated into any Web page by simply embedding the following tags
• <embed src="/fhem/PostMe_widget?type=pins&postit=<postit>"/>
  to produce an interactive list of all PostMe names with pins from system <postit>.
• <embed src="/fhem/PostMe_widget?type=pin&postit=<postit>&name=<name>"/>
  to produce an interactive entry for PostMe <name>from system <postit>

The module provides interface routines that may be called from your own Perl programs, see documentation in the Wiki.


Set

• set <postit> create <name>
  creates a sticky note named <name>
• set <postit> rename <name> <newname>
  renames the sticky note named <name> as <newname>
• set <postit> delete <name>
  deletes the sticky note named <name>
• set <postit> add <name> <item>
  adds to the sticky note named <name> an item <item>
• set <postit> modify <name> <item> <attribute> <data>
  adds/modifies/removes and attribute-value-pair <attribute>="<data>" to the item <item> on the sticky note named <name>
  adding, if this attribute is not yet present; modification, if it is present - <data> will then be overwritten; removal, if no <data> is given
• set <postit> remove <name> <item>
set <postit> remove <name> item<number>
  removes from the sticky note named <name> an item <item> or the one numbered <number> (starting at 0)
• set <postit> clear <name>
  clears the sticky note named <name> from all items

Get

• get <postit> list <name>
  Show the sticky note named <name> and its content
• get <postit> special <name>
  Process the special annotations (see above) of the sticky note named <name>
• get <postit> mail <name>
  Send the sticky note named <name> and its content via eMail to a predefined recipient (e.g. sticky note <postme01Name> is sent to <postme01MailRec>).
  The mailing subroutine is called with three parameters for recipient, subject and text.
• get <postit> message <name>
  Send the sticky note named <name> and its content via instant messenger to a predefined recipient (e.g. sticky note <postme01Name> is sent to <postme01MsgRec>).
  The messenger subroutine is called with three parameters for recipient, subject and text.
• get <postit> TTS <name>
  Speak the sticky note named <name> and its content. The TTS subroutine is called with one parameter text.
• get <postit> JSON <name>
  Return the sticky note named <name> in JSON format
• get <postit> all
  Show all sticky notes and their content
• get <postit> allspecial
  Process the special annotations (see above) of all sticky notes
• get <postit> version
  Display the version of the module

Attributes

• attr <postit> postmeStd <name1,name2,...>
  Comma separated list of standard sticky notes that will be created on device start.
• attr <postit> postmeClick 1|0 (default)
  If 0, embedded sticky notes will pop up on mouseover-events and vanish on mouseout-events (default).
  If 1, embedded sticky notes will pop up on click events and vanish after closing the note
• attr <postit> postmeIcon <string>
  Icon for display of a sticky note
• attr <postit> postmeStyle SVG|HTML|jQuery (default)
  If jQuery, embedded sticky notes will produce jQuery code (default)
  If HTML, embedded sticky notes will produce HTML code
  If SVG, embedded sticky notes will produce SVG code
• attr <postit> listseparator <character>
  Character used to separate list items (default ',')
Note, that in the parameters sent to the following functions, ":" serves as separator between list name and items, and "," serves as separator between items. They may be exchanged with simple regular expression operations.
• attr <postit> postmeMailFun <string>
  Function name for the eMail function. This subroutine is called with three parameters for recipient, subject and text.
• attr <postit> postmeMailRec(01|02|...) <string> recipient addresses for the above eMail function (per PostMe).
• attr <postit> postmeMsgFun <string>
  Function name for the instant messenger function. This subroutine is called with three parameters for recipient, subject and text.
• attr <postit> postmeMsgRec(01|02|...) <string> recipient addresses for the above instant messenger function (per PostMe).
• attr <postit> postmeTTSFun <string>
  Function name for the text-to-speech function. This subroutine is called with two parameters, the device name and the composite text.
• attr <postit> postmeTTSDev(01|02|...) <string> device name for the above TTS function.
• Standard attributes alias, comment, event-on-update-reading, event-on-change-reading, room, eventMap, loglevel, webCmd

PrecipitationSensor

[EN DE]

For more information about the PrecipitationSensor see here: FHEM thread

Define
define <name> PrecipitationSensor <device>
<device> specifies the network device
Normally this is the IP-address and the port in the form ip:port
Example: 192.168.1.100:81


Set
• raw <data>
  send <data> to the PrecipitationSensor.


• connect
  tries to (re-)connect to the PrecipitationSensor. It does not reset the PrecipitationSensor but only try to get a connection to it.


• reboot
  Reboots the PrecipitationSensor. Works only if we are connected (state is opened or initialized)


• calibrate
  Calibrates and saves the threshold levels of the PrecipitationSensor. Works only if we are connected (state is opened or initialized)
  How to perform a calibration:
  1.) Place the sensor in a location with absolutely no motion within a radius of at least 3 meters
  2.) Set the "Publish interval" on the web interface to 60 seconds
  3.) Wait for at least 120 seconds before calling the "calibrate" command
  4.) The calibrated threshold levels "GroupMagThresh" will be updated after the next Publish interval cycle


• restPreciAmount
  Resets the amount of precipitation. Works only if we are connected (state is opened or initialized)


• savesettings
  Saves the changes to flash. Works only if we are connected (state is opened or initialized)


• flash
  This provides a way to flash it directly from FHEM.


Get
---

Attributes
• initCommands
  Space separated list of commands to send for initialization.


• timeout
  format: <timeout>
  Asks the PrecipitationSensor every timeout seconds if it is still alive. If there is no response it reconnects to the PrecipitationSensor.
  


• disable
  if disabled, it does not try to connect

PushNotifier

[EN DE]

PushNotifier is a service to receive instant push notifications on your phone or tablet from a variety of sources.
You need an account to use this module.
For further information about the service see FhemWiki PushNotifier.

Discuss the module here.


Define
define <name> PushNotifier <apiToken> <appName> <user> <password> <deviceID>

You have to create an account to get the apiToken.
And you have to create an application to get the appToken.

Example:
define PushNotifier1 PushNotifier 01234 appname user password 012

Set
set <PushNotifier_device> message

Examples:
set PushNotifier1 message This is a text.

Linebreak:
set PushNotifier1 message This is a text._New Line.


Generated events:
N/A

Pushbullet

[EN DE]

Pushbullet is a service to send instant push notifications to different devices. There are apps for iPhone, Android, Windows (Beta), Mac OS X and plugins for Chrome Firefox and Safari.
For further information about the service see pushbullet.com.

Discuss the module here.


Define
define <name> Pushbullet <accessToken>

Note:

• JSON has to be installed on the FHEM host.
• Register on pushbullet.com to get your accessToken.

Set
• clear
  clear device readings
• contactAdd name | email
  adds a contact. Spaces in name are allowed
• deviceDelete deviceName
  deletes a device
• deviceRename deviceName | newDeviceName
  renames a device
• link [| title | device]
  sends a link with optional title and device. If no device is given, push goes to all your devices.
• list item1[, item2, item3, ... | title | device]
  sends a list with one or more items, optional title and device. If no device is given, push goes to all your devices.
• message [| title | device]
  sends a push notification with optional title and device. If no device is given, push goes to all your devices.

Examples:

set Pushbullet message This is a message.
sends a push notification with message "This is a message" without a title to all your devices.

set Pushbullet message This is a message | A title
sends a push notification with message "This is a message" and title "A title" to all your devices.

set Pushbullet message This is a message | A title | iPhone
sends a push notification with message "This is a message" and title "A title" to Device iPhone.

set Pushbullet message This is a message | A title | Max Mustermann
sends a push notification with message "This is a message" and title "A title" to your contact Max Mustermann.


Note:
Spaces before and after | are not needed.

Get
• devices
  reads your device list (devices + contacts) and set device readings

Attributes
• defaultDevice
  default device for pushmessages
• defaultTitle
  default title for pushmessages. If it is undefined the defaultTitle will be FHEM

Pushover

[EN DE]

Pushover is a service to receive instant push notifications on your phone or tablet from a variety of sources.
You need an account to use this module.
For further information about the service see pushover.net.

Installation of Perl module IO::Socket::SSL is mandatory to use this module (i.e. via 'cpan -i IO::Socket::SSL').
It is recommended to install Perl-JSON to make use of advanced functions like supplementary URLs.

Discuss the module here.


Define
define <name> Pushover <token> <user> [<infix>]

You have to create an account to get the user key.
And you have to create an application to get the API token.

Attribute infix is optional to define FHEMWEB uri name for Pushover API callback function.
Callback URL may be set using attribute callbackUrl (see below).
Note: A uri name can only be used once within each FHEM instance!

Example:
define Pushover1 Pushover 01234 56789
define Pushover1 Pushover 01234 56789 pushCallback1

Set
msg
set <Pushover_device> msg <text> [<option1>=<value> <option2>="<value with space in it>" ...]

The following options may be used to adjust message content and delivery behavior:

message    - type: text - Your message text. Using this option takes precedence; non-option text content will be discarded.
device     - type: text - Your user's device name to send the message directly to that device, rather than all of the user's devices (multiple devices may be separated by a comma). May also be set to a specific User or Group Key. To address a specific device for a specific User/Group, use User/Group Key first and add device name separated by colon.
title      - type: text - Your message's title, otherwise your Pushover API app's name is used.
action     - type: text - Either a FHEM command to run when user taps link or a supplementary URL to show with your message.
url_title  - type: text - A title for your FHEM command or supplementary URL, otherwise just the URL is shown.
priority   - type: integer - Send as -2 to generate no notification/alert, -1 to always send as a quiet notification, 1 to display as high-priority and bypass the user's quiet hours, or 2 to also require confirmation from the user.
retry      - type: integer - Mandatory in combination with message priority >= 2.
expire     - type: integer - Mandatory in combination with message priority >= 2.
cancel_id  - type: text - Custom ID to immediate expire messages with priority >=2 and disable reoccuring notification.
timestamp  - type: integer - A Unix timestamp of your message's date and time to display to the user, rather than the time your message is received by the Pushover servers. Takes precendence over attribute timestamp=1.
sound      - type: text - The name of one of the sounds supported by device clients to override the user's default sound choice.
attachment      - type: text - Path to an image file that should be attached to the message. The base path is relative to the FHEM directory and may be overwritten using the storagePath attribute.

Examples:
set Pushover1 msg My first Pushover message.
set Pushover1 msg My second Pushover message.\nThis time with two lines.
set Pushover1 msg "Another Pushover message in double quotes."
set Pushover1 msg 'Another Pushover message in single quotes.'
set Pushover1 msg message="Pushover message using explicit option for text content." This part of the text will be ignored.
set Pushover1 msg This is a message with a title. title="This is a subject"
set Pushover1 msg title="This is a subject, too!" This is another message with a title set at the beginning of the command.
set Pushover1 msg This message has an attachment! attachment="demolog/pictures/p1.jpg"
set Pushover1 msg title=Emergency priority=2 retry=30 expire=3600 Security issue in living room.
set Pushover1 msg title=Link Have a look to this website: url_title="Open" action="http://fhem.de/" expire=3600
set Pushover1 msg title=Hint expire=3600 This is a reminder to do something. Action will expire in 1h. url_title="Click here for action" action="set device something"
set Pushover1 msg title=Emergency priority=2 retry=30 expire=3600 Security issue in living room. sound=siren url_title="Click here for action" action="set device something"






msgCancel
set <Pushover_device> msgCancel <ID>

Prematurely stopps reoccuring confirmation request for messages with priority >= 2.

Example:
set Pushover1 msg title=Emergency priority=2 retry=30 expire=3600 Security Alarm in Living room. sound=siren cancel_id=SecurityAlarm
set Pushover1 msgCancel SecurityAlarm



msg (deprecated format)
set <Pushover_device> msg [title] <msg> [<device> <priority> <sound> [<retry> <expire> [<url_title> <action>]]]

Examples:
set Pushover1 msg 'This is a text.'
set Pushover1 msg 'Title' 'This is a text.'
set Pushover1 msg 'Title' 'This is a text.' '' 0 ''
set Pushover1 msg 'Emergency' 'Security issue in living room.' '' 2 'siren' 30 3600
set Pushover1 msg 'Hint' 'This is a reminder to do something' '' 0 '' 0 3600 'Click here for action' 'set device something'
set Pushover1 msg 'Emergency' 'Security issue in living room.' '' 2 'siren' 30 3600 'Click here for action' 'set device something'


Notes:
• For the first and the second example the corresponding default attributes for the missing arguments must be defined for the device (see attributes section)
• If device is empty, the message will be sent to all devices.
• If device has a User or Group Key, the message will be sent to this recipient instead. Should you wish to address a specific device here, add it at the end separated by colon.
• If sound is empty, the default setting in the app will be used.
• If priority is higher or equal 2, retry and expire must be defined.



glance
set <Pushover_device> glance [<text>] [<option1>=<value> <option2>="<value with space in it>" ...]

Update Pushover's glances on Apple Watch.
The following options may be used to adjust message content and delivery behavior:

title    - type: text(100 characters) - A description of the data being shown, such as "Widgets Sold".
text     - type: text(100 characters) - The main line of data, used on most screens. Using this option takes precedence; non-option text content will be discarded. If you want your text to be interpreted as HTML by the Pushover client app, add the prefix 'html:' before the actual text (unless you already use HTML tags in it where it is automatically detected).
subtext  - type: text(100 characters) - A second line of data.
count    - type: integer(may be negative) - Shown on smaller screens; useful for simple counts.
percent  - type: integer(0-100) - Shown on some screens as a progress bar/circle.
device   - type: text - Your user's device name to send the message directly to that device, rather than all of the user's devices (multiple devices may be separated by a comma). May also be set to a specific User or Group Key. To address a specific device for a specific User/Group, use User/Group Key first and add device name separated by colon.



Get
N/A

Attributes
• do_not_notify
• disabledForIntervals
• readingFnAttributes
• callbackUrl
  Set the callback URL to be used to acknowledge messages with emergency priority or supplementary URLs.
• timestamp
  Send the unix timestamp with each message.
• title
  Will be used as title if title is not specified as an argument.
• device
  Will be used for the device name if device is not specified as an argument. If left blank, the message will be sent to all devices.
• priority
  Will be used as priority value if priority is not specified as an argument. Valid values are -1 = silent / 0 = normal priority / 1 = high priority
• expire
  When message priority is 2, this default value will be used for expire when not provided in the message. Needs to be 30 or higher.
• retry
  When message priority is 2, this default value will be used for retry when not provided in the message.
• sound
  Will be used as the default sound if sound argument is missing. If left blank the adjusted sound of the app will be used.
• storagePath
  Will be used as the default path when sending attachments, otherwise global attribute modpath will be used.

Generated events:
N/A

Pushsafer

[EN DE]

Pushsafer is a web service to receive instant push notifications on your iOS, Android or Windows 10 Phone or Desktop device from a variety of sources.
You need a Pushsafer account to use this module.
For further information about the service see pushsafer.com.

This module is only capable to send messages via Pushsafer.

Define
define <name> Pushsafer <key>

The parameter <key> must be a alphanumeric string. This can be a regular private key (20 digits) from your Pushsafer account or an E-Mail alias key (15 digits) which needs to be setup in your account.

Example:
define PushsaferAccount Pushsafer A1b2c3D4E5F6g7h8i9J0

Set
set <name> message <text> [<option1>=<value> <option2>=<value> ...]

Currently only the message command is available to sent a message.

So the very basic use case is to send a simple text message like the following example:

set PushsaferAccount message "My first Pushsafer message."

To send a multiline message, use the placeholder "\n" to indicate a newline:

set PushsaferAccount message "My second Pushsafer message.\nThis time with two lines."

Optional Modifiers

It is possible to customize a message with special options that can be given in the message command after the message text. Several options can be combined together. The possible options are:

title     - short: t  - type: text - A special title for the message text.
device    - short: d  - type: text - The device ID as number, to send the message to a specific device, or "gs" + group ID to send to a device group (e.g. "gs23" for group id 23). By default the message will be send to all registered devices.
sound     - short: s  - type: number - The ID of a specific sound to play on the target device upon reception (see Pushsafer.com for a complete list of values and their meaning).
icon      - short: i  - type: number - The ID of a specific icon to show on the target device for this text (see Pushsafer.com for a complete list of values and their meaning).
vibration - short: v  - type: number - The number of times the device should vibrate upon reception (maximum: 3 times; iOS/Android only). If not set, the default behavior of the device is used.
url       - short: u  - type: text - A URL that should be included in the message. This can be regular http:// URL's but also specific app schemas. See Pushsafer.com for a complete list of supported URL schemas.
urlText   - short: ut - type: text - A text that should be used to display a URL from the "url" option.
key       - short: k  - type: text - Overrides the private key given in the define statement. Also an alias key can be used.
ttl       - short: l  - type: number - Defines a "time-to-live" given in minutes after the message will be deleted on the target device(s). Possible range is between 1 - 43200 minutes (30 days).
picture   - short: p  - type: text - Attach a image to the message. This can be a file path located in your filesystem (e.g. picture=/home/user/picture.jpg) or the name of a IPCAM instance (like picture=IPCAM:<name>) to send the last snapshot image (e.g. picture=IPCAM:IpCam_Front_House). The supported image formats are JPG, PNG and GIF.
picture2  - short: p2 - type: text - same syntax as for option "picture"
picture3  - short: p3 - type: text - same syntax as for option "picture"

Examples:


set PushsaferAccount message "This is a message with a title." title="Super important"
set PushsaferAccount message "Get down here\nWe're waiting" title="Lunch is ready" device=100
set PushsaferAccount message "Server is down" sound=25 icon=5 vibration=3
set PushsaferAccount message "Look at my photos" url="http://www.foo.com/myphotos" urlText="Summer Vacation"

It is also possible to use the short-term versions of options:

set PushsaferAccount message "This is a message with a title." t="Super important"
set PushsaferAccount message "Get down here\nWe're waiting" t="Lunch is ready" d=100
set PushsaferAccount message "Server is down" s=25 i=5 v=3
set PushsaferAccount message "Look at my photos" u="http://www.foo.com/myphotos" ut="Summer Vacation"




Get
N/A

Attributes
• do_not_notify
• disabledForIntervals
• readingFnAttributes



Generated Readings/Events:

• lastSuccess - The last successful status message received by the Pushsafer server
• lastError - The last errur message received by the Pushsafer server
• availableMessages-<device ID>-<device name> - The remaining messages that can be send to this device

PylonLowVoltage

[EN DE]

Module for integration of low voltage batteries with battery management system (BMS) of the manufacturer Pylontech via RS485/Ethernet gateway. Communication to the RS485 gateway takes place exclusively via an Ethernet connection.
The module has been successfully used so far with Pylontech batteries of the following types:

• US2000
• US2000B Plus
• US2000C
• US2000 Plus
• US3000
• US3000C
• US5000

The following devices have been successfully used as RS485 Ethernet gateways to date:

• USR-TCP232-304 from the manufacturer USRiot
• Waveshare RS485 to Ethernet Converter

In principle, any other RS485/Ethernet gateway should also be compatible.

Requirements

This module requires the Perl modules:

• IO::Socket::INET (apt-get install libio-socket-multicast-perl)
• IO::Socket::Timeout (Installation e.g. via the CPAN shell or the FHEM Installer module)

The data format must be set on the RS485 gateway as follows:

Start Bit	- 1 Bit
Data Bit	- 8 Bit
Stop Bit	- 1 Bit
Parity	- without Parity

Example configuration of a Waveshare RS485 to Ethernet converter

The converter's web interface offers several pages with settings. The relevant settings are shown below as an example. The assignment of a fixed IP address is assumed in advance.

Serial port settings
- Baud Rate	: according to the battery setting
- Data Size	: 8 Bit
- Parity	: None
- Stop Bits	: 1
- Local Port Number	: freely selected
- Work Mode	: TCP Server
- Reset	: not set
- Link	: set
- Index	: not set
- Similar RCF2217	: set
Settings Expand Function
- Heartbeat Packet Type	: None
- Register Packet Type	: None
- Short Connection	: not set
- TCP Server-kick off old connection	: set
- Buffer Data before Connected	: set
- UART Set Parameter	: not set

Limitations
The module currently supports a maximum of 16 batteries (1 master + 15 slaves) in up to 7 groups.
The number of groups and batteries that can be realized depends on the products used. Please refer to the manufacturer's instructions.

Definition

define <name> PylonLowVoltage <hostname/ip>:<port> [<bataddress>]

Example:
define Pylone1 PylonLowVoltage 192.168.2.86:9000 1 group=0


• hostname/ip:
  Host name or IP address of the RS485/Ethernet gateway
• port:
  Port number of the port configured in the RS485/Ethernet gateway
• bataddress:
  Device address of the Pylontech battery. Several Pylontech batteries can be connected via a Pylontech-specific Link connection. The permissible number can be found in the respective Pylontech documentation.
  The master battery in the network (with open link port 0 or to which the RS485 connection is connected) has the address 1, the next battery then has address 2 and so on. If no device address is specified, address 1 is used.
• group:
  Optional group number of the battery stack. If group=0 or is not specified, the default configuration “Single Group” is used. The group number can be 0 to 7.

Mode of operation

Depending on the setting of the "Interval" attribute, the module cyclically reads values provided by the battery management system via the RS485 interface.

Get

• data
  The data query of the battery management system is executed. The timer of the cyclic query is reinitialized according to the set value of the "interval" attribute.
  

Attributes

• disable 0|1
  Enables/disables the device definition.


• interval <seconds>
  Interval of the data request from the battery in seconds. If "interval" is explicitly set to the value "0", there is no automatic data request.
  (default: 30)


• timeout <seconds>
  Timeout for establishing the connection to the RS485 gateway.
  (default: 0.5)
  
  Note: If a timeout >= 1 second is set, the module switches internally to the use of a parallel process (BlockingCall) so that write or read delays on the RS485 interface do not lead to blocking states in FHEM.


• userBatterytype
  The automatically determined battery type (Reading batteryType) is replaced by the specified string.


• waitTimeBetweenRS485Cmd <Sekunden>
  Waiting time between the execution of RS485 commands in seconds.
  This parameter only has an effect if the “timeout” attribute is set to a value >= 1.
  (default: 0.1)

Readings

• averageCellVolt
  Average cell voltage (V)
• bmsTemperature
  Temperature (°C) of the battery management system
• cellTemperature_0104
  Temperature (°C) of cell packs 1 to 4
• cellTemperature_0508
  Temperature (°C) of cell packs 5 to 8
• cellTemperature_0912
  Temperature (°C) of the cell packs 9 to 12
• cellTemperature_1315
  Temperature (°C) of the cell packs 13 to 15
• cellTemperature_Pos_XX
  Temperature (°C) of position XX (not further specified)
• cellVoltage_XX
  Cell voltage (V) of the cell pack XX. In the battery module "packCellcount" cell packs are connected in series. Each cell pack consists of single cells connected in parallel.
• chargeCurrentLimit
  current limit value for the charging current (A)
• chargeEnable
  current flag loading allowed
• chargeFullRequest
  current flag charge battery module fully (from the mains if necessary)
• chargeImmediatelySOCXX
  current flag charge battery module immediately (05: SOC limit 5-9%, 09: SOC limit 9-13%)
• chargeVoltageLimit
  current charge voltage limit (V) of the battery module
• dischargeCurrentLimit
  current limit value for the discharge current (A)
• dischargeEnable
  current flag unloading allowed
• dischargeVoltageLimit
  current discharge voltage limit (V) of the battery module
• moduleSoftwareVersion_manufacture
  Firmware version of the battery module
• packAlarmInfo
  Alarm status (ok - battery module is OK, failure - there is a fault in the battery module)
• packCapacity
  nominal capacity (Ah) of the battery module
• packCapacityRemain
  current capacity (Ah) of the battery module
• packCellcount
  Number of cell packs in the battery module
• packCurrent
  current charge current (+) or discharge current (-) of the battery module (A)
• packCycles
  Number of full cycles - The number of cycles is, to some extent, a measure of the wear and tear of the battery. A complete charge and discharge is counted as one cycle. If the battery is discharged and recharged 50%, it only counts as one half cycle. Pylontech specifies a lifetime of several 1000 cycles (see data sheet).
• packImbalance
  current imbalance of voltage between the single cells of the battery module (%)
• packPower
  current drawn (+) or delivered (-) power (W) of the battery module
• packSOC
  State of charge (%) of the battery module
• packState
  current working status of the battery module
• packVolt
  current voltage (V) of the battery module
• paramCellHighVoltLimit
  System parameter upper voltage limit (V) of a cell
• paramCellLowVoltLimit
  System parameter lower voltage limit (V) of a cell (alarm limit)
• paramCellUnderVoltLimit
  System parameter undervoltage limit (V) of a cell (protection limit)
• paramChargeCurrentLimit
  System parameter charging current limit (A) of the battery module
• paramChargeHighTempLimit
  System parameter upper temperature limit (°C) up to which the battery charges
• paramChargeLowTempLimit
  System parameter lower temperature limit (°C) up to which the battery charges
• paramDischargeCurrentLimit
  System parameter discharge current limit (A) of the battery module
• paramDischargeHighTempLimit
  System parameter upper temperature limit (°C) up to which the battery discharges
• paramDischargeLowTempLimit
  System parameter lower temperature limit (°C) up to which the battery discharges
• paramModuleHighVoltLimit
  System parameter upper voltage limit (V) of the battery module
• paramModuleLowVoltLimit
  System parameter lower voltage limit (V) of the battery module (alarm limit)
• paramModuleUnderVoltLimit
  System parameter undervoltage limit (V) of the battery module (protection limit)
• protocolVersion
  PYLON low voltage RS485 protocol version
• serialNumber
  Serial number

QRCode

[EN DE]

Devices of this module are used to generate an URL that will be used to generate and receive a QRCode from the service of TEC-IT
The device will also display the generated QRCode in the device details. It can also provide the HTML-code used for display for other purposes (e.g. weblink devices)

ATTENTION:The sevice provider does not allow more than 30 QRCode generations / minute without special permission

See terms of sevice on TEC-IT homepage: http://qrcode.tec-it.com/de#TOS

Define

define <name> QRCode



Set

set <name> update
Refreshes the QRCode-URL for Image generation.

Attributes


QRCode-URL relevant attributes

The following attributes take influence on the QRCode generation.

If one of those attributes is changed, per default an auto update of the QRCode-URL is performed.


• qrData
  This attribute is used to set the data that will be encoded in the QRCode.
  If this attribute is not set an error message is generatet.
  
  
• qrSize
  Defines the size of the generated QRCode image
  Possible values are small, medium (default), large.
  
  
• qrResolutionDPI
  Defines the resolution for QRCode generaation
  Valid values are between 96 and 600 (Default is 300dpi)
  
  
• qrColor
  Defines the foreground color of the genereted QRCode image
  This is a RGB color value in hex format (eg. FF0000 = red) Default is 000000 (black)
  
  
• qrBackColor
  Defines the background color of the genereted QRCode image
  This is a RGB color value in hex format (eg. 0000FF = blue) Default is FFFFFF (white).
  
  
• qrTransparent
  Defines that the background of the generated QRCode will be transparent
  Possible values are False (non-tranparent background) or True (transparent background)
  default is non-transparent.
  
  
• qrQuietZone
  defines the size of a quiet zone around the QRCode in the image.
  This is a blank zone making it easier to scan the QRCode for some scanners.
  Default ist 0, if attribute is not set.
  
  
• qrQuietUnit
  specifies the unit for qrQuietZone attribute
  Possible values are mm (default), in (=inch), mil (=mils), mod (=Module) or px (=Pixel).
  
  
• qrCodepage
  Used Codepage for QRCode generation.
  Possible values are UTF8 (default), Cyrillic or Ansi
  
  
• qrErrorCorrection
  Error correction used in generated QRCode image.
  Possible values are L (default), M,Q or H
  
  
Display relevant attributes

The followin Attribute change the behaviour and display parameters for the detail view
of QRCode devices in FHEMWEB. Therfore it changes the result of QRCode_getHtml function
(see below.)

In cas of an error, neither QRCode, nor qrDisplayText will be displayed. Instead
an error message is displayed.


• qrDisplayWidth
  display width of the QRCode image
  Default is 200
  
  
• qrDisplayHeight
  Display height of the QRCode image
  Default is 200
  
  
• qrDisplayData
  If set the contents or the reading data is displayed below the QRCode image
  Usually this is the contents of attribute qrData.
  
  
• qrDisplaNoImage
  If set, the QRCode image will not be displayed
  
  
• qrDisplaText
  user defined text to be displayed below QRCode image
  
  
• qrDisplaNoText
  If this attribute is set, the text specified in qrDisplayText will not be displayed
  below QRCode image. So qrDisplayText doesn't have to be deleted.
  
  
• qrNoAutoUpdate
  If set not auto update will be processed for QRCode relevant attributes.
  
  
• readingFnAttributes


Generated Readings




• data
  This reading contains the data to be encoded by the QRCode
  Usually this is the contents of attribute qrData.
  In case of an error it contains the error message.
  
  
• qrcode_url
  By set update generated URL, used to get the QRCode image
  
  
  
• state
  The state of the device
  Initially this is defined or the timestamp of last set update, or auto-update
  
  


Usefull Funktionen

The module comes with a useful function to provide the HTML code used for display in detail view of the
QRCode device in FHEMWEB for other purposes, e.g. weblink.




• QRCode_getHtml($;$$)
  
  Returns the HTML code for the specified QRCode device
  
  Arguments:
  
  
  • QRCodeDevice
    Name of the QRCode device as a string.
  • noImage (Optional)
    The same as attribute qrDisplayNoImage
    
  • noText (Optional)
    The same as attribute qrDisplayNoText
    
  
  
  Example:
  
  QRCode_getHtml('MyQRCode',1,0)
  
  Generate HTML code of (QRCode-) device named MyQRCode with QRCode image but not with the
  user defined Text (qrDisplayText).

RESIDENTS

[EN DE]

Define
define <rgr_ResidentsName> RESIDENTS

Provides a special virtual device to represent a group of individuals living at your home.
It locically combines individual states of ROOMMATE, GUEST and PET devices and allows state changes for all members.
Based on the current state and other readings, you may trigger other actions within FHEM.

Example:

# Standalone
define rgr_Residents RESIDENTS


Set
set <rgr_ResidentsName> <command> [<parameter>]

Currently, the following commands are defined.

• addGuest   -   creates a new GUEST device and adds it to the current RESIDENTS group. Just enter the dummy name and there you go.
• addPet   -   creates a new PET device and adds it to the current RESIDENTS group. Just enter the dummy name and there you go.
• addRoommate   -   creates a new ROOMMATE device and adds it to the current RESIDENTS group. Just enter the first name and there you go.
• removeGuest   -   shows all GUEST members and allows to delete their dummy devices easily.
• removePet   -   shows all PET members and allows to delete their dummy devices easily.
• removeRoommate   -   shows all ROOMMATE members and allows to delete their dummy devices easily.
• state   home,gotosleep,asleep,awoken,absent,gone   switch between states for all group members at once; see attribute rgr_states to adjust list shown in FHEMWEB
• create   wakeuptimer   add several pre-configurations provided by RESIDENTS Toolkit. See separate section for details.
Note: If you would like to restrict access to admin set-commands (-> addGuest, addPet, addRoommate, removeGuest, removePet, create) you may set your FHEMWEB instance's attribute allowedCommands like 'set,set-user'. The string 'set-user' will ensure only non-admin set-commands can be executed when accessing FHEM using this FHEMWEB instance.



Possible states and their meaning


This module differs between 7 states:


• home - residents are present at home and at least one of them is not asleep
• gotosleep - present residents are on their way to bed (if they are not asleep already)
• asleep - all present residents are currently sleeping
• awoken - at least one resident just woke up from sleep
• absent - no resident is currently at home but at least one will be back shortly
• gone - all residents left home for longer period
• none - no active member


Note: State 'none' cannot explicitly be set. Setting state to 'gone' will be handled as 'none' for GUEST or PET member devices.


Attributes

• rgr_homealoneInStatus - if set, state will have a prefix of the value of residentsHomealoneSubtype; In case it is a pet, it will only be copied to state as 'pet'. Defaults to "0"
• rgr_homealoneSubTypes - a list of subTypes that will trigger home alone status if they are the only ones present at home. The order here will also affect the determination of the person with the most responsibility at home. The sorting order starts with least important to most important.
• rgr_lang - overwrite global language setting; helps to set device attributes to translate FHEMWEB display text
• rgr_noDuration - may be used to disable continuous, non-event driven duration timer calculation (see readings durTimer*)
• rgr_showAllStates - states 'asleep' and 'awoken' are hidden by default to allow simple gotosleep process via devStateIcon; defaults to 0
• rgr_states - list of states to be shown in FHEMWEB; separate entries by comma only and do NOT use spaces; unsupported states will lead to errors though
• rgr_wakeupDevice - reference to enslaved DUMMY devices used as a wake-up timer (part of RESIDENTS Toolkit's wakeuptimer)



Generated Readings/Events:

• homealoneSubtype - subType of the residential object in charge
• homealoneType - type of the residential object in charge
• lastActivity - the last state change of one of the group members
• lastActivityBy - the realname of the last group member with changed state
• lastArrival - timestamp of last arrival at home
• lastAwake - timestamp of last sleep cycle end
• lastDeparture - timestamp of last departure from home
• lastDurAbsence - duration of last absence from home in human readable format (hours:minutes:seconds)
• lastDurAbsence_cr - duration of last absence from home in computer readable format (minutes)
• lastDurPresence - duration of last presence at home in human readable format (hours:minutes:seconds)
• lastDurPresence_cr - duration of last presence at home in computer readable format (minutes)
• lastDurSleep - duration of last sleep in human readable format (hours:minutes:seconds)
• lastDurSleep_cr - duration of last sleep in computer readable format (minutes)
• lastSleep - timestamp of last sleep cycle begin
• lastState - the prior state
• lastWakeup - time of last wake-up timer run
• lastWakeupDev - device name of last wake-up timer
• nextWakeup - time of next wake-up program run
• nextWakeupDev - device name for next wake-up program run
• presence - reflects the home presence state, depending on value of reading 'state' (can be 'present' or 'absent')
• residentsAbsent - number of residents with state 'absent'
• residentsAbsentDevs - device name of residents with state 'absent'
• residentsAbsentNames - device alias of residents with state 'absent'
• residentsAsleep - number of residents with state 'asleep'
• residentsAsleepDevs - device name of residents with state 'asleep'
• residentsAsleepNames - device alias of residents with state 'asleep'
• residentsAwoken - number of residents with state 'awoken'
• residentsAwokenDevs - device name of residents with state 'awoken'
• residentsAwokenNames - device alias of residents with state 'awoken'
• residentsGone - number of residents with state 'gone'
• residentsGoneDevs - device name of residents with state 'gone'
• residentsGoneNames - device alias of residents with state 'gone'
• residentsGotosleep - number of residents with state 'gotosleep'
• residentsGotosleepDevs - device name of residents with state 'gotosleep'
• residentsGotosleepNames - device alias of residents with state 'gotosleep'
• residentsHome - number of residents with state 'home'
• residentsHomeDevs - device name of residents with state 'home'
• residentsHomeNames - device alias of residents with state 'home'
• residentsTotal - total number of all active residents despite their current state
• residentsTotalAbsent - number of all residents who are currently underway
• residentsTotalAbsentDevs - device name of all residents who are currently underway
• residentsTotalAbsentNames - device alias of all residents who are currently underway
• residentsTotalGuests - number of active guests who are currently treated as part of the residents scope
• residentsTotalGuestsAbsent - number of all active guests who are currently underway
• residentsTotalGuestsAbsentDevs - device name of all active guests who are currently underway
• residentsTotalGuestsAbsentNames - device alias of all active guests who are currently underway
• residentsTotalGuestsPresent - number of all active guests who are currently at home
• residentsTotalGuestsPresentDevs - device name of all active guests who are currently at home
• residentsTotalGuestsPresentNames - device alias of all active guests who are currently at home
• residentsTotalPeople - number of active people who are currently treated as part of the residents scope
• residentsTotalPeopleAbsent - number of all active people who are currently underway
• residentsTotalPeopleAbsentDevs - device name of all active people who are currently underway
• residentsTotalPeopleAbsentNames - device alias of all active people who are currently underway
• residentsTotalPeoplePresent - number of all active people who are currently at home
• residentsTotalPeoplePresentDevs - device name of all active people who are currently at home
• residentsTotalPeoplePresentNames - device alias of all active people who are currently at home
• residentsTotalPets - number of pets treated as being a permanent resident
• residentsTotalPetsAbsent - number of all pets who are currently underway
• residentsTotalPetsAbsentDevs - device name of all pets who are currently underway
• residentsTotalPetsAbsentNames - device alias of all pets who are currently underway
• residentsTotalPetsPresent - number of all pets who are currently at home
• residentsTotalPetsPresentDevs - device name of all pets who are currently at home
• residentsTotalPetsPresentNames - device alias of all pets who are currently at home
• residentsTotalRoommates - number of residents treated as being a permanent resident
• residentsTotalRoommatesAbsent - number of all roommates who are currently underway
• residentsTotalRoommatesAbsentDevs - device name of all roommates who are currently underway
• residentsTotalRoommatesAbsentNames - device alias of all roommates who are currently underway
• residentsTotalRoommatesPresent - number of all roommates who are currently at home
• residentsTotalRoommatesPresentDevs - device name of all roommates who are currently at home
• residentsTotalRoommatesPresentNames - device alias of all roommates who are currently at home
• residentsTotalPresent - number of all residents who are currently at home
• residentsTotalPresentDevs - device name of all residents who are currently at home
• residentsTotalPresentNames - device alias of all residents who are currently at home
• residentsTotalWakeup - number of all residents which currently have a wake-up program being executed
• residentsTotalWakeupDevs - device name of all residents which currently have a wake-up program being executed
• residentsTotalWakeupNames - device alias of all residents which currently have a wake-up program being executed
• residentsTotalWayhome - number of all active residents who are currently on their way back home
• residentsTotalWayhomeDevs - device name of all active residents who are currently on their way back home
• residentsTotalWayhomeNames - device alias of all active residents who are currently on their way back home
• residentsTotalWayhomeDelayed - number of all residents who are delayed on their way back home
• residentsTotalWayhomeDelayedDevs - device name of all delayed residents who are currently on their way back home
• residentsTotalWayhomeDelayedNames - device alias of all delayed residents who are currently on their way back home
• state - reflects the current state
• wakeup - becomes '1' while a wake-up program of this resident group is being executed


RESIDENTS Toolkit

Using set-command create you may add pre-configured configurations to your RESIDENTS, ROOMMATE, GUEST or PET devices for your convenience.
The following commands are currently available:


• wakeuptimer   -   adds a wake-up timer dummy device with enhanced functions to start with wake-up automations
  A notify device is created to be used as a Macro to carry out your actual automations. The macro is triggered by a normal at device you may customize as well. However, a special RESIDENTS Toolkit function is handling the wake-up trigger event for you.
  The time of activated wake-up timers may be relatively increased or decreased by using + or - respectively. +HH:MM can be used as well.
  
  The wake-up behaviour may be influenced by the following device attributes:
  
  • wakeupAtdevice - backlink the at device (mandatory)
  • wakeupDays - only trigger macro at these days. Mon=1,Tue=2,Wed=3,Thu=4,Fri=5,Sat=6,Sun=0 (optional)
  • wakeupDefaultTime - after triggering macro reset the wake-up time to this default value (optional)
  • wakeupEnforced - Enforce wake-up (optional; 0=no, 1=yes, 2=if wake-up time is not wakeupDefaultTime, 3=if wake-up time is earlier than wakeupDefaultTime)
  • wakeupHolidays - May trigger macro on holidays or non-holidays (optional; andHoliday=on holidays also considering wakeupDays, orHoliday=on holidays independently of wakeupDays, andNoHoliday=on non-holidays also considering wakeupDays, orNoHoliday=on non-holidays independently of wakeupDays)
  • wakeupMacro - name of the notify macro device (mandatory)
  • wakeupOffset - value in minutes to trigger your macro earlier than the user requested to be woken up, e.g. if you have a complex wake-up program over 30 minutes (defaults to 0)
  • wakeupResetSwitcher - DUMMY device to quickly turn on/off reset function (optional, device will be auto-created)
  • wakeupResetdays - if wakeupDefaultTime is set you may restrict timer reset to specific days only. Mon=1,Tue=2,Wed=3,Thu=4,Fri=5,Sat=6,Sun=0 (optional)
  • wakeupUserdevice - backlink to RESIDENTS, ROOMMATE, GUEST or PET device to check its status (mandatory)
  • wakeupWaitPeriod - waiting period threshold in minutes until wake-up program may be triggered again, e.g. if you manually set an earlier wake-up time than normal while using wakeupDefaultTime. Does not apply in case wake-up time was changed during this period; defaults to 360 minutes / 6h (optional)

RFXCOM

[EN DE]

This module is for the old RFXCOM USB or LAN based 433 Mhz RF receivers and transmitters (order order code 80002 and others). It does not support the new RFXtrx433 transmitter because it uses a different protocol. See RFXTRX for support of the RFXtrx433 transmitter.
These receivers supports many protocols like Oregon Scientific weather sensors, RFXMeter devices, X10 security and lighting devices and others.
Currently the following parser modules are implemented:

• 41_OREGON.pm (see device OREGON): Process messages Oregon Scientific weather sensors. See http://www.rfxcom.com/oregon.htm of Oregon Scientific weather sensors that could be received by the RFXCOM receivers. Until now the following Oregon Scientific weather sensors have been tested successfully: BTHR918, BTHR918N, PCR800, RGR918, THGR228N, THGR810, THR128, THWR288A, WTGR800, WGR918. It will probably work with many other Oregon sensors supported by RFXCOM receivers. Please give feedback if you use other sensors.
  
• 42_RFXMETER.pm (see device RFXMETER): Process RFXCOM RFXMeter devices. See http://www.rfxcom.com/sensors.htm.
• 43_RFXX10REC.pm (see device RFXX10REC): Process X10 security and X10 lighting devices.

Note: this module requires the Device::SerialPort or Win32::SerialPort module if the devices is connected via USB or a serial port.

Define
define <name> RFXCOM <device> [noinit]


USB-connected (80002):

<device> specifies the USB port to communicate with the RFXCOM receiver. Normally on Linux the device will be named /dev/ttyUSBx, where x is a number. For example /dev/ttyUSB0.

Example:
define RFXCOMUSB RFXCOM /dev/ttyUSB0


Network-connected devices:

<device> specifies the host:port of the device. E.g. 192.168.1.5:10001
noninit is optional and issues that the RFXCOM device should not be initialized. This is useful if you share a RFXCOM device. It is also useful for testing to simulate a RFXCOM receiver via netcat or via FHEM2FHEM.

Example:
define RFXCOMTCP RFXCOM 192.168.1.5:10001
define RFXCOMTCP2 RFXCOM 192.168.1.121:10001 noinit



• dummy


• longids
  Comma separated list of device-types for RFXCOM that should be handled using long IDs. This additional ID is a one byte hex string and is generated by the Oregon sensor when is it powered on. The value seems to be randomly generated. This has the advantage that you may use more than one Oregon sensor of the same type even if it has no switch to set a sensor id. For example the author uses two BTHR918N sensors at the same time. All have different deviceids. The drawback is that the deviceid changes after changing batteries. All devices listed as longids will get an additional one byte hex string appended to the device name.
  Default is to use long IDs for all devices.
  
  Examples:

  # Do not use any long IDs for any devices:
  attr RFXCOMUSB longids 0
  # Use any long IDs for all devices (this is default):
  attr RFXCOMUSB longids 1
  # Use longids for BTHR918N devices.
  # Will generate devices names like BTHR918N_f3.
  attr RFXCOMUSB longids BTHR918N
  # Use longids for TX3_T and TX3_H devices.
  # Will generate devices names like TX3_T_07, TX3_T_01 ,TX3_H_07.
  attr RFXCOMUSB longids TX3_T,TX3_H

RFXMETER

[EN DE]

The RFXMETER module interprets RFXCOM RFXMeter messages received by a RFXCOM receiver. You need to define an RFXCOM receiver first. See the RFXCOM.

Define
define <name> RFXMETER <deviceid> [<scalefactor>] [<unitname>]

<deviceid> is the device identifier of the RFXMeter sensor and is a one byte hexstring (00-ff).
<scalefactor> is an optional scaling factor. It is multiplied to the value that is received from the RFXmeter sensor.
<unitname> is an optional string that describes the value units. It is added to the Reading generated to describe the values.

Example:
define RFXWater RFXMETER 00 0.5 ltr
define RFXPower RFXMETER 01 0.001 kwh
define RFXGas RFXMETER 02 0.01 cu_m


Set
N/A

Get
N/A

Attributes
• ignore


• do_not_notify

RFXX10REC

[EN DE]

The RFXX10REC module interprets X10 security and X10 lighting messages received by a RFXCOM RF receiver. Reported also to work with KlikAanKlikUit. You need to define an RFXCOM receiver first. See RFXCOM.

Define
define <name> RFXX10REC <type> <deviceid> <devicelog> [<deviceid> <devicelog>]

<type>
specifies the type of the X10 device:
X10 security devices:
• ds10a (X10 security ds10a Door/Window Sensor or compatible devices. This device type reports the status of the switch [Open/Closed], status of the delay switch [min|max]], and battery status [ok|low].)
• ms10a (X10 security ms10a motion sensor. This device type reports the status of motion sensor [normal|alert] and battery status [ok|low].))
• sd90 (Marmitek sd90 smoke detector. This device type reports the status of the smoke detector [normal|alert] and battery status [ok|low].)
• kr18 (X10 security remote control. Report the Reading "Security" with values [Arm|Disarm], "ButtonA" and "ButtonB" with values [on|off] )
X10 lighting devices:
• ms14a (X10 motion sensor. Reports [normal|alert] on the first deviceid (motion sensor) and [on|off] for the second deviceid (light sensor))
• x10 (All other x10 devices. Report [on|off] on both deviceids.)

<deviceid>
specifies the first device id of the device. X10 security have a a 16-Bit device id which has to be written as a hex-string (example "5a54"). A X10 lighting device has a house code A..P followed by a unitcode 1..16 (example "B1").

<devicelog>
is the name of the Reading used to report. Suggested: "Window" or "Door" for ds10a, "motion" for motion sensors, "Smoke" for sd90.

<deviceid2>
is optional and specifies the second device id of the device if it exists. For example sd90 smoke sensors can be configured to report two device ids. ms14a motion sensors report motion status on the first deviceid and the status of the light sensor on the second deviceid.

<devicelog2>
is optional for the name used for the Reading of <deviceid2>.

Example:
define livingroom_window RFXX10REC ds10a 72cd Window
define motion_sensor1 RFXX10REC ms10a 55c6 motion
define smoke_sensor1 RFXX10REC sd90 54d3 Smoke 54d3 Smoketest
define motion_sensor2 RFXX10REC ms14a A1 motion A2 light


Set
N/A

Get
N/A

Attributes
• ignore


• do_not_notify

RHASSPY

[EN DE]

This module receives, processes and executes voice commands coming from Rhasspy voice assistent.

General Remarks:

• For dialogues, RHASSPY relies on the mechanisms as described in Rhasspy Dialogue Manager documentation.
  So don't expect these parts to work if you use other options than Rhasspy's own dialogue management.
• You may need or want some additional materials to get the best out of RHASSPY in FHEM. So have a look at the additional files and examples provided in svn contrib.
  See especially attributes languageFile and rhasspyIntents for further reference.

Define

define <name> RHASSPY <baseUrl> <devspec> <defaultRoom> <language> <fhemId> <prefix> <useGenericAttrs> <handleHotword> <Babble> <encoding>

All parameters in define are optional, most will not be needed (!), but keep in mind: changing them later might lead to confusing results for some of them! Especially when starting with RHASSPY, do not set any other than the first three (or four if your language is neither english nor german) of these at all!

Remark:
RHASSPY uses parseParams at quite a lot places, not only in define, but also to parse attribute values.
So all parameters in define should be provided in the key=value form. In other places you may have to start e.g. a single line in an attribute with option:key="value xy shall be z" or identifier:yourCode={fhem("set device off")} anotherOption=blabla form.

Parameters:

• baseUrl: http-address of the Rhasspy service web-interface. Optional, but needed as soon as default (baseUrl=http://127.0.0.1:12101) is not appropriate.
  Make sure, this is set to correct values (ip and port) if Rhasspy is not running on the same machine or not uses default port!
• devspec: All the devices you want to control by Rhasspy must meet devspec. If genericDeviceType support is enabled, it defaults to genericDeviceType=.+, otherwise the former default devspec=room=Rhasspy will be used. See as a reference, how to e.g. use a comma-separated list of devices or combinations like devspec=room=livingroom,room=bathroom,bedroomlamp.
• defaultRoom: Default room name. Used to speak commands without a room name (e.g. "turn lights on" to turn on the lights in the "default room"). Optional, but also recommended. Default is defaultRoom=default.
• language: Makes part of the topic tree, RHASSPY is listening to. Should (but needs not to) point to the language voice commands shall be spoken with. Default is derived from global, which defaults to language=en. Preferably language should be set appropriate in global, if possible.
• fhemId: May be used to distinguishe between different instances of RHASSPY on the MQTT side. Also makes part of the topic tree the corresponding RHASSPY is listening to.
  Might be usefull, if you have several instances of FHEM running, and may - in later versions - be a criteria to distinguish between different users (e.g. to only allow a subset of commands and/or rooms to be addressed). Not recommended to be set if just one RHASSPY device is defined.
• prefix: May be used to distinguishe between different instances of RHASSPY on the FHEM-internal side.
  Might be usefull, if you have several instances of RHASSPY in one FHEM running and want e.g. to use different identifier for groups and rooms (e.g. a different language). Not recommended to be set if just one RHASSPY device is defined.
• useGenericAttrs: Formerly, RHASSPY only used it's own attributes (see list below) to identifiy options for the subordinated devices you want to control. Today, it is capable to deal with a couple of commonly used genericDeviceType (switch, light, thermostat, thermometer, blind, media, scene and info), so it will add genericDeviceType to the global attribute list and activate RHASSPY's feature to estimate appropriate settings - similar to rhasspyMapping. useGenericAttrs=0 will deactivate this. (do not set this unless you know what you are doing!). Notes:
  • As some devices may not directly provide all their setter infos at startup time, RHASSPY will do a second automatic devicemap update 2 minutes after each FHEM start. In the meantime not all commands may work.
  • homebridgeMapping atm. is not used as source for appropriate mappings in RHASSPY.
• siteId: To some extend, you may (indirectly) want or need a RHASSPY device to act as a satellite in the Rhasspy ecosystem. So it may be a good idea to add the siteId (no matter if it's the automatically generated one) to the satellite list in the intent recognition component in Rhasspy. Otherwise the following features will not work:
  • Test sentencies (single or read from a file)
  • rhasspyMsgDialog
  • rhasspySpeechDialog
• noChangeover: By default, RHASSPY will first try to execute the intent as handed over by Rhasspy. In case there's no strict match, RHASSPY then will do a check, if the single device intent could be executed as group intent (vice versa; to do this, the {Group} key value will be used as {Device} key). Setting this key to '1' will completely prevent this check, '2' will stop changeover from single device intent to respective group intent, but allow to switch from group to single device.
• handleHotword: Trigger Reading hotword in case of a hotword is detected. See attribute rhasspyHotwords for further reference.
• Babble: experimental! Points to a Babble device. Atm. only used in case if text input from an AMADCommBridge is processed, see rhasspySpeechDialog for details.
• encoding: most likely deprecated! May be helpfull in case you experience problems in conversion between RHASSPY (module) and Rhasspy (service). Example: encoding=cp-1252. Do not set this unless you experience encoding problems!
• sessionTimeout experimental! timout limit in seconds. By default, RHASSPY will close a sessions immediately once a command could be executed. Setting a timeout will keep session open until timeout expires. NOTE: Setting this key may result in confusing behaviour. Atm not recommended for regular useage, testing only! May require some non-default settings on the Rhasspy side to prevent endless self triggering. Note: In case of Kaldi, you may have to set a longer default there as well.
• autoTraining: deactivated by setting the timeout (in seconds) to "0", default is "60". If not set to "0", RHASSPY will try to catch all actions wrt. to changes in attributes that may contain any content relevant for Rhasspy's training. In case if, training will be initiated after timeout hast passed since last action; see also update devicemap command.

RHASSPY needs a MQTT2_CLIENT device connected to the same MQTT-Server as the voice assistant (Rhasspy) service.

Examples for defining an MQTT2_CLIENT device and the Rhasspy device in FHEM:

• Minimalistic version - Rhasspy running on the same machine using it's internal MQTT server, MQTT2_CLIENT is only used by RHASSPY, language setting from global is used:

  defmod rhasspyMQTT2 MQTT2_CLIENT localhost:12183
attr rhasspyMQTT2 clientOrder RHASSPY
attr rhasspyMQTT2 subscriptions setByTheProgram

  define Rhasspy RHASSPY defaultRoom=Livingroom

• Extended version - Rhasspy running on remote machine using an external MQTT server on a third machine with non-default port, MQTT2_CLIENT is also used by MQTT_GENERIC_BRIDGE and MQTT2_DEVICE, hotword events shall be generated:

  defmod rhasspyMQTT2 MQTT2_CLIENT 192.168.1.122:1884
attr rhasspyMQTT2 clientOrder RHASSPY MQTT_GENERIC_BRIDGE MQTT2_DEVICE
attr rhasspyMQTT2 subscriptions hermes/intent/+ hermes/dialogueManager/sessionStarted hermes/dialogueManager/sessionEnded hermes/nlu/intentNotRecognized hermes/hotword/+/detected hermes/hotword/toggleOn hermes/hotword/toggleOff hermes/tts/say <additional subscriptions for other MQTT-Modules>

  define Rhasspy RHASSPY baseUrl=http://192.168.1.210:12101 defaultRoom="Büro Lisa" language=de devspec=genericDeviceType=.+,device_a1,device_xy handleHotword=1

Additionals remarks on MQTT2-IOs:

Using a separate MQTT server (and not the internal MQTT2_SERVER) is highly recommended, as the Rhasspy scripts also use the MQTT protocol for internal (sound!) data transfers. Best way is to either use MQTT2_CLIENT (see above) or bridge only the relevant topics from mosquitto to MQTT2_SERVER (see e.g. http://www.steves-internet-guide.com/mosquitto-bridge-configuration for the principles). When using MQTT2_CLIENT, it's necessary to set clientOrder to include RHASSPY (as most likely it's the only module listening to the CLIENT it could be just set to attr <m2client> clientOrder RHASSPY)

Furthermore, you are highly encouraged to restrict subscriptions only to the relevant topics:

attr <m2client> subscriptions setByTheProgram

In case you are using the MQTT server also for other purposes than Rhasspy, you have to set subscriptions manually to at least include the following topics additionally to the other subscriptions desired for other purposes.

hermes/intent/+
hermes/dialogueManager/sessionStarted
hermes/dialogueManager/sessionEnded
hermes/nlu/intentNotRecognized
hermes/hotword/+/detected
hermes/hotword/toggleOn
hermes/hotword/toggleOff
hermes/tts/say

Important: After defining the RHASSPY module, you are supposed to manually set the attribute IODev to force a non-dynamic IO assignement. Use e.g. attr <deviceName> IODev <m2client>.

Note: RHASSPY consolidates a lot of data from different sources. The final data structure RHASSPY uses at runtime will be shown by the list command. It's highly recommended to have a close look at this data structure, especially when starting with RHASSPY or in case something doesn't work as expected!
After changing something relevant within FHEM for either the data structure in

• RHASSPY (this form is used when reffering to module or the FHEM device) or for
• Rhasspy (this form is used when reffering to the remote service),

you have to make sure these changes are also updated in RHASSPYs internal data structure and (often, but not always) to Rhasspy. See the different versions provided by the update command.

Set

• update

  Various options to update settings and data structures used by RHASSPY and/or Rhasspy. Choose between one of the following:

  • devicemap
    When having finished the configuration work to RHASSPY and the subordinated devices, issuing a devicemap-update is required. You may do that manually in case you have deactivated the "autoTraining" feature or do not want to wait untill timeout is reached. Issueing that command will get the RHASSPY data structure updated, inform Rhasspy on changes that may have occured (update slots) and initiate a training on updated slot values etc., see remarks on data structure above.
  • devicemap_only
    This may be helpfull to make an intermediate check, whether attribute changes have found their way to the data structure. This will neither update slots nor (immediately) initiate any training towards Rhasspy.
  • slots
    This may be helpfull after checks on the FHEM side to immediately send all data to Rhasspy and initiate training.
  • slots_no_training
    This may be helpfull to make checks, whether all data is sent to Rhasspy. This will not initiate any training.
  • language
    Reinitialization of language file.
    Be sure to execute this command after changing something within in the language configuration file!
    
  • intent_filter
    Reset intent filter used by Rhasspy dialogue manager. See intentFilter in rhasspyTweaks attribute for details.
    
  • all
    Surprise: means language file and full update to RHASSPY and Rhasspy including training and intent filter.

  Example: set <rhasspyDevice> update language

• play <siteId and path+filename>

  Send WAV file to Rhasspy.
  siteId and path and filename are required!
  You may optionally add a number of repeats and a wait time in seconds between repeats. wait defaults to 15, if only repeats is given.

  Examples:
  set <rhasspyDevice> play siteId="default" path="/opt/fhem/test.wav"
set <rhasspyDevice> play siteId="default" path="./test.wav" repeats=3 wait=20

• speak <siteId and text>

  Voice output over TTS.
  Both arguments (siteId and text) are required!

  Example:
  set <rhasspyDevice> speak siteId="default" text="This is a test"

• textCommand <text to analyze>

  Send a text command to Rhasspy.

  Example:
  set <rhasspyDevice> textCommand turn the light on

• fetchSiteIds

  Send a request to Rhasspy to send all siteId's. This by default is done once, so in case you add more satellites to your system, this may help to get RHASSPY updated.

  Example:
  set <rhasspyDevice> fetchSiteIds

• trainRhasspy

  Sends a train-command to the HTTP-API of the Rhasspy master
  Might be removed in the future versions in favor of the update features

  Example:
  set <rhasspyDevice> trainRhasspy

• volume <float value>

  Sets volume of given siteId between 0 and 1 (float)
  Both arguments (siteId and volume) are required!

  Example:
  set <rhasspyDevice> siteId="default" volume="0.5"

• customSlot <parameters>

  Creates a new - or overwrites an existing slot - in Rhasspy
  Provide slotname, slotdata and (optional) info, if existing data shall be overwritten and training shall be initialized immediately afterwards.
  First two arguments are required, third and fourth are optional.
  overwrite defaults to true, setting any other value than true will keep existing Rhasspy slot data.

  Examples:
  set <rhasspyDevice> customSlot mySlot a,b,c overwrite training
set <rhasspyDevice> customSlot slotname=mySlot slotdata=a,b,c overwrite=false

• activateVoiceInput

  Activate a satellite for voice input. siteId, hotword and modelId may be provided (either in order of appearance or as named arguments), otherwise some defaults will be used.

Get

• export_mapping <devicename>

  Exports a "classical" rhasspyMapping attribute value for the provided device. You may find this usefull to adopt that further to your individual needs. May not completely work in all cases, especially wrt. to SetScene and HUEBridge formated scenes.

• test_file <path and filename>

  Checks the provided text file. Content will be sent to Rhasspy NLU for recognition (line by line), result will be written to the file '<input without ending.txt>_result.txt'. stop as filename will stop test mode if sth. goes wrong. No commands will be executed towards FHEM devices while test mode is active.

  Note: To get test results, some additional configuration in Rhasspy is required!

• test_sentence <sentence to be analyzed>

  Checks the provided sentence for recognition by Rhasspy NLU. No commands to be executed as well, needs also additional configuration in Rhasspy.

Attributes

Note: To get RHASSPY working properly, you have to configure attributes at RHASSPY itself and the subordinated devices as well.

RHASSPY itself supports the following attributes:

• languageFile
  

  Path to the language-config file. If this attribute isn't set, a default set of english responses is used for voice responses.
  The file itself must contain a JSON-encoded keyword-value structure (partly with sub-structures) following the given structure for the mentioned english defaults. As a reference, there's one in the additionals files available in german (note the comments there!), or just make a dump of the English structure with e.g. (replace RHASSPY by your device's name): {toJSON($defs{RHASSPY}->{helper}{lng})}, edit the result e.g. using https://jsoneditoronline.org and place this in your own languageFile version. There might be some variables to be used - these should also work in your sentences.
  languageFile also allows combining e.g. a default set of german sentences with some few own modifications by using "defaults" subtree for the defaults and "user" subtree for your modified versions. This feature might be helpful in case the base language structure has to be changed in the future.

  Example (placed in the same dir fhem.pl is located):

  attr <rhasspyDevice> languageFile ./rhasspy-de.cfg

• response

  Note: Using this attribute is no longer recommended, use options provided by the languageFile attribute instead.

  Optionally define alternative default answers. Available keywords are DefaultError, NoActiveMediaDevice and DefaultConfirmation.

  Example:

  DefaultError=
DefaultConfirmation=Klaro, mach ich

• rhasspyIntents

  Defines custom intents. See Custom Intent erstellen.
  One intent per line.

  Example:

  attr <rhasspyDevice> rhasspyIntents SetCustomIntentsTest=SetCustomIntentsTest(siteId,Type)

  together with the following myUtils-Code should get a short impression of the possibilities:

  sub SetCustomIntentsTest {
my $room = shift;
my $type = shift;
Log3('rhasspy',3 , "RHASSPY: Room $room, Type $type");
return "RHASSPY: Room $room, Type $type";
}

  The following arguments can be handed over:

  • NAME => name of the RHASSPY device addressed,
  • DATA => entire JSON-$data (as parsed internally), encoded in JSON
  • siteId, Device etc. => any element out of the JSON-$data.

  If a simple text is returned, this will be considered as response, if return value is not defined, the default response will be used.
  You may use the internal functions (e.g. "handleIntentSetOnOff()" as well. To skipp the default answers for these intents, you have to add a "noResponse"-key to the $data argument (or ".inBulk" key forr single device intents).
  For more advanced use of this feature, you may return either a HASH or an ARRAY data structure (Note: The formating of the required data might be subject to changes!). If ARRAY is returned:

  • First element of the array is interpreted as response and may be plain text (dialog will be ended) or HASH type to continue the session. The latter will keep the dialogue-session open to allow interactive data exchange with Rhasspy. An open dialogue will be closed after some time, (configurable) default is 20 seconds, you may alternatively hand over other numeric values as second element of the array.
  • Second element might either be a comma-separated list of devices that may have been modified (otherwise, these devices will not cast any events! See also the "d" parameter in rhasspyShortcuts), or (if first element is HASH type) a nummeric value as timeout.
  • If HASH type data (or $response in ARRAY) is returned to continue a session, make sure to hand over all relevant elements, including especially customData for referencing and intentFilter if you want to restrict possible intents. It's recommended to always also activate CancelAction to allow user to actively exit the dialogue, or activate something that could hand over a resetInput key.
  
  See also additionals files for further examples on this.

• rhasspyShortcuts

  Define custom sentences without editing Rhasspys sentences.ini
  The shortcuts are uploaded to Rhasspy when using the updateSlots set-command.
  One shortcut per line, syntax is either a simple and an extended version.

  Examples:

  mute on=set amplifier2 mute on
lamp off={fhem("set lampe1 off")}
i="you are so exciting" f="set $NAME speak siteId='livingroom' text='Thanks a lot, you are even more exciting!'"
i="mute off" p={fhem ("set $NAME mute off")} n=amplifier2 c="Please confirm!"
i="i am hungry" f="set Stove on" d="Stove" c="would you like roast pork"

  Abbreviations explanation:

  • i => intent
    Lines starting with "i:" will be interpreted as extended version, so if you want to use that syntax style, starting with "i:" is mandatory.
  • f => FHEM command
    Syntax as usual in FHEMWEB command field.
  • p => Perl command
    Syntax as usual in FHEMWEB command field, enclosed in {}; this has priority to "f=".
  • d => device name(s, comma separated) that shall be handed over to fhem.pl as updated. Needed for triggering further actions and longpoll! Note: When calling Perl functions, the return value of the called function will be used if no explicit device is provided.
  • r => Response to be send to the caller. If not set, the return value of the called function will be used.
    Response sentence will be parsed to do "set magic"-like replacements, so also a line like i="what's the time for sunrise" r="at [Astro:SunRise] o'clock" is valid.
    You may ask for confirmation as well using the following (optional) shorts:
    • c => either numeric or text. If numeric: Timeout to wait for automatic cancellation. If text: response to send to ask for confirmation.
    • ct => numeric value for timeout in seconds, default: 15.
    See here for more info about confirmations.


• rhasspyTweaks

  Place for additional settings to influence RHASSPY's global behavior on certain aspects.

  • timerLimits

    Used to determine when the timer should response with e.g. "set to 30 minutes" or with "set to 10:30"

    timerLimits=90,300,3000,2*HOURSECONDS,50

    Five values have to be set, corresponding with the limits to timerSet responses. so above example will lead to seconds response for less then 90 seconds, minute+seconds response for less than 300 seconds etc.. Last value is the limit in seconds, if timer is set in time of day format.

  • timerSounds

    Per default the timer responds with a voice command if it has elapsed. If you want to use a wav-file instead, you can set this here.

    timerSounds= default=./yourfile1.wav eggs=3:20:./yourfile2.wav potatoes=5:./yourfile3.wav

    Above keys are some examples and need to match the "Label"-tags for the timer provided by the Rhasspy-sentences.
    default is optional. If set, this file will be used for all labeled timer without match to other keywords.
    The two numbers are optional. The first one sets the number of repeats, the second is the waiting time between the repeats.
    repeats defaults to 5, wait to 15
    If only one number is set, this will be taken as repeats.

  • timeouts

    Atm. keywords confirm and/or default can be used to change the corresponding defaults (15 seconds / 20 seconds) used for dialogue timeouts.

    Example:

    timeouts: confirm=25 default=30

  • confidenceMin

    By default, RHASSPY will use a minimum confidence level of 0.66, otherwise no command will be executed. You may change this globally (key: default) or more granular for each intent specified.
    Example:

    confidenceMin= default=0.6 SetMute=0.4 SetOnOffGroup=0.8 SetOnOff=0.8

  • confirmIntents

    This key may contain <Intent>=<regex> pairs beeing

    • Intent one of the intents supporting confirmation feature (all set type intents) and
    • regex containing a regular expression matching to either the group name (for group intents) or the device name(s) - using a full match lookup. If intent and regex match, a confirmation will be requested. Example:

      confirmIntents=SetOnOffGroup=light|blinds SetOnOff=blind.*

    To execute any action requiring confirmation, you have to send an Mode:OK value by the ConfirmAction intent. Any other Mode key sent to ConfirmAction intent will be interpretad as cancellation request. For cancellation, you may alternatively use the CancelAction intent. Example:
    [de.fhem:ConfirmAction]
( yes, please do it | go on | that's ok | yes, please ){Mode:OK}
( don't do it after all ){Mode}
[de.fhem:CancelAction]
( let it be | oh no | cancel | cancellation ){Mode:Cancel}
    

  • confirmIntentResponses

    By default, the answer/confirmation request will be some kind of echo to the originally spoken sentence ($rawInput as stated by DefaultConfirmationRequestRawInput key in responses). You may change this for each intent specified using $target, ($rawInput) and $Value als parameters.
    Example:

    confirmIntentResponses=SetOnOffGroup="really switch group $target $Value" SetOnOff="confirm setting $target $Value"

    $Value may be translated with defaults from a words key in languageFile, for more options on $Value and/or more specific settings in single devices see also confirmValueMap key in rhasspySpecials.

  • ignoreKeywords

    You may have also some technically motivated settings in the attributes RHASSPY uses to generate slots, e.g. MQTT, alexa, homebridge or googleassistant in room attribute. The key-value pairs will sort the given value out while generating the content for the respective slot for key (atm. only rooms and group are supported). value will be treated as (case-insensitive) regex with need to exact match.
    Example:

    ignoreKeywords=room=MQTT|alexa|homebridge|googleassistant|logics-.*

  • gdt2groups

    You may want to assign some default groupnames to all devices with the same genericDeviceType without repeating it in all single devices.
    Example:

    gdt2groups= blind=rollläden,rollladen thermostat=heizkörper light=lichter,leuchten

  • mappingOverwrite

    If set, any value set in rhasspyMapping attribute will delete all content detected by automated mapping analysis (default: only overwrite keys set in devices rhasspyMapping attributes.

    Example:

    mappingOverwrite=1

  • extrarooms

    You may want to add more rooms to what Rhasspy can recognize as room. Using this key, the comma-separated items will be sent as rooms for preparing the room and mainrooms slots.
    Example:

    extrarooms= barn,music collection,cooking recipies
    Note: Only do this in case you really know what you are doing! Additional rooms only may be usefull in case you have some external application knowing what to do with info assinged to these rooms!

  • updateSlots

    Changes aspects on slot generation and updates.

    noEmptySlots=1

    By default, RHASSPY will generate an additional slot for each of the genericDeviceType it recognizes, regardless, if there's any devices marked to belong to this type. If set to 1, no empty slots will be generated.

    overwrite_all=false

    By default, RHASSPY will overwrite all generated slots. Setting this to false will change this.

  • intentFilter

    Atm. Rhasspy will activate all known intents at startup. As some of the intents used by FHEM are only needed in case some dialogue is open, it will deactivate these intents (atm: ConfirmAction, CancelAction, Choice, ChoiceRoom and ChoiceDevice(including the additional parts derived from language and fhemId))) at startup or when no active filtering is detected. You may disable additional intents by just adding their names in intentFilter line or using an explicit state assignment in the form intentname=true (Note: activating the 4 mentionned intents is not possible!). For details on how configure works see Rhasspy documentation.

• rhasspyHotwords

  Define custom reactions as soon as a specific hotword is detected (or with "global": a toggle command is detected). This does not require any specific configuration on any other FHEM device.
  One hotword per line, syntax is either a simple and an extended version. The "hotword" global will be treated specially and can be used to also execute custom commands when a toggle event is indicated.

  Examples:
  

  bumblebee_linux = set amplifier2 mute on
porcupine_linux = livingroom="set amplifier mute on" default={Log3($DEVICE,3,"device $DEVICE - room $ROOM - value $VALUE")}
global = { rhasspyHotword($DEVICE,$VALUE,$DATA,$MODE) }

  First example will execute the command for all incoming messages for the respective hotword, second will decide based on the given siteId keyword; $DEVICE is evaluated to RHASSPY name, $ROOM to siteId and $VALUE to the hotword. Additionally, in "global key", $DATA will contain entire JSON-$data (as parsed internally, encoded in JSON) and $MODE will be one of on, off or detected
  . You may assign different commands to on, off and detected. default is optional. If set, this action will be executed for all siteIds without match to other keywords.
  Additionally, if either rhasspyHotwords is set or key handleHotword in DEF is activated, the reading hotword will be filled with hotword plus siteId to also allow arbitrary event handling.
  NOTE: As all hotword messages are sent to a common topic structure, you may need additional measures to distinguish between several RHASSPY instances, e.g. by restricting subscriptions and/or using different entries in this attribute.

• rhasspyMsgDialog

  If some key in this attribute are set, RHASSPY will react somehow like a msgDialog device. This needs some configuration in the central msgConfig device first, and additional configuration in Rhasspy!

  Keys that may be set in this attribute:
  • allowed The ROOMMATE or GUEST devices allowed to interact with RHASSPY (comma-separated device names). This ist the only mandatory key to be set.
  • open A keyword or expression used to initiate a dialogue (will be converted to a regex compatible notation)
  • sessionTimeout timout limit in seconds (recommended). All sessions will be closed automatically when timeout has passed. Timer will be reset with each incoming message .
  • close keyword used to exit a dialogue (similar to open) before timeout has reached
  • hello and goodbye are texts to be sent when opening or exiting a dialogue
  • msgCommand the fhem-command to be used to send messages to the messenger service.
  • siteId the siteId to be used by this RHASSPY instance to identify it as satellite in the Rhasspy ecosystem
  • querymark Text pattern that shall be used to distinguish the queries done in intent MsgDialog from others (for the future: will be added to all requests towards Rhasspy intent recognition system automatically; not functional atm.)
  
  

Remarks on rhasspySpeechDialog and Babble:
Interaction with Babble and AMAD.*-Devices is not approved to be properly working yet. Further tests may be needed and functionality may be subject to changes!

• rhasspySpeechDialog experimental!

  Optionally, you may want not to use the internal speach-to-text and text-to-speach engines provided by Rhasspy (for one or several siteId's), but provide simple text to be forwarded to Rhasspy for intent recognition. Atm. only "AMAD" is supported for this feature. For generic "msg" (and text messenger) support see rhasspyMsgDialog
  Note: Needs some additional configuration in Rhasspy!

  Keys that may be set in this attribute:
  • allowed A list of AMADDevice devices allowed to interact with RHASSPY (comma-separated device names). This ist the only mandatory key to be set.
  • filterFromBabble By default, all incoming messages from AMADDevice/AMADCommBridge will be forwarded to Rhasspy. For better interaction with Babble you may opt to ignore all messages not matching the filterFromBabble by their starting words (case-agnostic, will be converted to a regex compatible notation). You additionally have to set a Babble key in DEF pointing to the Babble device. All regular messages (start sequence not matching filter) then will be forwarded to Babble using Babble_DoIt() function.
  • <allowed AMAD-device> A list of key=value pairs to tweak default behaviours:
    • wakeword If set, a wakeword detected message for this wakeword will lead to an "activateVoiceInput" command towards this AMADDevice
    • sessionTimeout timeout (in seconds) used if a request (e.g. for confirmation) is open for this AMADDevice (if not set, global default value is used)
    • Remark: This may contain additional keys in the future, e.g., to restrict wakeword effect to a specific siteId.
  Example:
  

  allowed=AMADDev_A
filterFromBabble=tell rhasspy
AMADDev_A=wakeword=alexa sessionTimeout=20

• forceNEXT

  If set to 1, RHASSPY will forward incoming messages also to further MQTT2-IO-client modules like MQTT2_DEVICE, even if the topic matches to one of it's own subscriptions. By default, these messages will not be forwarded for better compability with autocreate feature on MQTT2_DEVICE. See also clientOrder attribute in MQTT2 IO-type commandrefs; setting this in one instance of RHASSPY might affect others, too.

 

For the subordinated devices, a list of the possible attributes is automatically extended by several further entries

The names of these attributes all start with the prefix previously defined in RHASSPY - except for genericDeviceType (gDT).
These attributes are used to configure the actual mapping to the intents and the content sent by Rhasspy.

Note: As the analyses of the gDT is intented to lead to fast configuration progress, it's highly recommended to use this as a starting point. All other RHASSPY-specific attributes will then be considered as a user command to overwrite the results provided by the automatics initiated by gDT usage.

By default, the following attribute names are used: rhasspyName, rhasspyRoom, rhasspyGroup, rhasspyChannels, rhasspyColors, rhasspySpecials.
Each of the keywords found in these attributes will be sent by update to Rhasspy to create the corresponding slot.

• rhasspyName

  Comma-separated "labels" for the device as used when speaking a voice-command. They will be used as keywords by Rhasspy. May contain space or mutated vovels.

  Example:
  attr m2_wz_08_sw rhasspyName kitchen lamp,ceiling lamp,workspace,whatever

• rhasspyRoom

  Comma-separated "labels" for the "rooms" the device is located in. Recommended to be unique.

  Example:
  attr m2_wz_08_sw rhasspyRoom living room

  Note: If you provide more than one room, the first will be regarded as mainroom, which has a special role, especially in dialogues.

• rhasspyGroup

  Comma-separated "labels" for the "groups" the device is in. Recommended to be unique.

  Example: attr m2_wz_08_sw rhasspyGroup lights

• rhasspyMapping

  If automatic detection (gDT) does not work or is not desired, this is the place to tell RHASSPY how your device can be controlled.

  Example:

  attr lamp rhasspyMapping SetOnOff:cmdOn=on,cmdOff=off,response="All right"
GetOnOff:currentVal=state,valueOff=off
GetNumeric:currentVal=pct,type=brightness
SetNumeric:currentVal=brightness,cmd=brightness,minVal=0,maxVal=255,map=percent,step=1,type=brightness
GetState:response=The temperature in the kitchen is at [lamp:temperature] degrees
MediaControls:cmdPlay=play,cmdPause=pause,cmdStop=stop,cmdBack=previous,cmdFwd=next

• rhasspyChannels

  Used to change the channels of a tv, set light-scenes, etc.
  key=value line by line arguments mapping command strings to fhem- or Perl commands.

  Example:

  attr TV rhasspyChannels orf eins=channel 201
orf zwei=channel 202
orf drei=channel 203


  Note: This attribute is not added to global attribute list by default. Add it using userattr or by editing the global userattr attribute.

• rhasspyColors

  Used to change to colors of a light
  key=value line by line arguments mapping keys to setter strings on the same device.

  Example:

  attr lamp1 rhasspyColors red=rgb FF0000
green=rgb 008000
blue=rgb 0000FF
yellow=rgb FFFF00

  Note: This attribute is not added to global attribute list by default. Add it using userattr or by editing the global userattr attribute. You may consider using rhasspySpecials (colorCommandMap and/or colorForceHue2rgb) instead.

• rhasspySpecials

  Options to change a bunch of aspects how a single device behaves when addressed by voice commands. You may use several of the following lines.

  key:value line by line arguments similar to rhasspyTweaks.

  • group

    If set, the device will not be directly addressed, but the mentioned group - typically a FHEM structure device or a HUEDevice-type group. This has the advantage of saving RF ressources and/or fits better to already implemented logics.
    Note: all addressed devices will be switched, even if they are not member of the rhasspyGroup. Each group should only be addressed once, but it's recommended to put this info in all devices under RHASSPY control in the same external group logic.
    All of the following options are optional.

    • async_delay
      Float nummeric value, just as async_delay in structure; the delay will be obeyed prior to the next sending command.
    • prio
      Numeric value, defaults to "0". prio and async_delay will be used to determine the sending order as follows: first devices will be those with lowest prio arg, second sort argument is async_delay with lowest value first.
    • partOf
      Will adress an entire group directly. This group has to exist in FHEM first (could be e.g. a structure or a ZigBee-group) and needs to be switched with the same command than the single device.

    Example:

    attr lamp1 rhasspySpecials group:async_delay=0.3 prio=1 group=lights

  • numericValueMap

    Allows mapping of numeric values from the Value key to individual commands. Might e.g. usefull to address special positioning commands for blinds.

    Example:

    attr blind1 rhasspySpecials numericValueMap:10='Event Slit' 50='myPosition'

    Note: will lead to e.g. set blind1 Event Slit when numeric value 10 is received in {Value} key.

  • venetianBlind

    attr blind1 rhasspySpecials venetianBlind:setter=dim device=blind1_slats stopCommand="set blind1_slats dim [blind1_slats:dim]"

    Explanation (one of the two arguments is mandatory):

    • setter is the set command to control slat angle, e.g. positionSlat for CUL_HM or older ZWave type devices
    • device is needed if the slat command has to be issued towards a different device (applies e.g. to newer ZWave type devices)
    • CustomCommand arbitrary command defined by the user. Note: no variables will be evaluated. Will be executed if a regular nummeric command is detected.
    • stopCommand arbitrary command defined by the user. Note: no variables will be evaluated. Will be executed if a stop command is detected.

    If set, the slat target position will be set to the same level than the main device.

  • colorCommandMap

    Allows mapping of values from the Color key to individual commands.

    Example:

    attr lamp1 rhasspySpecials colorCommandMap:0='rgb FF0000' 120='rgb 00FF00' 240='rgb 0000FF'

  • colorTempMap

    Allows mapping of values from the Colortemp key to individual commands.

    Works similar to colorCommandMap

  • colorForceHue2rgb

    Defaults to "0". If set, a rgb command will be issued, even if the device is capable to handle hue commands.

    Example:

    attr lamp1 rhasspySpecials colorForceHue2rgb:1

  • priority

    Keywords inRoom and outsideRoom can be used, each followed by comma separated types to give priority in Set or Get intents. This may eleminate requests in case of several possible devices or rooms to deliver requested info type.

    Example:

    attr sensor_outside_main rhasspySpecials priority:inRoom=temperature outsideRoom=temperature,humidity,pressure

    Note: If there's a suitable "active" device, this will be given an even higher priority in most cases (e.g. "make music louder" may increase the volume on a switched on amplifier device and not go to an MPD device in the same room)

  • confirm

    This is the more granular alternative to confirmIntents key in rhasspyTweaks (including confirmIntentResponses). You may provide intent names only or <Intent>=<response> pairs like confirm: SetOnOff="$target shall be switched $Value" SetScene.

  • confirmValueMap

    Provide a device specific translation for $Value, e.g. for a blind type device rhasspySpecials could look like:
    confirm: SetOnOff="really $Value $target"
confirmValueMap: on=open off=close

  • scenes

    attr lamp1 rhasspySpecials scenes:scene2="Kino zu zweit" scene3=Musik scene1=none scene4=none

    Explanation:

    If set, the value (e.g. "Kino zu zweit") provided will be sent to Rhasspy instead of the tech names (e.g. "scene2", derived from available setters). Value none will delete the scene from the internal list, setting the combination all=none will exclude the entire device from beeing recognized for SetScene, rest=none will only include the labeled scenes. These values finally will be what's expected to be spoken to identificate a specific scene.

  • blacklistIntents

    attr weather rhasspySpecials blacklistIntents:MediaControls

    Explanation:

    If set, the blacklisted intents will be deleted after automated mapping analysis.

• rhasspyMsgCommand

  Command used by RHASSPY to send messages to text dialogue partners. See also rhasspyMsgDialog attribute.

Intents

The following intents are directly implemented in RHASSPY code. Note: In case you hand over a key named "resetInput", no specific intent handler will be called, but the respective satellite will be activated and reset to it's default intentFilter.

The keywords used by these intents (in sentences.ini) are as follows:

• Shortcuts
(keywords as required by user code)
• SetOnOff
{Device} and {Value} (on/off) are mandatory, {Room} is optional.
Note: As experimental feature, you may hand over additional fields, like {Device1} ("1" here and in the follwoing keys may be any additonal postfix), {Group}/{Group1} and/or {Room1}. Then the intent will be interpreted as SetOnOffGroup intent adressing all the devices matching the {Device}s or {Group}s name(s), as long as they are in (one of) the respective {Room}s.
The only restriction is: The intented {Value} (or, for other multicommand intents: Color etc.-value) has to be unique.
• SetOnOffGroup
{Group} and {Value} (on/off) are mandatory, {Room} is optional, global in {Room} will be interpreted as "everywhere".
Experimental multicommand feature should work also with this intent, (redirecting to itself and adding devices according to the additional keys).
• SetTimedOnOff
Basic keywords see SetOnOff, plus timer info in at least one of the fields {Hour} (for relative additions starting now), {Hourabs} (absolute time of day), {Min} (minutes) and {Sec} (seconds). If {Hourabs} is provided, {Min} and {Sec} will also be interpreted as absolute values.
• SetTimedOnOffGroup
(for keywords see SetOnOffGroup)
• GetOnOff
(for keywords see SetOnOff)
• SetNumeric
Dependend on the specific surrounding informations, a combination of {Device}, {Value} (nummeric value), {Change} and/or {Type} are sufficient, {Room} is optional. Additional optional field is {Unit} (value percent will be interprated as request to calculate, others will be ignored). {Change} can be with one of ({Type})
• lightUp, lightDown (brightness)
• volUp, volDown (volume)
• tempUp, tempDown (temperature/desired-temp)
• setUp, setDown (setTarget)
• cmdStop (applies only for blinds)
allowing to decide on calculation scheme and to guess for the appropiate device and/or answer. Optionally you may combine {Change} with {Factor} (nummeric value) to increase or reduce the stepwidth (typically derived from device, if {Value} is not provided) of the desired change (both values will be multiplied). experimental multicommand feature should work also with this intent (switching intent to SetNumericGroup).
• SetNumericGroup
(as SetNumeric, except for {Group} instead of {Device}).
• GetNumeric
(as SetNumeric)
• GetState
To querry existing devices, {Device} is mandatory, keys {Room}, {Update}, {Type} and {Reading} (defaults to internal STATE) are optional. By omitting {Device}, you may request some options RHASSPY itself provides (may vary dependend on the room). {Type} keys for RHASSPY are generic, control, info, scenes and rooms.
• MediaControls
{Device} and {Command} are mandatory, {Room} is optional. {Command} may be one of cmdStop, cmdPlay, cmdPause, cmdFwd, cmdBack or cmdPlaylist (the later only if there's an playlist command available, requires additional {Playlist} field).
experimental! If you put an MPD device under RHASSPY control, you may also have the option to use cmdPlaySelected and cmdAddSelected to replace or extend your current playlist using several additional fields: {ArtistId}, {AlbumId}, {Album}, {Artist}, {Albumartist}, {Title}, {Genre}, and {Name}. The first two will be treated as musicbrainz_artistid or musicbrainz_albumid respecively and (lower case) transfered to filter arguments as described in MPD documentation. Additionally you may use {RandomNr} to shuffle the result and limit the songs added to the given number.
• MediaChannels
(as configured by the user)
• SetColor
{Device} and one Color option are mandatory, {Room} is optional. Color options are {Hue} (0-360), {Colortemp} (0-100), {Saturation} (as understood by your device) or {Rgb} (hex value from 000000 to FFFFFF) experimental multicommand feature should work as well.
• SetColorGroup
(as SetColor, except for {Group} instead of {Device}).
• SetScene
{Device} and {Scene} (it's recommended to use the $lng.fhemId.Scenes slot to get that generated automatically!), {Room} is optional, {Get} with value scenes may be used to request all possible scenes for a device prior to make a choice.
• GetTime
• GetDate
• Timer
Timer info as described in SetTimedOnOff is mandatory, {Room} and/or {Label} are optional to distinguish between different timers. {CancelTimer} key will force RHASSPY to try to remove a running timer (using optional {Room} and/or {Label} key to identify the respective timer), {GetTimer} key will be treated as request if there's a timer running (optionally also identified by {Room} and/or {Label} keys).
• SetTimer
(Outdated, use generic "Timer" instead!) Set a timer, required info as mentionned in Timer Required tags to set a timer: at least one of {Hour}, {Hourabs}, {Min} or {Sec}. {Label} and {Room} are optional to distinguish between different timers. If {Hourabs} is provided, all timer info will be regarded as absolute time of day info, otherwise everything is calculated using a "from now" logic.
• GetTimer
(Outdated, use generic "Timer" instead!) Get timer info as mentionned in Timer, key {GetTimer} is not explicitely required.
• ConfirmAction
{Mode} with value 'OK'. All other calls will be interpreted as CancelAction intent call.
• CancelAction
Hand over a {Mode} key is recommended.
• Choice
One or more of {Room}, {Device} or {Scene}
• ChoiceRoom
{Room} NOTE: Useage of generic "Choice" intent instead is highly recommended!
• ChoiceDevice
{Device} NOTE: Useage of generic "Choice" intent instead is highly recommended!
• ReSpeak

Readings

There are some readings you may find usefull to tweak some aspects of RHASSPY's logics:

• siteId2room_<siteId>
Typically, RHASSPY derives room info from the name of the siteId. So naming a satellite bedroom will let RHASSPY assign this satellite to the same room, using the group sheme is also supported, e.g. kitchen.front will refer to kitchen as room (if not explicitly given).
You may overwrite that behaviour by setting values to siteId2room readings: setreading siteId2room_mobile_phone1 kitchen will force RHASSPY to link your satellite phone1 kitchen to kitchen as room.
• room2siteId_<room>
Used to identify the satellite to speak messages addressed to a room (same for playing sound files). Should deliver exactly one possible siteId, e.g. <lingingroom.04>
• siteId2doubleSpeak_<siteId>
RHASSPY will always respond via the satellite where the dialogue was initiated from. In some cases, you may want additional output to other satellites - e.g. if they don't have (always on) sound output options. Setting this type of reading will lead to (additional!) responses to the given second satellite; naming scheme is the same as for site2room.
• sessionTimeout_<siteId>
RHASSPY will by default automatically close every dialogue after an executable commandset is detected. By setting this type of reading, you may keep open the dialoge to wait for the next command to be spoken on a "by siteId" base; naming scheme is similar as for site2room. Intent CancelAction will close any session immedately.
• siteId2ttsDevice_<siteId>
experimental! If an AMADDevice TYPE device is enabled for rhasspySpeechDialog, RHASSPY will forward response texts to the device for own text-to-speach processing. Setting this type of reading allows redirection of adressed satellites to the given AMADDevice (device name as reading value, 0 to disable); naming scheme is the same as for site2room.

ROLLO

[EN DE]

The module ROLLO offers an easy away to control shutters with one or two relays and to stop them exactly.
The current position (in %) will be displayed in fhem. It doesn't matter which hardware is used to control the shutters as long as they are working with FHEM.


Note

If you had installed ROLLO before it became part of FHEM and you didn't update it for a long time, you might miss the "position" readings and the corresponding set command. "position" was replaced with "pct" to ensure compatibility with other modules (like Automatic shutter control - ASC). Please adjust your notifies/DOIFs accordingly.

Example

define TestRollo ROLLO

Define

define <Rollo-Device> ROLLO

Define a ROLLO instance.

Set

• open set <Rollo-Device> open
  opens the shutter (pct 0)
• closed set <Rollo-Device> closed
  close the shutter (pct 100)
• up set <Rollo-Device> up
  opens the shutter one step (pct +10)
• down set <Rollo-Device> down
  close the shutter one step (pct -10)
• half set <Rollo-Device> half
  drive the shutter to half open (pct 50)
• stop set <Rollo-Device> stop
  stop a driving shutter
• drive set <Rollo-Device> drive up 5
  Drives the shutter in the specified direction for the specified time (in seconds)
• blocked set <Rollo-Device> blocked
  when activated, the shutter can move only restricted. See attribute block_mode for further details.
• unblocked set <Rollo-Device> unblocked
  unblock the shutter, so you can drive the shutter
• pct set <Rollo-Device> pct <value>
  drive the shutter to exact pct from 0 (open) to 100 (closed)
• reset set <Rollo-Device> reset <value>
  set the modul to real pct if the shutter pct changed outside from fhem
• extern set <Rollo-Device> extern <value>
  if the shutter is started/stopped externaly, you can inform the module so it can calculate the current pct

Get

• version get <Rollo-Device> version
  Returns the version number of the FHEM ROLLO module

Attributes

• rl_type attr <Rollo-Device> rl_type [normal|HomeKit] Type differentiation to support different hardware. Depending on the selected type, the direction of which the pct is expected to set:
  • normal = pct 0 means open, pct 100 means closed
  • HomeKit = pct 100 means open, pct 0 means closed
• rl_secondsDown attr <Rollo-Device> rl_secondsDown <number>
  time in seconds needed to drive the shutter down
• rl_secondsUp attr <Rollo-Device> rl_secondsUp <number>
  time in seconds needed to drive the shutter up
• rl_excessTop attr <Rollo-Device> rl_excessTop <number>
  additional time the shutter need from last visible top pct to the end pct
• rl_excessBottom attr <Rollo-Device> rl_excessBottom <number>
  additional time the shutter need from visible closed pct to the end pct
• rl_switchTime attr <Rollo-Device> rl_switchTime <number>
  time for the shutter to switch from one driving direction to other driving direction
• rl_resetTime attr <Rollo-Device> rl_resetTime <number>
  additional time the shutter remains in driving state if driving to final positions (open, closed), to ensure that the final position was really reached. So difference in the pct calculation can be corrected.
• rl_reactionTime attr <Rollo-Device> rl_reactionTime <number>
  additional time the shutter needs to start (from start command to really starting the motor)
• rl_autoStop attr <Rollo-Device> rl_autoStop [0|1]
  No stop command should be sent, the shutter stops by itself.
• rl_commandUp attr <Rollo-Device> rl_commandUp <string>
  Up to three commands you have to send to drive the shutter up
• rl_commandDown attr <Rollo-Device> rl_commandDown <string>
  Up to three commands you have to send to drive the shutter down
• rl_commandStop attr <Rollo-Device> rl_commandStop <string>
  command to stop a driving shutter
• rl_commandStopDown attr <Rollo-Device> rl_commandStopDown <string>
  command to stop a down driving shutter, if not set commandStop is executed
• rl_commandStopUp attr <Rollo-Device> rl_commandStopUp <string>
  command to stop a up driving shutter, if not set commandStop is executed
• rl_blockMode attr <Rollo-Device> rl_blockMode [blocked|force-open|force-closed|only-up|only-down|half-up|half-down|none]
  the possibilities of the shutter in blocked mode:
  • blocked = shutter can't drive
  • force-open = drive the shutter up if a drive command is send
  • force-closed = drive the shutter down if a drive command is send
  • only-up = only drive up commands are executed
  • only-down =only drive down commands are executed
  • half-up = only drive to pcts above half-up
  • half-down = only drive to pcts below half-down
  • none = blockmode is disabled
• automatic-enabled attr <Rollo-Device> automatic-enabled [yes|no]
  if disabled the additional module ROLLO_AUTOMATIC doesn't drive the shutter
• automatic-delay attr <Rollo-Device> automatic-delay <number>
  if set any ROLLO_AUTOMATIC commands are executed delayed (in minutes)
  
• rl_forceDrive attr <Rollo-Device> rl_forceDrive [0|1]
  force open/closed even if device is already in target position
  
• rl_noSetPosBlocked attr <Rollo-Device> rl_noSetPosBlocked [0|1]
  if disabled positions may be set even if device is blocked. After unblocking it will drive to the position.
  
• disable attr <Rollo-Device> disable [0|1]
  if disabled all set and get commands for ROLLO are disabled
  
• readingFnAttributes

ROOMMATE

[EN DE]

Define
define <rr_FirstName> ROOMMATE [<device name(s) of resident group(s)>]

Provides a special virtual device to represent a resident of your home.
Based on the current state and other readings, you may trigger other actions within FHEM.

Used by superior module RESIDENTS but may also be used stand-alone.

Use comma separated list of resident device names for multi-membership (see example below).

Example:

# Standalone
define rr_Manfred ROOMMATE

# Typical group member
define rr_Manfred ROOMMATE rgr_Residents # to be member of resident group rgr_Residents

# Member of multiple groups
define rr_Manfred ROOMMATE rgr_Residents,rgr_Parents # to be member of resident group rgr_Residents and rgr_Parents

# Complex family structure
define rr_Manfred ROOMMATE rgr_Residents,rgr_Parents # Parent
define rr_Lisa ROOMMATE rgr_Residents,rgr_Parents # Parent
define rr_Rick ROOMMATE rgr_Residents,rgr_Children # Child1
define rr_Alex ROOMMATE rgr_Residents,rgr_Children # Child2



Set
set <rr_FirstName> <command> [<parameter>]

Currently, the following commands are defined.

• location   -   sets reading 'location'; see attribute rr_locations to adjust list shown in FHEMWEB
• mood   -   sets reading 'mood'; see attribute rr_moods to adjust list shown in FHEMWEB
• state   home,gotosleep,asleep,awoken,absent,gone   switch between states; see attribute rr_states to adjust list shown in FHEMWEB
• create
• locationMap   add a pre-configured weblink device using showing a Google Map if readings locationLat+locationLong are present.
• wakeuptimer   add several pre-configurations provided by RESIDENTS Toolkit. See separate section in RESIDENTS module commandref for details.
Note: If you would like to restrict access to admin set-commands (-> create) you may set your FHEMWEB instance's attribute allowedCommands like 'set,set-user'. The string 'set-user' will ensure only non-admin set-commands can be executed when accessing FHEM using this FHEMWEB instance.



Possible states and their meaning


This module differs between 6 states:


• home - individual is present at home and awake
• gotosleep - individual is on it's way to bed
• asleep - individual is currently sleeping
• awoken - individual just woke up from sleep
• absent - individual is not present at home but will be back shortly
• gone - individual is away from home for longer period



Presence correlation to location


Under specific circumstances, changing state will automatically change reading 'location' as well.

Whenever presence state changes from 'absent' to 'present', the location is set to 'home'. If attribute rr_locationHome was defined, first location from it will be used as home location.

Whenever presence state changes from 'present' to 'absent', the location is set to 'underway'. If attribute rr_locationUnderway was defined, first location from it will be used as underway location.



Auto Gone


Whenever an individual is set to 'absent', a trigger is started to automatically change state to 'gone' after a specific timeframe.
Default value is 36 hours.

This behaviour can be customized by attribute rr_autoGoneAfter.



Synchronizing presence with other ROOMMATE, GUEST or PET devices


If you always leave or arrive at your house together with other roommates, guests or pets, you may enable a synchronization of your presence state for certain individuals.
By setting attribute rr_passPresenceTo, those individuals will follow your presence state changes to 'home', 'absent' or 'gone' as you do them with your own device.

Please note that individuals with current state 'gone' or 'none' (in case of guests) will not be touched.



Synchronizing state with other ROOMMATE, GUEST or PET devices


To sync each and every status change that is _not_ related to leaving or arriving at your house, you may set attribute rr_passStateTo.

Please note that individuals with current state 'gone' or 'none' (in case of guests) will not be touched.



Location correlation to state


Under specific circumstances, changing location will have an effect on the actual state as well.

Whenever location is set to 'home', the state is set to 'home' if prior presence state was 'absent'. If attribute rr_locationHome was defined, all of those locations will trigger state change to 'home' as well.

Whenever location is set to 'underway', the state is set to 'absent' if prior presence state was 'present'. If attribute rr_locationUnderway was defined, all of those locations will trigger state change to 'absent' as well. Those locations won't appear in reading 'lastLocation'.

Whenever location is set to 'wayhome', the reading 'wayhome' is set to '1' if current presence state is 'absent'. If attribute rr_locationWayhome was defined, LEAVING one of those locations will set reading 'wayhome' to '1' as well. So you actually have implicit and explicit options to trigger wayhome.
Arriving at home will reset the value of 'wayhome' to '0'.

If you are using the GEOFANCY module, you can easily have your location updated with GEOFANCY events by defining a simple NOTIFY-trigger like this:

define n_rr_Manfred.location notify geofancy:currLoc_Manfred.* set rr_Manfred:FILTER=location!=$EVTPART1 location $EVTPART1

By defining geofencing zones called 'home' and 'wayhome' in the iOS app, you automatically get all the features of automatic state changes described above.


Attributes

• rr_autoGoneAfter - hours after which state should be auto-set to 'gone' when current state is 'absent'; defaults to 36 hours
• rr_geofenceUUIDs - comma separated list of device UUIDs updating their location via GEOFANCY. Avoids necessity for additional notify/DOIF/watchdog devices and can make GEOFANCY attribute devAlias obsolete. (using more than one UUID/device might not be a good idea as location my leap)
• rr_lang - overwrite global language setting; helps to set device attributes to translate FHEMWEB display text
• rr_locationHome - locations matching these will be treated as being at home; first entry reflects default value to be used with state correlation; separate entries by space; defaults to 'home'
• rr_locationUnderway - locations matching these will be treated as being underway; first entry reflects default value to be used with state correlation; separate entries by comma or space; defaults to "underway"
• rr_locationWayhome - leaving a location matching these will set reading wayhome to 1; separate entries by space; defaults to "wayhome"
• rr_locations - list of locations to be shown in FHEMWEB; separate entries by comma only and do NOT use spaces
• rr_moodDefault - the mood that should be set after arriving at home or changing state from awoken to home
• rr_moodSleepy - the mood that should be set if state was changed to gotosleep or awoken
• rr_moods - list of moods to be shown in FHEMWEB; separate entries by comma only and do NOT use spaces
• rr_noDuration - may be used to disable continuous, non-event driven duration timer calculation (see readings durTimer*)
• rr_passStateTo - synchronize home state with other ROOMMATE, GUEST or PET devices; separte devices by space
• rr_passPresenceTo - synchronize presence state with other ROOMMATE, GUEST or PET devices; separte devices by space
• rr_presenceDevices - take over presence state from any other FHEM device. Separate more than one device with comma meaning ALL of them need to be either present or absent to trigger update of this ROOMMATE device. You may optionally add a reading name separated by :, otherwise reading name presence and state will be considered.
• rr_realname - whenever ROOMMATE wants to use the realname it uses the value of attribute alias or group; defaults to group
• rr_showAllStates - states 'asleep' and 'awoken' are hidden by default to allow simple gotosleep process via devStateIcon; defaults to 0
• rr_states - list of states to be shown in FHEMWEB; separate entries by comma only and do NOT use spaces; unsupported states will lead to errors though
• rr_wakeupDevice - reference to enslaved DUMMY devices used as a wake-up timer (part of RESIDENTS Toolkit's wakeuptimer)
• subType - specifies a specific class of a roommate for the device. This will be considered for home alone status calculation. Defaults to "adult"



Generated Readings/Events:

• durTimerAbsence - timer to show the duration of absence from home in human readable format (hours:minutes:seconds)
• durTimerAbsence_cr - timer to show the duration of absence from home in computer readable format (minutes)
• durTimerPresence - timer to show the duration of presence at home in human readable format (hours:minutes:seconds)
• durTimerPresence_cr - timer to show the duration of presence at home in computer readable format (minutes)
• durTimerSleep - timer to show the duration of sleep in human readable format (hours:minutes:seconds)
• durTimerSleep_cr - timer to show the duration of sleep in computer readable format (minutes)
• lastArrival - timestamp of last arrival at home
• lastAwake - timestamp of last sleep cycle end
• lastDeparture - timestamp of last departure from home
• lastDurAbsence - duration of last absence from home in human readable format (hours:minutes:seconds)
• lastDurAbsence_cr - duration of last absence from home in computer readable format (minutes)
• lastDurPresence - duration of last presence at home in human readable format (hours:minutes:seconds)
• lastDurPresence_cr - duration of last presence at home in computer readable format (minutes)
• lastDurSleep - duration of last sleep in human readable format (hours:minutes:seconds)
• lastDurSleep_cr - duration of last sleep in computer readable format (minutes)
• lastLocation - the prior location
• lastMood - the prior mood
• lastSleep - timestamp of last sleep cycle begin
• lastState - the prior state
• lastWakeup - time of last wake-up timer run
• lastWakeupDev - device name of last wake-up timer
• location - the current location
• mood - the current mood
• nextWakeup - time of next wake-up program run
• nextWakeupDev - device name for next wake-up program run
• presence - reflects the home presence state, depending on value of reading 'state' (can be 'present' or 'absent')
• state - reflects the current state
• wakeup - becomes '1' while a wake-up program of this resident is being executed
• wayhome - depending on current location, it can become '1' if individual is on his/her way back home

RPII2C

[EN DE]

Provides access to Raspberry Pi's I2C interfaces for some logical modules and also directly.
This modul will basically work on every linux system that provides /dev/i2c-x.

preliminary:

• load I2C kernel modules (choose one of the following options):
  
  • open /etc/modules
    
    sudo nano /etc/modules
    
    add these lines
    
    i2c-dev
i2c-bcm2708

  • Since Kernel 3.18.x on raspberry pi and maybe on other boards too, device tree support was implemented and enabled by default. To enable I2C support just add
    device_tree_param=i2c0=on,i2c1=on
    to /boot/config.txt You can also enable just one of the I2C. In this case remove the unwantet one from the line.
  • On Raspbian images since 2015 just start sudo raspi-config and enable I2C there. Parameters will be added automaticly to /boot/config.txt
  reboot


• Choose only one of the three follwing methodes do grant access to /dev/i2c-* for FHEM user:
  • sudo apt-get install i2c-tools
sudo adduser fhem i2c
sudo reboot
    
  
  
  • Add following lines into /etc/init.d/fhem before perl fhem.pl line in start or into /etc/rc.local:
    sudo chown fhem /dev/i2c-*
sudo chgrp dialout /dev/i2c-*
sudo chmod +t /dev/i2c-*
sudo chmod 660 /dev/i2c-*

  
  
  • Alternatively for Raspberry Pi you can install the gpio utility from WiringPi library change access rights of I2C-Interface
    WiringPi installation is described here: RPI_GPIO.
    gpio utility will be automaticly used, if installed.
    Important: to use I2C-0 at P5 connector you must use attribute swap_i2c0.
    


• Optional: access via IOCTL will be used (RECOMMENDED) if Device::SMBus is not present.
  To access the I2C-Bus via the Device::SMBus module, following steps are necessary:
  
  sudo apt-get install libmoose-perl
sudo cpan Device::SMBus
  
  
• For Raspbian users only
  If you are using I2C-0 at P5 connector on Raspberry Pi model B with newer raspbian versions, including support for Raspberry Pi model B+, you must add following line to /boot/cmdline.txt:
  
  bcm2708.vc_i2c_override=1
  
  

Define
define <name> RPII2C <I2C Bus Number>
where <I2C Bus Number> is the number of the I2C bus that should be used (0 or 1)


Set
• Write one byte (or more bytes sequentially) directly to an I2C device (for devices that have only one register to write):
  set <name> writeByte <I2C Address> <value>
  
  
• Write n-bytes to an register range (as an series of single register write operations), beginning at the specified register:
  set <name> writeByteReg <I2C Address> <Register Address> <value> [<value> [..]]
  
  
• Write n-bytes directly to an I2C device (as an block write operation):
  set <name> writeBlock <I2C Address> <Register Address> <value> [<value> [..]]
  
  
• Write n-bytes to an register range (as an block write operation), beginning at the specified register:
  set <name> writeBlockReg <I2C Address> <Register Address> <value> [<value> [..]]
  
  

Examples:
Write 0xAA to device with I2C address 0x60
set test1 writeByte 60 AA
Write 0xAA to register 0x01 of device with I2C address 0x6E
set test1 writeByteReg 6E 01 AA
Write 0xAA to register 0x01 of device with I2C address 0x6E, after it write 0x55 to 0x02 as two separate commands
set test1 writeByteReg 6E 01 AA 55
Write 0xA4 to register 0x03, 0x00 to register 0x04 and 0xDA to register 0x05 of device with I2C address 0x60 as an block command
set test1 writeBlock 60 03 A4 00 DA



Get
• Gets value of I2C device's registers:
  get <name> read <I2C Address> [<Register Address> [<number of registers>]]
  
  
• Gets value of I2C device in blockwise mode:
  get <name> readblock <I2C Address> [<number of registers>]
  
  
• Gets value of I2C device's registers in blockwise mode:
  get <name> readblockreg <I2C Address> <Register Address> [<number of registers>]
  
  

Examples:
Reads byte from device with I2C address 0x60
get test1 read 60
Reads register 0x01 of device with I2C address 0x6E.
get test1 read 6E 01 AA 55
Reads register 0x03 to 0x06 of device with I2C address 0x60.
get test1 read 60 03 4




Attributes
• swap_i2c0
  Swap Raspberry Pi's I2C-0 from J5 to P5 rev. B
  This attribute is for Raspberry Pi only and needs gpio utility from WiringPi library.
  Default: none, valid values: on, off
  
  
• useHWLib
  Change hardware access method.
  Attribute exists only if both access methods are usable
  Default: IOCTL, valid values: IOCTL, SMBus
  
  
• ignore
• do_not_notify
• showtime

RPI_1Wire

[EN DE]

For German documentation see Wiki

provides an interface to devices connected through the standard Raspberry 1-Wire interface (GPIO4) and is aware of the following devices:


• Family 0x10 (DS18S20) temperature
• Family 0x12 (DS2406) adressable 2 port switch (untested)
• Family 0x19 (DS28E17) i2c bridge (unsupported)
• Family 0x1c (DS28E04) eeprom memory (unsupported)
• Family 0x1d (DS2423) dual counter
• Family 0x26 (DS2438) a/d converter with temperature support
• Family 0x28 (DS18B20) temperature
• Family 0x29 (DS2408) 8 port switch
• Family 0x3a (DS2413) adressable 2 port switch
• Family 0x3b (DS1825) temperature
• Family 0x42 (DS28EA00) temperature
• DHT11/DHT22 sensors (adressable GPIO) temperature, humidity

Data can be queried blocking (conversion time of temperature sensors can block FHEM for about 1s), nonblocking or with staged timer (conv_time hack)

Define

define <name> RPI_1Wire BUSMASTER|ff-xxxxxxxxxxxx|DHT11-<gpio>|DHT22-<gpio>


• BUSMASTER device has the functionality to autocreate devices on startup or with the "scan" command
  Having a BUSMASTER is not required unless you like to use autocreate or the therm_bulk_read feature.
  The internal reading "devices" will list all the device IDs associated with the BUSMASTER.
  In case you defined more than one w1_bus_master in your system, you can use "BUSMASTER-x", where "x" is the number of w1_bus_masterx in the sysfs, to explicitly define it. Default is always to use "1".
  Note: To define a FHEM device for a device that is physically not present, provide "force" as second argument to override the check.
  
• ff-xxxxxxxxxxxx is the id of a 1-Wire device as shown in sysfs tree where ff is the family. To use 1-Wire sensors call "sudo raspi-config" and enable the "1-Wire Interface" under "Interface options".
• DHT11|12-<gpio> defines a DHT11 or DHT22 sensor where gpio is the number of the used GPIO. This requires an additional Perl module which can be aquired here. Make sure to define the right type, since DHT11 and DHT22 sensors are similar, but require different algorithms to read. Also note that these are not 1-Wire (GPIO4) sensors and should be attached to GPIOs different to 4 and require one GPIO each.

Set

• set scan
  Only available for BUSMASTER: Scan the device tree for new 1-Wire devices (not possible for DHT) and trigger autocreate
  
• set update
  Force a manual update of the device data. Will also restart the polling interval.
  
• set precision 9|10|11|12
  Set the precision of the temperature conversion. Only available for temperature sensors and if the "resolution" file in sysfs is writable by the fhem user. See udev how to enable. Changing the precision is resetting conv_time to its default value.
  Lowering the precision can significantly reduce conversion time.
  Requires Linux Kernel 5.10+ (Raspbian Buster) and write permissions to sysfs (see "get udev")
  
• set conv_time <milliseconds>
  Set the conversion time of the temperature conversion. When changing the precision, this is always reset to the system default (by the w1_therm driver) and that is the recommended value for most users.
  Requires Linux Kernel 5.10+ (Raspbian Buster) and write permissions to sysfs (see "get udev")
  
• (applies only Linux Kernel 5.10+ (Raspbian Buster)): There is however a "hack" to avoid fork()ing a nonblocking call, by setting the conv_time to e.g. 2ms (do not use 1ms, this had an unexpected behaviour in my system, setting the conv_time to 576, while setting it to 0 is restoring the default value). By this the read operation to the device will not finish in time before the new value is ready, but exit almost immediately (not blocking fhem). If you now set the "mode" of this device to "timer" it will trigger another read 1.5s later when the result will be ready (and also return immediately). With this timer driven "double read" it is possible to read the values quickly without blocking FHEM.
  This might be useful if you have a lot of devices that you are reading in short sequence and you're low on system memory. The typical "nonblocking" call is temporarily creating a fork() of the current FHEM process, which in worst case can be complete copy of the memory FHEM uses (the OS does some optimizations though and only copies active parts). This can increase the risk of running out of system memory.
• set therm_bulk_read on|off
  Only available for BUSMASTER: Trigger a bulk read (in non-blocking mode) for ALL temperature sensors at once. The next read from the temperature sensors will return immediately, so it will be safe to set them to "blocking" mode, if the pollingInterval for BUSMASTER is smaller than the lowest pollingInterval for all sensors.
  Requires Linux Kernel 5.10+ (Raspbian Buster) and write permissions to sysfs (see "get udev")
  Note: There seems to be a Kernel bug, that breaks this feature if there are other 1-Wire devices on GPIO4 than temperature sensors using w1_therm driver.
  
• set clear
  Clears the failures counter.
• set pioa on|off <duration>
  Sets the pioa of a 2 port switch to on or off.
  The optional duration switches the pio back after a given number of seconds when using "on-for-timer" or "off-for-timer"
• set piob on|off <duration>
  Sets the piob of a 2 port switch to on or off.
  The optional duration switches the pio back after a given number of seconds when using "on-for-timer" or "off-for-timer"
• set pio(0-7) on|off <duration>
  Sets the according pio of a 8 port switch (0-7) to on or off.
  The optional duration switches the pio back after a given number of seconds when using "on-for-timer" or "off-for-timer"

Get

• udev
  Displays help how to configure udev to make some sysfs files writable for the fhem user. These write permissions are required to use the features conv_time, precision and therm_bulk_read.
  Just create a udev file with content as described and copy it to /etc/udev/rules.d/ (root required). To activate the rules without a reboot you can use "sudo udevadm control --reload-rules && udevadm trigger". To activate the missing set commands, you will still need to restart FHEM.
  

Attributes

• pollingInterval
  Defines how often the device is updated in seconds.
  Setting the pollingInterval to 0 disables the automatic updates.
  Default: 60, valid values: integers
  
• tempOffset
  Only applies to temperature measurements: Value to be added to the measured temperature to calibrate sensors that are off.
  In combination with the tempFactor the factor will be applied first, then the offset is added.
  Default: 0, valid values: float
  
• tempFactor
  Only applies to temperature measurements: Value that the measured temperature gets multiplied with to calibrate sensors that are off.
  In combination with the tempOffset the factor will be applied first, then the offset is added.
  Default: 1.0, valid values: float
  
• mode blocking|nonblocking|timer
  Reading values from the devices is typically blocking the execution of FHEM. In my tests a typical precision 12 temperature reading blocks for about 1s, a counter read for 0.2s and reading voltages about 0.5s.
  While this sounds minimal there are devices that may depend on timing (e.g. CUL_HM) and can be impacted if FHEM is blocked for so long. As a result this module is by default fork()ing a seperate process that does the read operation in parallel to normal FHEM execution, which should be ok for most users, but can be optimized if desired (see more in "set conv_time" above).
  Setting to timer mode is blocked for safety reasons in case conv_time is more than 9ms.
  Default: nonblocking, valid values: blocking,nonblocking,timer
  
• faultvalues
  A space separated list of values that will be ignored. Use this if you sensor is sometimes returning a strange value that you don't want to be processed. The comparison is done before applying any rounding, offsets or factors.
  Default: empty, valid values: list of values
  
• decimals
  Only applies to temperatures: Number of decimals for display (T: x.xx). The reading "temperature" always shows the full precision given by the sensor.
  Default: 3, valid values: integer
  

Readings

• failures
Counts the failed read attempts (due to unavaible devices, empty data or CRC failures).
Use "set clear" to reset this counter (e.g. after a hardware issue was resolved)

• failreason
Reason for the last seen failure:
• crc: data could be read, but there was a checksum failure. If that happens too often, check you cabling quality
• no_data: The device could be opened, but no data was received
• open_device: The device could not be opened. Likely it was disconnected
• cleared: The counter has just been cleared with "set clear"
• duration
Duration of the last read out. In modes blocking and timer a warning is put into failreason if this get more than 0.5s

• conv_time
Only for temperature: The actual used conversion time (queried from the OS)
Requires Linux Kernel 5.10+ (Raspbian Buster)

• precision
Only for temperature: The actual used precision/resolution (queried from the OS)
Requires Linux Kernel 5.10+ (Raspbian Buster)

• temperature
Temperature reading from the device

• counter.A/counter.B
Counter readings from the device (DS2423)

• vad/vdd
Voltage readings from the device (DS2438)

• pioa/piob
Switch states for dual port switches

• latcha/latchb
Latch states for DS2413. This device differentiates between the actual state of the switch and the the state of the current request (latch).

• pio1 ... pio8
Switch states for 8 port switches

RPI_GPIO

[EN DE]

Raspberry Pi offers direct access to several GPIO via header P1 (and P5 on V2). The Pinout is shown in table under define. With this module you are able to access these GPIO's directly as output or input. For input you can use either polling or interrupt mode
In addition to the Raspberry Pi, also BBB, Cubie, Banana Pi and almost every linux system which provides gpio access in userspace is supported.
Warning: Never apply any external voltage to an output configured pin! GPIO's internal logic operate with 3,3V. Don't exceed this Voltage!

preliminary:
GPIO Pins accessed by sysfs. The files are located in folder /system/class/gpio and belong to the gpio group (on actual Raspbian distributions since jan 2014). It will work even on an Jessie version but NOT if you perform an kerlen update
After execution of following commands, GPIO's are usable whithin PRI_GPIO:

sudo adduser fhem gpio
sudo reboot

If attribute pud_resistor shall be used and on older Raspbian distributions, aditionally gpio utility from WiringPi library must be installed to set the internal pullup/down resistor or export and change access rights of GPIO's (for the second case active_low does not work).
Installation WiringPi:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install git-core
git clone git://git.drogon.net/wiringPi
cd wiringPi ./build

On Linux systeme where /system/class/gpio can only accessed as root, GPIO's must exported and their access rights changed before FHEM starts.
This can be done in /etc/rc.local (Examole for GPIO22 and 23):

echo 22 > /sys/class/gpio/export
echo 23 > /sys/class/gpio/export
chown -R fhem:root /sys/devices/virtual/gpio/* (or chown -R fhem:gpio /sys/devices/platform/gpio-sunxi/gpio/* for Banana Pi)
chown -R fhem:root /sys/class/gpio/*


Define
define RPI_GPIO <GPIO number>[ <GPIO-Basedir>[ <WiringPi-gpio-utility>]]

all usable GPIO number can be found here

Examples:

      define Pin12 RPI_GPIO 18
      attr Pin12 poll_interval 5
	  define Pin12 RPI_GPIO 18 /sys/class/gpio /usr/somewhere/bin/gpio
    

Set
set <name> <value>

where value is one of:

• for output configured GPIO
  off
on
toggle

  The set extensions are also supported.
  
• for input configured GPIO
  readval
  readval refreshes the reading Pinlevel and, if attr toggletostate not set, the state value

Examples:
set Pin12 off
set Pin11,Pin12 on



Get
get <name>

returns "high" or "low" regarding the actual status of the pin and writes this value to reading Pinlevel

Attributes
• direction
  Sets the GPIO direction to input or output.
  Default: input, valid values: input, output
  
  
• active_low
  Inverts logical value
  Default: no, valid values: no, yes
  
  
• interrupt
  can only be used with GPIO configured as input
  enables edge detection for GPIO pin
  on each interrupt event readings Pinlevel and state will be updated
  Default: none, valid values: none, falling, rising, both
  For "both" the reading Longpress will be added and set to on as long as kes hold down longer than 1s
  For "falling" and "rising" the reading Toggle will be added an will be toggled at every interrupt and the reading Counter that increments at every interrupt
  
  
• poll_interval
  Set the polling interval in minutes to query the GPIO's level
  Default: -, valid values: decimal number
  
  
• toggletostate
  works with interrupt set to falling or rising only
  if yes, state will be toggled at each interrupt event
  Default: no, valid values: yes, no
  
  
• pud_resistor
  Sets the internal pullup/pulldown resistor
  Works only with installed gpio urility from WiringPi Library.
  Default: -, valid values: off, up, down
  
  
• debounce_in_ms
  readout of pin value x ms after an interrupt occured. Can be used for switch debouncing
  Default: 0, valid values: decimal number
  
  
• restoreOnStartup
  Restore Readings and sets after reboot
  Default: last, valid values: last, on, off, no
  
  
• unexportpin
  do an unexport to /sys/class/gpio/unexport if the pin definition gets cleared (e.g. by rereadcmd, delete,...)
  Default: yes, valid values: yes, no
  
  
• longpressinterval
  works with interrupt set to both only
  time in seconds, a port need to be high to set reading longpress to on
  Default: 1, valid values: 0.1 - 10
  
  
• readingFnAttributes

RSS

[EN DE]

Provides a freely configurable RSS feed and HTML page.

The media RSS feed delivers status pictures either in JPEG or PNG format. This media RSS feed can be used to feed a status display to a network-enabled photo frame.

In addition, a periodically refreshing HTML page is generated that shows the picture with an optional HTML image map.

You need to have the perl module GD installed. This module is most likely not available for small systems like Fritz!Box.

RSS is an extension to FHEMWEB. You must install FHEMWEB to use RSS.

Beginners might find the RSS Workshop useful.

A note on colors: Colors are specified as 6- or 8-digit hex numbers, every 2 digits determining the red, green and blue color components as in HTML color codes. The optional 7th and 8th digit code the alpha channel (transparency from 00 to 7F). Examples: FF0000 for red, C0C0C0 for light gray, 1C1C1C40 for semi-transparent gray.

Define

define <name> RSS jpg|png <hostname> <filename>

Defines the RSS feed. jpg and png are fixed literals to select output format. <hostname> is the hostname of the fhem server as seen from the consumer of the RSS feed. <filename> is the name of the file that contains the layout definition.

Examples

define FrameRSS RSS jpg host.example.org /etc/fhem/layout
define MyRSS RSS png 192.168.1.222 /var/fhem/conf/layout.txt


The RSS feeds are at
http://host.example.org:8083/fhem/rss/FrameRSS.rss
http://192.168.1.222:8083/fhem/rss/MyRSS.rss


The pictures are at
http://host.example.org:8083/fhem/rss/FrameRSS.jpg
http://192.168.1.222:8083/fhem/rss/MyRSS.png


The HTML pages are at
http://host.example.org:8083/fhem/rss/FrameRSS.html
http://192.168.1.222:8083/fhem/rss/MyRSS.html



Set
set <name> rereadcfg

Rereads the layout definition from the file. Useful to enable changes in the layout on-the-fly.


Attributes


• autoreread
  If set to 1, layout is automatically reread when layout file has been changed by FHEMWEB file editor.


• size
  The dimensions of the picture in the format <width>x<height>.


• bg
  A comma-separated list of directories that contain the background pictures (must be in JPEG, GIF or PNG format, file format is guessed from file name extension).


• bgroot
  A common prefix for all directories in the bg attribute. Needs to include a trailing path delimiter. Useful for setting subdirectories of a common root directory as background directories by only listing their names in the bg attributes and not the full paths.
  
  Example 1: attr myRSS bg /opt/fhem/PictureFrame/Bergansichten,/data/Files/Pictures
  Example 2: attr myRSS bgroot /opt/fhem/PictureFrame/; attr myRSS bg Bergansichten,Waldbilder
  


• bgcolor <color>
  Sets the background color.


• tmin
  The background picture is shown at least tmin seconds, no matter how frequently the RSS feed consumer accesses the page.


• refresh <interval>
  Time in seconds after which the HTML page is automatically reloaded. Defaults to 60. Set <interval> to 0 to disable reloading.


• viewport
  Adds a viewport directive to the HTML header.
  Example: attr FrameRSS viewport width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0
  This scales the image to fit to the browser's viewport and inhibits zooming in or out on tablets.


• noscroll
  Suppresses scrollbars in browsers, if set to 1.


• areas
  HTML code that goes into the image map.
  Example: attr FrameRSS areas <area shape="rect" coords="0,0,200,200" href="http://fhem.de"/><area shape="rect" coords="600,400,799,599" href="http://has:8083/fhem" target="_top"/>


• itemtitle
  Adds a title tag to the RSS item that contains the specified text.


• urlOverride
  Overrides the URL in the generated feed. If you specify attr <name> http://otherhost.example.org:8083/foo/bar, the JPEG picture that is at http://host.example.org:8083/fhem/rss/FrameRSS.jpg will be referenced as http://otherhost.example.org:8083/foo/bar/rss/FrameRSS.jpg. This is useful when your FHEM URLs are rewritten, e.g. if FHEM is accessed by a Reverse Proxy.




Usage information


If a least one RSS feed is defined, the menu entry RSS appears in the FHEMWEB side menu. If you click it you get a list of all defined RSS feeds. The URL of any such is RSS feed is http://hostname:port/fhem/rss/name.rss with hostname and name from the RSS feed's definition and the port (usually 8083) and literal /fhem from the underlying FHEMWEB definition.

Example:

http://host.example.org:8083/fhem/rss/FrameRSS.rss

The media RSS feed points to a dynamically generated picture. The URL of the picture belonging to the RSS can be found by replacing the extension ".rss" in feed's URL by ".jpg" or ".png" depending on defined output format,

Example:

http://host.example.org:8083/fhem/rss/FrameRSS.jpg
http://192.168.100.200:8083/fhem/rss/FrameRSS.png

To render the picture the current, or, if tmin seconds have elapsed, the next JPEG picture from the directory bg is chosen and scaled to the dimensions given in size. The background is black if no usable JPEG picture can be found. Next the script in the layout definition is used to superimpose items on the background.

You can directly access the URL of the picture in your browser. Reload the page to see how it works.

The media RSS feed advertises to refresh after 1 minute (ttl). Some photo frames ignore it and use their preset refresh rate. Go for a photo frame with an adjustable refresh rate (e.g every 5 seconds) if you have the choice!

This is how the fhem config part might look like:

define ui FHEMWEB 8083 global

define FrameRSS RSS jpg host.example.org /etc/fhem/layout
attr FrameRSS size 800x600
attr FrameRSS bg /usr/share/pictures
attr FrameRSS tmin 10


Layout definition


The layout definition is a script for placing items on the background. It is read top-down. It consists of layout control commands and items placement commands. Layout control commands define the appearance of subsequent items. Item placement commands actually render items.

Everything after a # is treated as a comment and ignored. You can fold long lines by putting a \ at the end.

General notes


1. Use double quotes to quote literal text if perl specials are allowed.
2. Text alignment requires the Perl module GD::Text::Align to be installed. Text wrapping (in text boxes) require GD::Text::Wrap to be installed. Debian-based systems can install both with apt-get install libgd-text-perl.

Notes on coordinates


1. (0,0) is the upper left corner.
2. Coordinates equal or greater than 1 are considered to be absolute pixels, coordinates between 0 and 1 are considered to be relative to the total width or height of the picture.
3. Literal x and y evaluate to the most recently used x- and y-coordinate. See also moveto and moveby below.

Layout control commands

• moveto <x> <y>
  Moves most recently used x- and y-coordinate to the given absolute or relative position.


• moveby <x> <y>
  Moves most recently used x- and y-coordinate by the given absolute or relative amounts.


• font "<font>"
  Sets the font. <font> is the name of a TrueType font (e.g. Arial) or the full path to a TrueType font (e.g. /usr/share/fonts/truetype/arial.ttf), whatever works on your system.


• rgb "<color>"
  Sets the color. You can use { <perl special> } for <color>.


• pt <pt>
  Sets the font size in points. A + or - sign in front of the the number given for <pt> signifies a change of the font size relative to the current size. Otherwise the absolute size is set. You can use { <perl special> } for <pt>.


• thalign|ihalign|halign "left"|"center"|"right"
  Sets the horizontal alignment of text, image or both. Defaults to left-aligned. You can use { <perl special> } instead of the literal alignment control word.


• tvalign|ivalign|valign "top"|"center"|"base"|"bottom"
  Sets the vertical alignment of text, image or both. Defaults to base-aligned for text and top-aligned for image. You can use { <perl special> } instead of the literal alignment control word.


• linespace <space>
  Sets the line spacing in pixels for text boxes (see textbox item below).


• condition <condition>
  Subsequent layout control and item placement commands except for another condition command are ignored if and only if <condition> evaluates to false.


• push
  The current parameter set (position, color, font name and size, text alignment and line spacing) is put (saved) on top of a stack.


• pop
  The most recently saved (pushed) current parameter set is pulled from the top of the stack and restored.


• label <lbl>
  Define a label for this line – i.e. name this line <lbl>. This label can be used to jump back or forward to this line by the <goto> command.
  A counter is implicitly defined for every label. From <perl specials> it can be accessed with {$<lbl>}. Example: the hit count for label foo is in $foo. The counter starts with zero and is increased with every hit of the label.


• goto <lbl>
  goto <lbl> if { <perl special> }
  Jump back or forward to the line labelled <lbl>. The condition is optional. Example: goto foo if { $foo < 5 }. This can be used to create loops. Note: if the goto jumps forward to the label for the first time, the hit count is 0; if the goto jumps backward to the label for the first time, the hit count is already 1.


Item placement commands
• text <x> <y> <text>
  Renders the text <text> at the position (<x>, <y>) using the current font, font size and color. You can use { <perl special> } for <text> to fully access device readings and do some programming on the fly. See below for examples.


• textbox <x> <y> <boxwidth> <text>
  Same as before but text is rendered in a box of horizontal width <boxwidth>.


• textboxf <x> <y> <boxwidth> <bgcolor> <text>
  Same as before but the textbox will be filled with the given background color <bgcolor> before drawing the text. <bgcolor> can be used with { <perl special> } to evalute RGB value.


• time <x> <y>
  Renders the current time in HH:MM format.


• seconds <x> <y> <format>
  Renders the curent seconds. Maybe useful for a RSS Clock.


• date <x> <y>
  Renders the current date in DD.MM.YYYY format.


• line <x1> <y1> <x2> <y2> [<thickness>]
  Draws a line from position (<x1>, <y1>) to position (<x2>, <y2>) with optional thickness (default=1).


• rect <x1> <y1> <x2> <y2> [<filled>]
  Draws a rectangle with corners at positions (<x1>, <y1>) and (<x2>, <y2>), which is filled if the <filled> parameter is set and not zero.
  If x2 or y2 is preceeded with a + (plus sign) then the coordinate is relative to x1 or y1, or in other words, it is the width-1 or height-1 of the rectangle, respectively.


• img <x> <y> <['w' or 'h']s> <imgtype> <srctype> <arg>
  Renders a picture at the position (<x>, <y>). The <imgtype> is one of gif, jpeg, png, svg. The picture is scaled by the factor <s> (a decimal value). If 'w' or 'h' is in front of scale-value the value is used to set width or height to the value in pixel. If <srctype> is file, the picture is loaded from the filename <arg>, if <srctype> is url or urlq, the picture is loaded from the URL <arg> (with or without logging the URL), if <srctype> is data, the picture is piped in from data <arg>. You can use { <perl special> } for <arg>. See below for example.
  Warning: do not load the image from URL that is served by fhem as it leads to a deadlock.


• embed <x> <y> <z> <position> <id> <element>
  For HTML output: embeds a div element into the HTML page at (<x>,<y>) with z-order <z> and positioning <position> (use absolute). <id> is the id attribute of the div element and <element> is its content.
  Note: There are several issues with different browsers when using this.


Example

This is how a layout definition might look like:

font /usr/share/fonts/truetype/arial.ttf # must be a TrueType font
rgb "c0c0c0" # HTML color notation, RGB
pt 48 # font size in points
time 0.10 0.90
pt 24
text 0.10 0.95 { ReadingsVal("MyWeather","temperature","?"). "C" }
moveby 0 -25
text x y "Another text"
img 20 530 0.5 png file { "/usr/share/fhem/www/images/weather/" . ReadingsVal("MyWeather","icon","") . ".png" }
embed 0 0 2 absolute plot1 { plotFromUrl('mySVG') }
embed 10 200 2 absolute iframe1 "<iframe width=\"420\" height=\"315\" src=\"//www.youtube.com/embed/9HShl_ufOFI\" frameborder=\"0\" allowfullscreen></iframe>"

Special uses

You can display SVG plots with the aid of the helper function plotAsPng(<name>[,<zoom>[,<offset>]]) (in 98_SVG.pm). Examples:

img 20 30 0.6 png data { plotAsPng("mySVGPlot") }
img 20 30 0.6 png data { plotAsPng("mySVGPlot","qday",-1) }

This requires the perl module Image::LibRSVG and librsvg. Debian-based systems can install these with apt-get install libimage-librsvg-perl.

You can display colorful icons with using the function FW_makeImage from the FHEMWEB API: img 40 200 h40 svg data {FW_makeImage('clock@blue')} For HTML output, you can use plotFromURL(<name>[,<zoom>[,<offset>]]) instead.

RandomTimer

[EN DE]

Define
define <name> RandomTimer <timespec_start> <device> <timespec_stop> <timeToSwitch> [<[VAR_DURATION][:VAR_START]>]
Defines a device, that imitates the random switch functionality of a timer clock, like a FS20 ZSU. The idea to create it, came from the problem, that is was always a little bit tricky to install a timer clock before holiday: finding the manual, testing it the days before and three different timer clocks with three different manuals - a horror.
By using it in conjunction with a dummy and a disableCond, I'm able to switch the always defined timer on every weekend easily from all over the world.


Description
a RandomTimer device starts at timespec_start switching device. Every (timeToSwitch seconds +-10%) it trys to switch device on/off. The switching period stops when the next time to switch is greater than timespec_stop.

Parameter
• timespec_start
  The parameter timespec_start defines the start time of the timer with format: HH:MM:SS. It can be a Perlfunction as known from the at timespec.


• device
  The parameter device defines the fhem device that should be switched.


• timespec_stop
  The parameter timespec_stop defines the stop time of the timer with format: HH:MM:SS. It can be a Perlfunction as known from the timespec at.


• timeToSwitch
  The parameter timeToSwitch defines the time in seconds between two on/off switches.
  Note: timeToSwitch will randomly vary by +-10% by default.


• variations
  The optional parameters variations will modify timeToSwitch and/or timespec_start, syntax is [VAR_DURATION][:VAR_START].
  
  • VAR_DURATION will turn timeToSwitch to a minimum value with some random seconds between zero and VAR_DURATION will be added.
  • VAR_START will modify timespec_start by adding some random number of seconds (between zero and VAR_START).
  Examples:
  Add something between 0 and 10 minutes to timeToSwitch:
  defmod Zufall1 RandomTimer *06:00 MYSENSOR_98 22:00:00 3600 600
  Randomize day's first check by up to half an hour:
  defmod Zufall1 RandomTimer *06:00 MYSENSOR_98 22:00:00 3600 :1800
  Do both:
  defmod Zufall1 RandomTimer *06:00 MYSENSOR_98 22:00:00 3600 600:1800
  

Examples
• define ZufallsTimerTisch RandomTimer *{sunset_abs()} StehlampeTisch +03:00:00 500
  defines a timer that starts at sunset an ends 3 hous later. Every 500 seconds(+-10%), the timer will perform an evaluation of the parameters to decide whether the device has to be switched or not.


• define ZufallsTimerTisch RandomTimer *{sunset_abs()} StehlampeTisch *{sunset_abs(3*3600)} 480
  defines a timer that starts at sunset and stops after sunset + 3 hours. The timer trys to switch every 480 seconds(+-10%).


• define ZufallsTimerTisch RandomTimer *{sunset_abs()} StehlampeTisch 22:30:00 300
  defines a timer that starts at sunset an ends at 22:30. The timer trys to switch every 300 seconds(+-10%).

Set

set <name> execNow
This will force the RandomTimer device to immediately execute the next switch instead of waiting untill timeToSwitch has passed. Use this in case you want immediate reaction on changes of reading values factored in disableCond. As RandomTimer itself will not be notified about any event at all, you'll need an additional event handler like notify that listens to relevant events and issues the "execNow" command towards your RandomTimer device(s).
NOTE: If the RandomTimer is disabled by attribute, this will not have any effect (different to set <name> active.)


set <name> active
Same effect than execNow, but will also delete a disable attribute if set.


set <name> inactive
Temporarily disable the RandomTimer w/o setting disable attribute. When set the next switch will be immediately executed.


set <name> recomputeTimes
Recalculate timespec_start and timespec_stop values. Might be helpfull in case you set timer limits in external devices (e.g. dummy).
Note: recomputing times will never issue any command towards <device>; esp.when shorting the time slot, make sure, your <device> is finally switched off.

Attributes
• disableCond
  The default behavior of a RandomTimer is, that it works. To set the Randomtimer out of work, you can specify in the disableCond attibute a condition in perlcode that must evaluate to true. The Condition must be put into round brackets. The best way is to define a function in 99_utils.
  
  Examples
  • attr ZufallsTimerZ disableCond (!isVerreist())
  • attr ZufallsTimerZ disableCond (ReadingsVal("presenceDummy","state","absent") eq "present")


• forceStoptimeSameDay
  When timespec_start is later then timespec_stop, it forces the timespec_stop to end on the current day instead of the next day. See forum post for use case.
  


• keepDeviceAlive
  The default behavior of a RandomTimer is, that it shuts down the device after stoptime is reached. The keepDeviceAlive attribute changes the behavior. If set, the device status is not changed when the stoptime is reached.
  
  Example
  • attr ZufallsTimerZ keepDeviceAlive


• disableCondCmd
  In case the disable condition becomes true while a RandomTimer is already running, by default the same action is executed as when stoptime is reached (see keepDeviceAlive attribute). Setting the disableCondCmd attribute changes this as follows: "none" will lead to no action, "offCmd" means "use off command", "onCmd" will lead to execution of the "on command". Delete the attribute to get back to default behaviour.
  
  Examples
  • attr ZufallsTimerZ disableCondCmd offCmd


• disabledForIntervals


• onCmd, offCmd
  Setting the on-/offCmd changes the command sent to the device. Default onCmd is set <device> on. The device can be specified by a @.
  
  Examples
  • attr Timer oncmd {fhem("set @ on-for-timer 14")}
    NOTE: using on-for-timer commands might lead to irritating results!
  • attr Timer offCmd {fhem("set @ off 16")}
  • attr Timer oncmd set @ pct 65
  • attr Timer offCmd set @ off 12
  The decision to switch on or off depends on the state of the device. For $featurelevel 6.0 and earlier, or if no offState attribute is set, this is evaluated by the funktion Value(<device>). Value() must evaluate one of the values "on" or "off". The behavior of devices that do not evaluate one of those values can be corrected by defining a stateFormat:
  attr stateFormat EDIPlug_01 {(ReadingsVal("EDIPlug_01","state","nF") =~ m/(ON|on)/i) ? "on" : "off" }
  if a devices Value() funktion does not evalute to on or off(like WLAN-Steckdose von Edimax) you get the message:
  [EDIPlug] result of function Value(EDIPlug_01) must be 'on' or 'off' NOTE: From $featurelevel 6.1 on or if attribute offState is set, the funktion ReadingsVal(<device>,"state",undef) will be used instead of Value(). If "state" of the device exactly matches the regex provided in the attribute "offState" or lowercase of "state" contains a part matching to "off", device will be considered to be "off" (or "on" in all other cases respectively).


• offState
  Setting this attribute, evaluation of on of will use ReadingsVal(<device>,"state",undef) instead of Value(). The attribute value will be used as regex, so e.g. also "dim00" beside "off" may be considered as indication the device is "off". You may use an optional second parameter (space separated) to check a different reading, e.g. for a HUEDevice-group "0 any_on" might be usefull.
  NOTE: This will be default behaviour starting with featurelevel 6.1.


• readingFnAttributes


• runonce
  Deletes the RandomTimer device after timespec_stop is reached.
  


• switchmode
  Setting the switchmode you can influence the behavior of switching on/off. The parameter has the Format 999/999 and the default ist 800/200. The values are in "per mill". The first parameter sets the value of the probability that the device will be switched on when the device is off. The second parameter sets the value of the probability that the device will be switched off when the device is on.
  
  Example
  • attr ZufallsTimerZ switchmode 400/400

Revolt NC-5462

[EN DE]

Provides energy consumption readings for Revolt NC-5462 devices via CUL or SIGNALduino (433MHz).

These devices send telegrams with measured values every few seconds. Many users saw problems with cheap 433MHz receivers - and even with good receivers, wrong values are received quite often, leading to outliers in plots and sporadic autocreation of devices with wrong IDs.

This module now ignores implausible telegrams (e.g. voltage below 80), but to further reduce outliers and event frequency, you should use the common attributes described below. You also might want to disable autocreation of Revolt devices once all of yours are detected.

Define
define <name> Revolt <id>

<id> is a 4 digit hex number to identify the NC-5462 device.
Note: devices are autocreated on reception of the first message.


Attributes
• ignore
• IODev
• do_not_notify
• showtime
• EnergyAdjustValue: adjust the energy reading (energy = energy - EnergyAdjustValue)

Common attributes
• event-aggregator: To reduce the high sending frequency and filter reception errors, you can use FHEM's event-aggregator. Common examples:
  • power:60:linear:mean,energy:36000:none:v reduce sampling frequency to one power event per minute and one energy value per 10 hours, other events can be disabled via event-on-change-reading or event-on-update-reading.
  • power::none:median:120,energy::none:median:120 keep sampling frequency untouched, but filter outliers using statistical median
• event-min-interval
• event-on-change-reading: can be used to disable events for readings you don't need. See documentation for details.
• event-on-update-reading: can be used to disable events for readings you don't need. See documentatino for details.
Readings
• energy [kWh]: Total energy consumption summed up in the NC-5462 devices. It seems you can't reset this counter and it will wrap around to 0 at 655.35 kWh. The EnergyAdjustValue attribute (see above) allows to adapt the reading, e.g. when you connect a new device.
• power [W]
• voltage [V]
• current [A]
• frequency [Hz]
• Pf: Power factor

Robonect

[EN DE]

Robonect is a after-market wifi-module for robomowers based on the husky G3-control. It was developed by Fabian H. and can be optained at www.robonect.de. This module gives you access to the basic commands. This module will not work without libjson-perl! Do not forget to install it first!

Define

define <name> Robonect <ip-adress or name>

Setting Winterschlaf prevents communicating with the mower.

The authentication can be supplied in the definition as plaine text or in a differen way - see the attributes. Per default the status is polled every 90s.

Example:

      define myMower Robonect 192.168.13.5
	  define myMower Robonect myMowersDNSName
      

Set

Set
• auto
  Sets the mower to automatic mode. The mower follows the internal timer, until another mode is chosen. The mower can be stopped with stop at any time. After using stop: be aware, that it continues mowing only if the timer supplies an active slot AND start is executed before.
• manuell
  This sets the mower to manual mode. The internal timer is ignored. Mowing starts with start and ends with stop.
• home
  This sends the mower directly home. Until you switch to auto or manuell, no further mowing work is done.
• feierabend
  This sends the mower home for the rest of the actual timeslot. At the next active timeslot mowing is continued automatically.
• start
  Start mowing in manual mode or in automatic mode at active timer-slot.
• stop
  Stops mowing immediately. The mower does not drive home. It stands there, until battery is empty. Use with care!
• maehauftrag
  This command starts a single mowing-task. It can be applied as much parameters as you want. For example you can influence start-/stop-time and duration.
  The parameters have to be named according the robonect-API (no doublechecking!).
  
  Example:
  Lauch at 15:00, Duration 120 minutes, do not use a remote-start-point, do not change mode after finishing task

  			  set myMower maehauftrag start=15:00 duration=120 remotestart=0 after=4
  			

• winterschlaf <on, off>
  If set to on, no polling is executet. Please use this during winter.
• user <user>
  One alternative to store authentication: username for robonect-logon is stored in FhemUtils or database (not encrypted).
  
• password <password>
  One alternative to store authentication: password for robonect-logon is stored in FhemUtils or database (not encrypted).
  

Get

Get
• status
  Gets the actual state of the mower - normally not needed, because the status is polled cyclic.
• health
  This one gets more detailed information - like voltages and temperatures. It is NOT SUPPORTED BY ALL MOWERS!!!
  If enabled via attribute, health is polled accordingly status.

Attributes


Common attributes:
DbLogInclude
DbLogExclude
IODev
alias
comment
devStateIcon
devStateStyle
do_not_notify
readingFnAttributes
event-aggregator
event-min-interval
event-on-change-reading
event-on-update-reading
eventMap
group
icon
room
showtime
sortby
stateFormat
userReadings
userattr
verbose
webCmd
widgetOverride



credentials

If you supply a valid path to a credentials file, this combination is used to log in at robonect. This mechism overrules basicAuth.

basicAuth

You can supply username and password plain or base-64-encoded. For a base64-encoder, use google.

Example:

      define myMower Robonect 192.168.5.1
	  attr myMower basicAuth me:mySecret
      

      define myMower Robonect 192.168.5.1
	  attr myMower basicAuth bWU6bXlTZWNyZXQ=
      

pollInterval

Supplies the interval top poll the robonect in seconds. Per default 90s is set.

timeout

Timeout for httpData to recive data. Default is 4s.

useHealth

If set to 1, the health-status of the mower will be polled. Be aware NOT ALL MOWERS ARE SUPPORTED!
Please refer to logfile or LAST_COMM_STATUS if the function does not seem to be working.

S7

[EN DE]

This module connects a SIEMENS PLC (S7,S5,SIEMENS Logo!). The TCP communication (S7, Siemens LOGO!) module is based on settimino (http://settimino.sourceforge.net). The serial Communication is based on a libnodave portation.

 

You can found a german wiki here: httl://www.fhemwiki.de/wiki/S7

For the communication the following modules have been implemented:
• S7 … sets up the communication channel to the PLC
• S7_ARead … Is used for reading integer Values from the PLC
• S7_AWrite … Is used for write integer Values to the PLC
• S7_DRead … Is used for read bits
• S7_DWrite … Is used for writing bits.

Reading work flow:

The S7 module reads periodically the configured DB areas from the PLC and stores the data in an internal buffer. Then all reading client modules are informed. Each client module extracts his data and the corresponding readings are set. Writing work flow:

At the S7 module you need to configure the PLC writing target. Also the S7 module holds a writing buffer. Which contains a master copy of the data needs to send.

 

(Note: after configuration of the writing area a copy from the PLC is read and used as initial fill-up of the writing buffer)

 

Note: The S7 module will send always the whole data block to the PLC. When data on the clients modules is set then the client module updates the internal writing buffer on the S7 module and triggers the writing to the PLC.

Definedefine <name> S7 <PLC_address> <rack> <slot> [<Interval>]

define logo S7 10.0.0.241 2 0

• PLC_address … IP address of the S7 PLC (For S5 see below)
• rack … rack of the PLC
• slot … slot of the PLC
• Interval … Intervall how often the modul should check if a reading is required

 

Note: For Siemens logo you should use a alternative (more simply configuration method):

 

define logo S7 LOGO7 10.0.0.241

 

Note: For Siemens S5 you must use a alternative (more simply configuration method):

 

define logo S7 S5 /dev/tty1 in this case the PLC_address is the serial port number

Attr

The following attributes are supported:

 

• MaxMessageLength
• receiveTimeoutMs
• Intervall

 

MaxMessageLength ... restricts the packet length if lower than the negioated PDULength. This could be used to increate the processing speed. 2 small packages may be smaler than one large package
receiveTimeoutMs ... timeout in ms for TCP receiving packages. Default Value 500ms. 
Intervall ... polling intervall in s 

S7_ARead

[EN DE]

This module is a logical module of the physical module S7.
This module provides analog data (signed / unsigned integer Values).
Note: you have to configure a PLC reading at the physical module (S7) first.


Define
define <name> S7_ARead {inputs|outputs|flags|db} <DB> <start> {u8|s8|u16|s16|u32|s32}


• inputs|outputs|flags|db … defines where to read.
• DB … Number of the DB
• start … start byte of the reading
• {u8|s8|u16|s16|u32|s32} … defines the datatype:
• u8 …. unsigned 8 Bit integer
• s8 …. signed 8 Bit integer
• u16 …. unsigned 16 Bit integer
• s16 …. signed 16 Bit integer
• u32 …. unsigned 32 Bit integer
• s32 …. signed 32 Bit integer
Note: the required memory area (start – start + datatypelength) need to be with in the configured PLC reading of the physical module.

Attr
The following parameters are used to scale every reading

• multiplicator
• offset
newValue = <multiplicator> * Value + <offset>

S7_AWrite

[EN DE]

This module is a logical module of the physical module S7.

This module provides sending analog data (unsigned integer Values) to the PLC.

Note: you have to configure a PLC writing at the physical modul (S7) first.

Define
define <name> S7_AWrite {inputs|outputs|flags|db} <DB> <start> {u8|s8|u16|s16|u32|s32|float}

• db … defines where to read. Note currently only writing in to DB are supported.
• DB … Number of the DB
• start … start byte of the reading
• {u8|s8|u16|s16|u32|s32} … defines the datatype:
• u8 …. unsigned 8 Bit integer
• s8 …. signed 8 Bit integer
• u16 …. unsigned 16 Bit integer
• s16 …. signed 16 Bit integer
• u32 …. unsigned 32 Bit integer
• s32 …. signed 32 Bit integer
• float …. 4 byte float
Note: the required memory area (start – start + datatypelength) need to be with in the configured PLC writing of the physical module.

Logo 7 / Logo 8

For Logo7 / Logo 8 also a short notation is supportet:

define <name> S7_AWrite {AI|AM|AQ|NAI|NAQ}X

Set

set <name> S7_AWrite <value>

• value … an numeric value

S7_Client

[EN DE]

abstract interface layer S7 / S5

S7_DRead

[EN DE]

This module is a logical module of the physical module S7.
This module provides digital data (ON/OFF).
Note: you have to configure a PLC reading at the physical modul (S7) first.


Define
define <name> S7_DRead {inputs|outputs|flags|db} <DB> <address>
• inputs|outputs|flags|db … defines where to read.
• DB … Number of the DB
• address … address you want to read. bit number to read. Example: 10.3
Note: the required memory area need to be with in the configured PLC reading of the physical module.

S7_DWrite

[EN DE]

This module is a logical module of the physical module S7.

This module is used to set/unset a Bit in ad DB of the PLC.

Note: you have to configure a PLC writing at the physical modul (S7) first.

Definedefine <name> S7_DWrite {db} <DB> <address>

• db … defines where to read. Note currently only writing in to DB are supported.
• DB … Number of the DB
• address … address you want to write. bit number to read. Example: 10.6
Note: the required memory area need to be with in the configured PLC reading of the physical module.

Setset <name> S7_AWrite {ON|OFF|TRIGGER};

Note: TRIGGER sets the bit for 1s to ON than it will set to OFF.

Attr
The following parameters are used to scale every reading

• trigger_length ... sets the on-time of a trigger in Seconds. Note out can also use trigger_length less than 1

S7_S5Client

[EN DE]

low level interface to S5

S7_S7Client

[EN DE]

low level interface to S7

SCIVT

[EN DE]

Define
define <name> SCIVT <SCD-device>

Define a SCD series solar controler device. Details see here. You probably need a Serial to USB controller like the PL2303.
Defining an SCIVT device will schedule an internal task, which reads the status of the device every 5 minutes, and triggers notify/filelog commands.
Note: Currently this device does not support a "set" function, only a single get function which reads the device status immediately.

Example:
define scd SCIVT /dev/ttyUSB2



Set
N/A

Get
get SCVIT data


Attributes
• model (SCD)

SD_BELL

[EN DE]

The module SD_BELL is a universal module of the SIGNALduino for different bells.

Currently, the following models are supported:
• wireless doorbell TCM 234759 Tchibo [Protocol 15]
• FreeTec PE-6946 [Protocol 32]
• Elro (Smartwares) Doorbell DB200 / 16 melodies - unitec Modell:98156+98YK [Protocol 41]
• Pollin 551227 [Protocol 42]
• m-e doorbell fuer FG- and Basic-Serie [Protocol 57]
• Heidemann | Heidemann HX | VTX-BELL_Funkklingel [Protocol 79]
• Grothe Mistral SE 01.1 (40 bit), 03.1 (48 bit) [Protocol 96]
• GEA-028DB [Protokoll 98]
• AVANTEK DB-LE [Protokoll 112]

Special feature Protocol 41, 2 different codes will be sent one after the other!


Define

define <NAME> SD_BELL <protocol> <hex-adresse>

Examples:
define <NAME> SD_BELL 32 68C1DA
define <NAME> SD_BELL 41 754485D3_08E8D593
define <NAME> SD_BELL 79 A3C


Set

ring

Get

N/A

Attribute

• do_not_notify
• ignore
• IODev
• model
  The attribute indicates the model type of your device.
  
• repeats
  This attribute can be used to adjust how many repetitions are sent. Default is 5.
  (For the model Heidemann_|_Heidemann_HX_|_VTX-BELL, the value repeats is fixed at 135!)

SD_GT

[EN DE]

The SD_GT module decodes and sends messages using the GT-9000 protocol. This protocol is used by a variety of remote controls, which are traded under different names. The messages are received and sent by a SIGNALduino.

The following models are currently known that use this protocol:


• EASY HOME RCT DS1 CR-A 3725
• Globaltronics GT-3000, GT-9000
• OBI Emil Lux / CMI Art.Nr.: 315606
• SilverCrest FSS B 20-A (3726) / 66538
• Tec Star Modell 2335191R
• uniTEC 48110 Funkfernschalterset (Receiver 55006x10, Transmitter: 50074)

New devices are usually automatically created in FHEM via autocreate. Since the protocol uses encryption, manual setup is virtually impossible.

The remote control is set up in a learning process. After receiving at least 5 messages within 3 minutes, a new device "SD_GT_LEARN" will be created. Setting up the individual buttons of the remote control starts after receiving another 6 different messages. This learning process is signaled with the status "learned code 4, please press another button", whereby the counter displays the number of currently registered codes.
All buttons of the remote control must now be pressed several times. Upon successful decoding of the radio signals, the individual keys are created.

The programming of the remote control is finished, if all key levels (A, B, C, D and possibly all) are created and the commands "on" and "off" are displayed. For each device, the Readings "CodesOn" and "CodesOff" must be set up with at least one code each. Without these learned codes no sending is possible.
The device "SD_GT_LEARN" is no longer needed and can be deleted.

If several remote controls are to be taught in, this process must be carried out separately for each remote control. The "SD_GT_LEARN" device must be deleted before starting to learn a new remote control.



Attribute:

• IODev - Sets the IO or physical device to be used to send signals to this logical device.
• disableSetAllFunction - Disables the function of the "all" button to switch all devices.
• do_not_notify - Disable FileLog/notify/inform notification for a device.
• ignore - Ignores the device, e.g. if it belongs to the neighbor. The device does not trigger FileLogs/Notifications.
• repeats - Number of repetitions of the send commands
• showtime - Used in the FHEMWEB to show the time of the last activity instead of the status in the overall view.




Readings:

• CodesOff: one to four hexadecimal codes for "off" that have been taught and used for sending
• CodesOn: one to four hexadecimal codes for "on" that have been learned and used for sending
• SendCode: the last sent code
• SystemCode: System code hexadecimal, the same for all buttons on a remote control
• SystemCodeDec: System code in decimal representation
• Version: Version of the encryption used
• state: State, "on" or "off"

SD_RSL

[EN DE]

The SD_RSL module decrypts and creates Conrad RSL messages sent / received by a SIGNALduino device.
If autocreate is used, a device "<code>_ALL" like RSL_74A400_ALLis created instead of channel and button = 4.

Define

define <name> SD_RSL <code>_<channel>[_<button>] <optional IODEV>

<name> is any name assigned to the device. For a better overview it is recommended to use a name in the form "RSL_B1A800_1_2"

<code> The code is 00000-FFFFFF

<channel> The channel is 1-4 or ALL

<button> The button is 1-4

Set

set <[on|off|toggle]>
Switches the device on or off.

set <[on-for-timer|off-for-timer|on-till|off-till|blink|intervals]>
Switches the socket for a specified duration. For Details see set extensions.

Get

N/A

Attribute

• IODev
• do_not_notify
• eventMap
• ignore
• readingFnAttributes
• RSLrepetition
  Set the repeats for sending signal.

SD_UT

[EN DE]

The module SD_UT is a universal module of SIGNALduino for devices or sensors.
After the first creation of the device unknown_please_select_model, the user must define the device himself via the model attribute.
If the device is not supported yet, bit data can be collected with the unknown_please_select_model device.

Note: As soon as the attribute model of a defined device is changed or deleted, the module re-creates a device of the selected type, and when a new message is run, the current device is deleted. Devices of the same or different type with the same deviceCode will result in errors. PLEASE use different deviceCode.

The following devices are supported:

• AC114-01 remote control   (module model: AC114_01, protocol 56)
• Atlantic Security sensors   (module model: MD-2003R, MD-2018R,MD-210R, protocol 91|91.1)
     Note: The model MD_230R (water) is recognized as MD-2018R due to the same hardware ID!
• BeSmart S4 remote control   (module model: BeSmart_S4, protocol 78)
• BF-301 remote control   (module model: BF_301, protocol 105)
• BOSCH ceiling fan   (module model: SF01_01319004_Typ2, protocol 86)
• Busch-Transcontrol HF - remote control 6861   (module model: TC6861, protocol 121)
• CAME swing gate drive   (module model: CAME_TOP_432EV, protocol 86)
• ChiliTec LED X-Mas light   (module model: Chilitec_22640, protocol 14)
• DC-1961-TG - remote control with 12 buttons for ceiling fan with lighting   (module model: DC_1961_TG, protocol 20)
• ESTO ceiling lamp   (module model: KL_RF01, protocol 93)
• Remote control with 4 buttons for diesel heating   (module model: RCnoName20, protocol 20)
• Remote control with 10 buttons for Leroy ceiling fan   (module model: RCnoName20_10, protocol 20)
• Remote control with 12 buttons for ceiling fan   (module model: RCnoName128, protocol 128)
• Remote control with 14 buttons for ceiling fan   (module model: RCnoName127, protocol 127)
• Hoermann HS1-868-BS   (module model: HS1_868_BS, protocol 69)
• Hoermann HSM4   (module model: HSM4, protocol 69)
• Krinner LUMIX X-Mas light string   (module model: Krinner_LUMIX, protocol 92)
• LED_XM21_0 X-Mas light string   (module model: LED_XM21_0, protocol 76)
• TR401 (Well-Light, remote control with 4 buttons)   (module model: TR401, protocol 114)
• TR-502MSV (LIDL, LIBRA, MANDOLYN, QUIGG), compatible GT-7008BS, GT-FSI-04, DMV-7008S, Powerfix RCB-I 3600   (module model: TR_502MSV, protocol 34)
• Manax RCS250   (module model: RC_10, protocol 90)
• Medion OR28V   (module model: OR28V, protocol 68)
• Meikee remote controls (Protokoll 118)
  • Meikee, 21 buttons, e.g. for Solar Flood Lights - module model: Meikee_21
  • Meikee, 24 buttons, e.g. for RGB LED Wallwasher Light - module model: Meikee_24
• mumbi AFS300-s (remote control RC-10, wireless socket RCS-22GS)   (module model: RC_10, protocol 90)
• Momento (remote control for wireless digital picture frame)   (module model: Momento, protocol 97)
• NAVARIS touch light switch Model No.: 44344.04   (module model: Navaris, protocol 99)
• NEFF or Refsta Topdraft (Tecnowind) kitchen hood   (module model: SF01_01319004, protocol 86)
• Novy Cloud 230 kitchen hood   (module model: Novy_840039, protocol 86)
• Novy Pureline 6830 kitchen hood   (module model: Novy_840029, protocol 86)
• QUIGG DMV-7000   (module model: QUIGG_DMV, protocol 34)
• SA-434-1 mini 923301   (module model: SA_434_1_mini, protocol 81)
• Techmar Garden Lights    (module model: Techmar, protocol 95)
• Tedsen Teletaster (protocol 46):
  • SKX1xx, 1 button - module model: Tedsen_SKX1xx
  • SKX2xx, 2 button (GEIGER_GF0x01) - module model: Tedsen_SKX2xx
  • SKX4xx, 4 button (GEIGER_GF0x02) - module model: Tedsen_SKX4xx
  • SKX6xx, 6 button (GEIGER_GF0x03) - module model: Tedsen_SKX6xx
• unitec magnetic contact 47031 (for alarm systems Unitec 47121, Unitec 47125, Friedland)   (module model: Unitec_47031, protocol 30)
• Visivo remote control for motorized screen   (module model: Visivo, protocol 24)
• Westinghouse ceiling fan (remote control, 5 buttons without SET)   (module model: Buttons_five, protocol 29)
• Westinghouse ceiling fan (remote control, 6 buttons with light dimmer)   (module model: Buttons_six, protocol 29)
• Westinghouse Delancey ceiling fan (remote control, 9 buttons with SET)   (module model: RH787T, protocol 83)
• Westinghouse ceiling fan Bendan (remote control TR60C-1, touch screen)   (module model: TR60C1, protocol 104)
• xavax 00111939 (remote control, 10 button)   (module model: xavax, protocol 26)


Define

define <NAME> SD_UT <model> <Hex-address>

examples:
define <NAME> SD_UT RH787T A
define <NAME> SD_UT SA_434_1_mini ffd
define <NAME> SD_UT unknown



Set

Different transmission commands are available.

BOSCH (SF01_01319004_Typ2), NEFF / Refsta Topdraft (SF01_01319004)
• delay: button 1 on the remote
• interval: button 2 on the remote
• light_on_off: button 3 on the remote
• minus: button 4 on the remote
• plus: button 5 on the remote

ChiliTec LED X-Mas light
• power_on: button ON on the remote
• power_off: button OFF on the remote
• flickering_slowly: button SL on the remote
• flickering_fast: button SF on the remote
• brightness_minus: button - on the remote
• brightness_plus: button + on the remote

ESTO KL_RF01
• on: button ON on the remote
• off: button OFF on the remote
• alternating_full_luminosity: button alternating_full_luminosity on the remote
• full_brightness: button full_brightness on the remote
• light_color_warm_white: button light_color_warm_white on the remote
• light_color_cold_white: button light_color_cold_white on the remote
• dimup: button DIMUP on the remote
• dimdown: button DIMDOWN on the remote
• night_mode: button moon on the remote

LED_XM21_0 light string
• on: button I on the remote
• off: button O on the remote

Remote control SA-434-1 mini 923301, Hoermann HS1-868-BS, Tedsen_SKX1xx
• send: button (Always send the same, even if the user sends another set command via console.)

Hoermann HSM4 (Remote control with 4 button)
• button_1: button 1 on the remote
• button_2: button 2 on the remote
• button_3: button 3 on the remote
• button_4: button 4 on the remote

Techmar Garden Lights (Remote control with 10 button)
• Group_1 ... Group_9: Group 1 to 9, on / off
• All_on / All_off: All Groups on / off

Westinghouse ceiling fan (Remote control with 5 button)
• 1_fan_low_speed: button 1/LOW on the remote
• 2_fan_medium_speed: button 2/MED on the remote
• 3_fan_high_speed: button 3/HI on the remote
• fan_off: turns off the fan
• light_on_off: switch light on or off
• light_dimm: light dimm

Westinghouse Delancey ceiling fan (Remote control RH787T with 9 button + SET)
• 1_fan_minimum_speed: button I on the remote
• 2_fan_low_speed: button II on the remote
• 3_fan_medium_low_speed: button III on the remote
• 4_fan_medium_speed: button IV on the remote
• 5_fan_medium_high_speed: button V on the remote
• 6_fan_high_speed: button VI on the remote
• fan_off: turns off the fan
• fan_direction: defining the direction of rotation
• light_on_off: switch light on or off
• set: button SET on the remote


Get

N/A


Attributes

• do_not_notify
• ignore
• IODev
• model
  The attribute indicates the model type of your device (AC114_01B, BeSmart_S4, Buttons_five, Buttons_six, CAME_TOP_432EV, Chilitec_22640, DC_1961_TG, HS1-868-BS, HSM4, KL_RF01, LED_XM21_0, Meikee_21, Meikee_24, Momento, Navaris, Novy_840029, Novy_840039, OR28V, QUIGG_DMV, RC_10, RH787T, SA_434_1_mini, SF01_01319004, TC6861, TR60C1, Tedsen_SKX1xx, Tedsen_SKX2xx, Tedsen_SKX4xx, Tedsen_SKX6xx, TR_502MSV, Unitec_47031, unknown).
  If the attribute is changed, a new device is created using autocreate. Autocreate must be activated for this.
• repeats
  This attribute can be used to adjust how many repetitions are sent. Default is 5. Valid values are 1-99.
• UTclock
  This attribute set the base clock when sending. There is no standard value.
  Exception: The model Novy_840039 has a preset base clock of 375. You can manually adjust this individually with this attribute.
• UTfrequency
  An individual transmission frequency can be set with this attribute. If this attribute is not set, the transmission frequency of the IO device (e.g. Signalduino) is used. Valid values 300.00-999.99 Mhz.


Generated readings of the models

AC114-01, Buttons_five, Buttons_six, CAME_TOP_432EV, Chilitec_22640, HSM4, KL_RF01, LED_XM21_0, Meikee_xx, Momento, Novy_840029, Novy_840039, OR28V, QUIGG_DMV, RC_10, RH787T, SF01_01319004, SF01_01319004_Typ2, TR401, TR_502MSV, Visivo
• deviceCode: Device code of the system
• LastAction: Last executed action of the device (receive for command received | send for command send).
• state: Current state of the device

MD_2003R (gas), MD_2018R (vibration), MD_210R (door/window switch), MD_230R (water)
• contact: State of the internal alarm contact.
• deviceTyp: Model type of the sensor.
• sabotage: State of sabotage contact.
• state: Current state of the device

HS1-868-BS, SA_434_1_mini, Tedsen_SKX1, Tedsen_SKX2xx, Tedsen_SKX4xx, Tedsen_SKX6xx
• LastAction: Last executed action of the device (receive for command received | send for command send).
• state: Current state of the device

Unitec_47031
• System-Housecode: System or house code of the device
• state: Condition of contact (prepared, unconfirmed)
• Zone: Zone of the device
• Usersystem: Group of the system

Weather Sensors various protocols

[EN DE]

The SD_WS module processes the messages from various environmental sensors received from an IO device (CUL, CUN, SIGNALDuino, SignalESP etc.).

Known models:
• ADE WS1907 Weather station with rain gauge
• Atech wireless weather station
• BBQ temperature sensor GT-TMBBQ-01s (transmitter), GT-TMBBQ-01e (receiver)
• Bresser 5-in-1, 6-in-1 and 7-in-1 Comfort Weather Center, 7009994, Professional rain gauge, Temeo
• Conrad S522
• EuroChron EFTH-800, EFS-3110A (temperature and humidity sensor)
• Fine Offset WH51, aka ECOWITT WH51, aka Froggit DP100, aka MISOL/1 (soil moisture sensor)
• Fine Offset WH57, aka Froggit DP60, aka Ambient Weather WH31L (thunder and lightning sensor)
• Fine Offset WH31, aka Ambient Weather WH31E, aka ecowitt WH31 (temperature and humidity sensor)
• Fine Offset WH40, aka Ambient Weather WH40, aka ecowitt WH40 (Regen sensor)
• Fody E42 (temperature and humidity sensor)
• Inkbird IBS-P01R pool thermometer, ITH-20R
• NC-3911, NC-3912 refrigerator thermometer
• Opus XT300
• PV-8644 infactory Poolthermometer
• Renkforce E0001PA
• Rain gauge DROP TFA 47.3005.01 with rain sensor TFA 30.3233.01
• TECVANCE TV-4848
• Sainlogic Weather stations FT-0835, FT0300, FT-0310, FT020T, WS019T
• Thermometer FT007T, FT007TP, F007T, F007TP
• Thermo-Hygrometer FT007TH, F007TH
• TS-FT002 Water tank level monitor with temperature
• TX-EZ6 for Weatherstation TZS First Austria
• WH2, WH2A (TFA Dostmann/Wertheim 30.3157 (sold in Germany), Agimex Rosenborg 66796 (sold in Denmark),ClimeMET CM9088 (Sold in UK)
• Weatherstation Auriol IAN 283582 Version 06/2017 (Lidl), Modell-Nr.: HG02832D
• Weatherstation Auriol AHFL 433 B2, IAN 314695 (Lidl)
• Weatherstations and sensors TFA 30.3151, 30.3152, 30.3153, 30.3157, 30.3200, 30.3208.02, 30.3221.02, 30.3222.02, 30.3228.02, 30.3229.02, 30.3233.01, 30.3251.10, 35.1077.54.S2, 35.1140.01
• Wireless Grill Thermometer, Model name: GFGT 433 B1


Define


Newly received sensors are usually automatically created in FHEM via autocreate.
Sensors that support a channel number are created, for example, in the following form:
SD_WS_33_1
The 1 indicates that the sensor with channel 1 was created. Sensors that do not offer a channel selection are created without a channel number, such as:
SD_WS_108
If several sensors with no or the same channel number are received, so you can set the attribute "longids" with the SIGNALduino. It is also possible to set up the devices manually with the following command:

define <name> SD_WS <code>

<code> is the channel or individual identifier used to identify the sensor.



Generated readings:


Some devices may not support all readings, so they will not be presented

• adc (raw value from analog to digital converter)
• batteryChanged (1)
• batteryState (low or ok)
• batteryVoltage (battery voltage in volts)
• batteryPercent (battery level in %)
• brightness (kLux)
• channel (number of channel
• distance (distance in cm (protocol 111) or km (protocol 116)
• humidity (humidity (1-100 % only if available)
• humidityTrend (consistent, rising, falling)
• sendmode (automatic or manual)
• rain (l/m²))
• rain_total (l/m²))
• state (T: H: W: R:)
• temperature (°C)
• temperatureTrend (consistent, rising, falling)
• type (type of sensor)
• uv (ultraviolet radiation)
• windDirectionDegree (Wind direction, grad)
• windDirectionText (Wind direction, N, NNE, NE, ENE, E, ESE, SE, SSE, S, SSW, SW, WSW, W, WNW, NW, NNW)
• windGust (Gust of wind, m/s)
• windSpeed (Wind speed, m/s)


Attributes


• do_not_notify


• ignore


• max-deviation-hum
  (Default: 1, allowed values: 1,2,3,4,5,6,7,8,9,10,15,20,25,30,35,40,45,50)
  Maximum permissible deviation of the measured humidity from the previous value in percent.
  Since many of the sensors handled in the module do not have checksums, etc. send, it can easily come to the reception of implausible values. To intercept these, a maximum deviation from the last correctly received value can be set. Greater deviations are then ignored and result in an error message in the log file, such as an error message like this:
  SD_WS_TH_84 ERROR - Hum diff too large (old 60, new 68, diff 8)
  In addition to the set value, a value dependent on the difference of the reception times is added. This is 1.0% relative humidity per minute. This means e.g. if a difference of 8 is set and the time interval of receipt of the messages is 3 minutes, the maximum allowable difference is 11.
  Instead of the max-deviation-hum and max-deviation-temp attributes, the doubleMsgCheck_IDs attribute of the SIGNALduino can also be used if the sensor is well received. An update of the readings is only executed if the same values ??have been received at least twice.


• max-deviation-temp
  (Default: 1, allowed values: 1,2,3,4,5,6,7,8,9,10,15,20,25,30,35,40,45,50)
  Maximum permissible deviation of the measured temperature from the previous value in Kelvin.
  Explanation see attribute "max-deviation-hum".


• model
  (Default: other, currently supported sensors: E0001PA, S522, TFA_30.3251.10 and TX-EZ6)
  The sensors of the "SD_WS_33 series" use different positions for the battery bit and different readings. If the battery bit is detected incorrectly (low instead of ok), then you can possibly adjust with the model selection of the sensor.
  So far, 3 variants are known. All sensors are created by Autocreate as model "other". If you receive a Conrad S522, Renkforce E0001PA or TX-EZ6, then set the appropriate model for the proper processing of readings.
  Protocol 85 (SD_WS_85_THW) decodes two different sensor types: TFA 30.3222.02 (thermo-hygro-wind) and 30.3251.10 (wind). The attribute must be set to this value "TFA_30.3251.10" so that the wind direction is also displayed for the sensor TFA 30.3251.10.


• readingFnAttributes


• showtime



Set


• replaceBatteryForSec
  (Only available for devices whose SIGNALduinos have the "longids" attribute activated.)
  
  replaceBatteryForSec <seconds>
  
  Puts the device into battery change mode for <secondes>. The first unknown address with the same protocol that is received replaces the current device address.

Weather Sensors protocol #7

[EN DE]

The SD_WS07 module interprets temperature sensor messages received by a Device like CUL, CUN, SIGNALduino etc.

Known models:
• Auriol AFW 2 A1, IAN: 297514
• Eurochon EAS800z
• FreeTec outdoor module for weather station NC-7344
• Mebus HQ7312-2
• Technoline WS6750/TX70DTH
• TFA 30320902

New received devices are added in FHEM with autocreate.

The module writes from verbose 4 messages, if not possible values like humidity > 100% are decoded.

Define
The received devices are created automatically.
The ID of the device is _ or, if the longid attribute is specified, it is with a combination of channel and some random generated bits during powering the sensor.
If you want to use more sensors, than channels available, you can use the longid option to differentiate them.

Generated readings:
Some devices may not support all readings, so they will not be presented

• state (T: H:)
• temperature (°C)
• humidity: (the humidity 1-100)
• batteryState: (low or ok)
• channel: (the channelnumberf)

Attributes
• offset-temp
  This offset can be used to correct the temperature. For example: 10 means, that the temperature is 10 °C higher.
  
• offset-hum
  Works the same way as offset-temp.
  
• do_not_notify
• ignore
• showtime
• max-deviation-hum (Default:1, allowed values: 1,2,3,4,5,6,7,8,9,10,15,20,25,30,35,40,45,50)
  Maximum permissible deviation of the measured humidity from the previous value in percent.
  Since these sensors do not send checksums, it can easily lead to the reception of implausible values. To intercept these, a maximum deviation from the last correctly received value can be set. Larger deviations are then ignored and lead to an error message in the log file, such as this:
  SD_WS07_TH_1 ERROR - Hum diff too large (old 60, new 68, diff 8)
  In addition to the set value, a value dependent on the difference of the reception times is added. This is 1.0% relative humidity per minute. This means e.g. if a difference of 8 is set and the time interval of receiving the messages is 3 minutes, the maximum allowed difference is 11.
• max-deviation-temp (Default:1, allowed values: 1,2,3,4,5,6,7,8,9,10,15,20,25,30,35,40,45,50)
  Maximum permissible deviation of the measured temperature from the previous value in Kelvin.
  please refer max-deviation-hum
• readingFnAttributes


Instead of the attributes max-deviation-hum and max-deviation-hum, the doubleMsgCheck_IDs attribute of the SIGNALduino can also be used if the sensor is well received. An update of the readings is only executed if the same values ??have been received at least twice.

Set
N/A

Get
N/A

Wether Sensors protocol #9

[EN DE]

The SD_WS09 module interprets temperature sensor messages received by a Device like CUL, CUN, SIGNALduino etc.

Requires Perl-Modul Digest::CRC / Math::Trig

• cpan install Digest::CRC or
  sudo apt-get install libdigest-crc-perl
• cpan install Math::Trig


Known models:
• WS-0101 --> Model: WH1080
• TFA 30.3189 / WH1080 --> Model: WH1080
• 1073 (WS1080) --> Model: WH1080
• WH2315 --> Model: WH1080
• WH3080 --> Model: WH1080
• CTW600 --> Model: CTW600

New received device are add in fhem with autocreate.


Define
The received devices created automatically.
The ID of the defice is the model or, if the longid attribute is specified, it is a combination of model and some random generated bits at powering the sensor.
If you want to use more sensors, you can use the longid option to differentiate them.

Set
N/A

Get
N/A


Attributes
• do_not_notify
• ignore
• showtime
• readingFnAttributes
• Model: WH1080,CTW600
• windKorrektur: -3,-2,-1,0,1,2,3
• Unit_of_Wind
  Unit of windSpeed and windGuest. State-Format: Value + Unit.
  m/s,km/h,ft/s,mph,bft,knot


• WindDirAverageTime
  default is 600s, time span to be considered for the calculation


• WindDirAverageMinSpeed
  since the wind direction is usually not clear at very low wind speeds, minspeed can be used to specify a threshold value.
  The (weighted) mean velocity < minspeed is returned undef


• WindDirAverageDecay
  1 -> all values ​​are weighted equally
  0 -> only the current value is used.
  in practice, you will take values ​​around 0.75


• WS09_CRCAUS (set in Signalduino-Modul 00_SIGNALduino.pm)
  0: CRC-Check WH1080 CRC-Summe = 0 on, default
  2: CRC-Summe = 49 (x031) WH1080, set OK


Generated readings:
Some devices may not support all readings, so they will not be presented

• State (T: H: Ws: Wg: Wd: R: ) temperature, humidity, windSpeed, windGuest, windDirection, Rain
• Temperature (°C)
• Humidity: (The humidity (1-100 if available)
• Battery: (low or ok)
• ID: (The ID-Number (number if)
• windSpeed/windGuest (Unit_of_Wind)) and windDirection (N-O-S-W)
• Rain (mm)
• windDirectionAverage
  As a result, the wind direction is returned, which are calculated from the current and past values via a kind of exponential mean value. The respective wind speed is additionally taken into account (higher speed means higher weighting)

WH2315 / WH3080:
• UV Index
• Lux

BBQ Sensors protocol #47

[EN DE]

The SD_WS_Maverick module interprets temperature sensor messages received by a Device like CUL, CUN, SIGNALduino etc.

Known models:
• Maverick 732/733
• TFA 14.1504 (Radio-controlled grill and meat thermometer)

New received device will be added in fhem with autocreate (if autocreate is globally enabled).

Define
The received devices created automatically.
Maverick generates a random ID each time turned on. So it is not possible to link the hardware with the fhem-device. The consequence is, that only one Maverick can be defined in fhem.

Generated readings:
• State (Food: BBQ: )
• temp-food (°C)
• temp-bbq (°C)
• Sensor-1-food_state (connected, disconnected or inactive)
• Sensor-2-bbq_state (connected, disconnected or inactive)
• messageType (sync at startup or resync, otherwise normal)
• checksum (experimental)

Attributes
• inactivityinterval
  The Interval to set Sensor-1-food_state and/or Sensor-2-bbq_state to inactive after defined minutes. This can help to detect empty batteries or the malfunction of a tempertature-sensor.
  default: 360
• do_not_notify
• ignore
• showtime (see FHEMWEB)
• readingFnAttributes
Set
N/A

Parse
N/A

SHC

[EN DE]

SHC is the basestation module that supports a family of RF devices available at www.smarthomatic.org. This module provides the IODevice for the SHCdev modules that implement the SHCdev protocol.

Note: this module may require the Device::SerialPort or Win32::SerialPort module if you attach the device via USB and the OS sets strange default parameters for serial devices.
It also requires Digest::CRC because the communication to the basestation is secured by a CRC.

Define
define <name> SHC <device>

<device> specifies the serial port to communicate with the SHC. The name of the serial-device depends on your distribution, under linux usually a /dev/ttyUSB0 device will be created.

You can also specify a baudrate if the device name contains the @ character, e.g.: /dev/ttyUSB0@57600. Please note that the default baudrate for the SHC base station is 115200 baud.

Example:

define shc_base SHC /dev/ttyUSB0


Set
• raw <data>
  not supported yet


Get
• N/A


Attributes
• N/A

SHCdev

[EN DE]

SHC is the device module that supports several device types available at www.smarthomatic.org.

These device are connected to the FHEM server through the SHC base station (SHC).

Currently supported are:

• EnvSensor
• PowerSwitch
• Dimmer
• Controller
• RGBDimmer
• SoilMoistureMeter

Define
define <name> SHCdev <SenderID> [<AesKey>]

<SenderID>
is a number ranging from 0 .. 4095 to identify the SHCdev device.

<AesKey>
is a optional number ranging from 0 .. 15 to select an encryption key. It is required for the basestation to communicate with remote devides The default value is 0.

Note: devices are autocreated on reception of the first message.


Set
• on
  Supported by Dimmer and PowerSwitch (on always refers to pin1).


• off
  Supported by Dimmer and PowerSwitch (off always refers to pin1).


• pct <0..100>
  Sets the brightness in percent. Supported by Dimmer.


• ani <AnimationMode> <TimeoutSec> <StartBrightness> <EndBrightness>
  Description and details available at www.smarthomatic.org. Supported by Dimmer.


• statusRequest
  Supported by Dimmer and PowerSwitch.


• Color <ColorNumber>
  A detailed description is available at www.smarthomatic.org. The color palette can be found here Supported by RGBDimmer.


• ColorAnimation <Repeat> <AutoReverse> <Time0> <ColorNumber0> <Time1> <ColorNumber1> ... up to 10 time/color pairs
  A detailed description is available at www.smarthomatic.org. The color palette can be found here Supported by RGBDimmer.


• Tone <ToneNumber>
  A detailed description is available at www.smarthomatic.org. The tone definition can be found here Supported by RGBDimmer.


• Melody <Repeat> <AutoReverse> <Time0> <Effect0> <ToneNumber0> <Time1> <Effect1> <ToneNumber1> ... up to 25 time/effect/tone pairs
  A detailed description is available at www.smarthomatic.org. The tone definition can be found here Supported by RGBDimmer.


• Text <PosY> <PosX> <Format> <Text>
  A detailed description is available at www.smarthomatic.org. Supported by Controller.
  Note: Since FHEM parameters can't include spaces, there is a special form to enter them. To add a space to the text, use the underline character (e.g. 'Hello_world'). If you want to send an underline character, escape it with the backslash (e.g. '\_test\_').


• MenuSelection <Index00> <Index01> ... <Index15>
  A detailed description is available at www.smarthomatic.org. Supported by Controller.
  When the MenuSelection was initiated by the user with the controller, the reading menuSelectionDelivery will be set additionally to the index00, ... readings. This can be used to distinguish if the menu selection was user initiated or done programmatically by a FHEM "set" command, especially to keep more than one controller with the same options in sync reacting on a change of the menuSelectionDelivery reading.


• Backlight <Mode> <AutoTimeoutSec>
  A detailed description is available at www.smarthomatic.org. Supported by Controller.


• DigitalPin <Pos> <On>
  A detailed description is available at www.smarthomatic.org. Supported by PowerSwitch.


• DigitalPinTimeout <Pos> <On> <Timeout>
  A detailed description is available at www.smarthomatic.org. Supported by PowerSwitch.


• DigitalPort <On>
  <On>
  is a bit array (0 or 1) describing the port state. If less than eight bits were provided zero is assumed. Example: set SHC_device DigitalPort 10110000 will set pin0, pin2 and pin3 to 1.
  A detailed description is available at www.smarthomatic.org. Supported by PowerSwitch.


• DigitalPortTimeout <On> <Timeout0> .. <Timeout7>
  <On>
  is a bit array (0 or 1) describing the port state. If less than eight bits were provided zero is assumed. Example: set SHC_device DigitalPort 10110000 will set pin0, pin2 and pin3 to 1.
  <Timeout0> .. <Timeout7>
  are the timeouts for each pin. If no timeout is provided zero is assumed. A detailed description is available at www.smarthomatic.org. Supported by PowerSwitch.


• set extensions
  Supported by Dimmer and PowerSwitch.

Get
• din <pin>
  Returns the state of the specified digital input pin for pin = 1..8. Or the state of all pins for pin = all. Supported by EnvSensor.


• ain <pin>
  Returns the state of the specified analog input pin for pin = 1..5. Or the state of all pins for pin = all. If the voltage of the pin is over the specied trigger threshold) it return 1 otherwise 0. Supported by EnvSensor.


• ain <pin>
  Returns the state of the specified analog input pin for pin = 1..5. Or the state of all pins for pin = all. If the voltage of the pin is over the specied trigger threshold) it return 1 otherwise 0. Supported by EnvSensor.


• ain_volt <pin>
  Returns the voltage of the specified analog input pin for pin = 1..5 in millivolts, ranging from 0 .. 1100 mV. Supported by EnvSensor.



Attributes
• devtype
  The device type determines the command set, default web commands and the default devStateicon. Currently supported are: EnvSensor, Dimmer, PowerSwitch, RGBDimmer, SoilMoistureMeter.
  
  Note: If the device is not set manually, it will be determined automatically on reception of a device type specific message. For example: If a temperature message is received, the device type will be set to EnvSensor.


• readonly
  if set to a value != 0 all switching commands (on, off, toggle, ...) will be disabled.


• forceOn
  try to switch on the device whenever an off status is received.

SIGNALduino

[EN DE]

The SIGNALduino ia based on an idea from mdorenka published at FHEM Forum. With the opensource firmware (see this link) it is capable to receive and send different protocols over different medias. The following device support is currently available: Wireless switches ITv1 & ITv3/Elro and other brands using pt2263 or arctech protocol--> uses IT.pm In the ITv1 protocol is used to sent a default ITclock from 250 and it may be necessary in the IT-Modul to define the attribute ITclock ELV FS10 -> 10_FS10 ELV FS20 -> 10_FS20 Temperature / humidity sensors CTW600, WH1080 -> 14_SD_WS09 ELV WS-2000, La Crosse WS-7000 -> 14_CUL_WS Eurochon EAS 800z -> 14_SD_WS07 FreeTec Aussenmodul NC-7344 -> 14_SD_WS07 Hama TS33C, Bresser Thermo/Hygro Sensor -> 14_Hideki La Crosse WS-7035, WS-7053, WS-7054 -> 14_CUL_TX Oregon Scientific v2 and v3 Sensors -> 41_OREGON.pm PEARL NC7159, LogiLink WS0002,GT-WT-02,AURIOL,TCM97001, TCM27 and many more -> 14_CUL_TCM97001 Temperatur / humidity sensors suppored -> 14_SD_WS07 technoline WS 6750 and TX70DTH -> 14_SD_WS07 It is possible to attach more than one device in order to get better reception, fhem will filter out duplicate messages. See more at the global section with attribute dupTimeout Note: this module require the Device::SerialPort or Win32::SerialPort module. It can currently only attatched via USB.

Define

define <name> SIGNALduino <device>

USB-connected devices (SIGNALduino):

• <device> specifies the serial port to communicate with the SIGNALduino. The name of the serial-device depends on your distribution, under linux the cdc_acm kernel module is responsible, and usually a /dev/ttyACM0 or /dev/ttyUSB0 device will be created. If your distribution does not have a cdc_acm module, you can force usbserial to handle the SIGNALduino by the following command:
  • modprobe usbserial
  • vendor=0x03eb
  • product=0x204b
  In this case the device is most probably /dev/ttyUSB0.
  
  You can also specify a baudrate if the device name contains the @ character, e.g.: /dev/ttyACM0@57600
  
  This is also the default baudrate.
  It is recommended to specify the device via a name which does not change:
  e.g. via by-id devicename: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0@57600
  If the baudrate is "directio" (e.g.: /dev/ttyACM0@directio), then the perl module Device::SerialPort is not needed, and fhem opens the device with simple file io. This might work if the operating system uses sane defaults for the serial parameters, e.g. some Linux distributions and OSX.
  
  

Internals

• IDsNoDispatch: Here are protocols entryls listed by their numeric id for which not communication to a logical module is enabled. To enable, look at the menu option Display protocollist.
• LASTDMSGID: This shows the last dispatched Protocol ID.
• NR_CMD_LAST_H: Number of messages sent within the last hour.
• RAWMSG: last received RAWMSG
• cc1101_available: If a CC1101 was detected, this internal is displayed with the value 1.
• version: This shows the version of the SIGNALduino microcontroller.
• versionProtocols: This shows the version of SIGNALduino protocol file.
• versionmodule: This shows the version of the SIGNALduino FHEM module itself.

Set

• LaCrossePairForSec
(Only with CC1101 receiver)
Enable autocreate of new LaCrosse sensors for x seconds. If ignore_battery is not given only sensors sending the 'new battery' flag will be created.


• cc1101_bWidth / cc1101_dataRate / cc1101_deviatn / cc1101_freq / cc1101_patable / cc1101_rAmpl / cc1101_reg / cc1101_sens
  (Only with CC1101 receiver)
  Set the sduino frequency / bandwidth / PA table / receiver-amplitude / sensitivity
  Use it with care, it may destroy your hardware and it even may be illegal to do so. Note: The parameters used for RFR transmission are not affected.
  
  • cc1101_bWidth can be set to values between 58 kHz and 812 kHz. Large values are susceptible to interference, but make possible to receive inaccurately calibrated transmitters. It affects tranmission too. Default is 325 kHz.
  • cc1101_dataRate , can be set to values ​​between 0.0247955 kBaud and 1621.83 kBaud.
  • cc1101_deviatn , can be set to values ​​between 1.586914 kHz and 380.859375 kHz.
  • cc1101_freq sets both the reception and transmission frequency. Note: Although the CC1101 can be set to frequencies between 315 and 915 MHz, the antenna interface and the antenna is tuned for exactly one frequency. Default is 433.920 MHz (or 868.350 MHz). If not set, frequency from cc1101_frequency will be used.
  • cc1101_patable change the PA table (power amplification for RF sending)
  • cc1101_rAmpl is receiver amplification, with values between 24 and 42 dB. Bigger values allow reception of weak signals. Default is 42.
  • cc1101_reg You can set multiple registers at one. Specify the register with its two digit hex code followed by the register value separate multiple registers via space.
  • cc1101_sens is the decision boundary between the on and off values, and it is 4, 8, 12 or 16 dB. Smaller values allow reception of less clear signals. Default is 4 dB.


• close
  Closes the connection to the device.


• disableMessagetype
  Allows you to disable the message processing for
  • messages with sync (syncedMS)
  • messages without a sync pulse (unsyncedMU)
  • manchester encoded messages (manchesterMC)
  The new state will be saved into the eeprom of your arduino.


• enableMessagetype
  Allows you to enable the message processing for
  • messages with sync (syncedMS)
  • messages without a sync pulse (unsyncedMU)
  • manchester encoded messages (manchesterMC)
  The new state will be saved into the eeprom of your arduino.


• flash [hexFile|url]
  The SIGNALduino needs the right firmware to be able to receive and deliver the sensor data to fhem. In addition to the way using the arduino IDE to flash the firmware into the SIGNALduino this provides a way to flash it directly from FHEM. You can specify a file on your fhem server or specify a url from which the firmware is downloaded.
  
  There are some requirements:
  • avrdude must be installed on the host
    On a Raspberry PI this can be done with: sudo apt-get install avrdude
  • the hardware attribute must be set if using any other hardware as an Arduino nano
    This attribute defines the command, that gets sent to avrdude to flash the uC.
  • If you encounter a problem, look into the logfile
  
  Example:
  • flash via Version Name: Versions are provided via get availableFirmware
  • flash via hexFile: set sduino flash ./FHEM/firmware/SIGNALduino_mega2560.hex
  • flash via url for Nano with CC1101: set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC7/SIGNALDuino_nanocc1101.hex
  
  note model radino:
  • Sometimes there can be problems flashing radino on Linux. Here in the wiki under point "radino & Linux" is a patch!
  • If the Radino is defined in this way /dev/ttyACM0, the flashing of the firmware should be done automatically. If this fails, the boot loader must be activated manually:
  • To activate the bootloader of the radino there are 2 variants.
    • 1) modules that contain a BSL-button:
      • apply supply voltage
      • press & hold BSL- and RESET-Button
      • release RESET-button, release BSL-button
      • (repeat these steps if your radino doesn't enter bootloader mode right away.)
    • 2) force bootloader:
      • pressing reset button twice
    In bootloader mode, the radino gets a different USB ID. This must be entered in the "flashCommand" attribute.
    If the bootloader is enabled, it signals with a flashing LED. Then you have 8 seconds to flash.


• raw
  Issue a SIGNALduino firmware command, without waiting data returned by the SIGNALduino. See the SIGNALduino firmware code for details on SIGNALduino commands. With this line, you can send almost any signal via a transmitter connected To send some raw data look at these examples: P#binarydata#R#C (#C is optional)
  
  Example 1: set sduino raw SR;R=3;P0=500;P1=-9000;P2=-4000;P3=-2000;D=0302030; sends the data in raw mode 3 times repeated
  Example 2: set sduino raw SM;R=3;P0=500;C=250;D=A4F7FDDE; sends the data manchester encoded with a clock of 250uS
  Example 3: set sduino raw SC;R=3;SR;P0=5000;SM;P0=500;C=250;D=A4F7FDDE; sends a combined message of raw and manchester encoded repeated 3 times
  Example 4: set sduino raw SN;R=3;D=9A46036AC8D3923EAEB470AB; sends a xFSK message of raw and repeated 3 times
  
  note: The wrong use of the upcoming options can lead to malfunctions of the SIGNALduino!
  
  
  • CEA -> Switching on the automatic frequency control for FSK modulation and firmware version >= V 4.0.0 (config: AFC=1)
  • CDA -> Switching off the automatic frequency control for FSK modulation and firmware version >= V 4.0.0 (config: AFC=0)
  • CER -> turn on data compression (config: Mred=1)
  • CDR -> disable data compression (config: Mred=0)
  
  Register commands for a CC1101
  • e -> default settings
  • x -> returns the ccpatable
  • C -> reads a value from the CC1101 register
    
    example: set sduino raw C04 reads the value from register address 0x04
  • W -> writes a value to the EEPROM and the CC1101 register (note: The EEPROM address has an offset of 2)
    
    example 1: set sduino raw W041D write 1D to register 0x02
    example 2: set sduino raw W041D#W0604 write 1D to register 0x02 and write 04 to register 0x04
  
  other commands from uC
  • ? -> returns the available commands
  • P -> sends a PING
  • R -> returns the free RAM
  • V -> returns the version
  • s -> returns the status
  • t -> returns the uptime
  
  
• reset
  This will do a reset of the usb port and normaly causes to reset the uC connected.


• sendMsg
  This command will create the needed instructions for sending raw data via the signalduino. Insteaf of specifying the signaldata by your own you specify a protocol and the bits you want to send. The command will generate the needed command, that the signalduino will send this. It is also supported to specify the data in hex. prepend 0x in front of the data part.
  
  Please note, that this command will work only for MU or MS protocols. You can't transmit manchester data this way.
  
  Input args are:
  • P#binarydata#R#C (#C is optional)
    Example binarydata: set sduino sendMsg P0#0101#R3#C500
    Will generate the raw send command for the message 0101 with protocol 0 and instruct the arduino to send this three times and the clock is 500.
    SR;R=3;P0=500;P1=-9000;P2=-4000;P3=-2000;D=03020302;
  
  
  • P#0xhexdata#R#C (#C is optional)
    Example 0xhexdata: set sduino sendMsg P29#0xF7E#R4
    Generates the raw send command with the hex message F7E with protocl id 29 . The message will be send four times.
    SR;R=4;P0=-8360;P1=220;P2=-440;P3=-220;P4=440;D=01212121213421212121212134;
  
  
  • P#0xhexdata#R#C#F (#C #F is optional)
    Example 0xhexdata: set sduino sendMsg P36#0xF7#R6#Fxxxxxxxxxx (xxxxxxxxxx = register from CC1101)
    Generates the raw send command with the hex message F7 with protocl id 36 . The message will be send six times.
    SR;R=6;P0=-8360;P1=220;P2=-440;P3=-220;P4=440;D=012323232324232323;F= (register from CC1101);

Get

• availableFirmware
  Retrieves available firmware versions from github and displays them in set flash command.


• ccconf
  Read some CUL radio-chip (cc1101) registers (frequency, bandwidth, etc.), and display them in human readable form.
  Only with cc1101 receiver.


• ccpatable
  read cc1101 PA table (power amplification for RF sending)
  Only with cc1101 receiver.


• ccreg
  read cc1101 registers (99 reads all cc1101 registers)
  Only with cc1101 receiver.


• close
  Close the connection to the SIGNALduino.


• cmds
  Depending on the firmware installed, SIGNALduinos have a different set of possible commands. Please refer to the sourcecode of the firmware of your SIGNALduino to interpret the response of this command. See also the raw-command.


• config
  Displays the configuration of the SIGNALduino protocol category. | example: MS=1;MU=1;MC=1;Mred=0


• freeram
  Displays the free RAM.


• ping
  Check the communication with the SIGNALduino.


• rawmsg
  Processes messages (MS, MC, MU, ...) as if they were received by the SIGNALduino. The get raw command does not send any commands to the microcontroller!
  
  For example, this message would: MS;P0=-7871;P2=-1960;P3=578;P4=-3954;D=030323232323434343434323232323234343434323234343234343234343232323432323232323232343234;CP=3;SP=0;R=0;m=0;
  after executing the command several times, create a sensor SD_WS_33_TH_1.


• uptime
  Displays information how long the SIGNALduino is running. A FHEM reboot resets the timer.


• version
  return the SIGNALduino firmware version

Attributes

• addvaltrigger
  Create triggers for additional device values. Right now these are RSSI, RAWMSG, DMSG and ID.


• blacklist_IDs
  The blacklist works only if a whitelist not exist.


• cc1101_frequency
  Specify the frequency of your SIGNALduino. Default is 433 Mhz.
  Since the PA table values are frequency-dependent,the specified frequency will be used.


• cc1101_reg_user
  Storage space for individual register configurations or values. One or more values ​​can be saved.
  note: The value consists of the register address followed by the value. Multiple values ​​are separated by commas. example: 04D3,0591


• debug
  This will bring the module in a very verbose debug output. Usefull to find new signals and verify if the demodulation works correctly.


• development
  The development attribute is only available in development version of this Module for backwart compatibility. Use the whitelistIDs Attribute instead. Setting this attribute to 1 will enable all protocols which are flagged with developID=Y.
  To check which protocols are flagged, open via FHEM webinterface in the section "Information menu" the option "Display protocollist". Look at the column "dev" where the flags are noted.
  
  
• do_not_notify


• doubleMsgCheck_IDs
  This attribute allows it, to specify protocols which must be received two equal messages to call dispatch to the modules.
  You can specify multiple IDs wih a colon : 0,3,7,12
  


• dummy


• eventlogging
  With this attribute you can control if every logmessage is also provided as event. This allows to generate event for every log messages. Set this to 0 and logmessages are only saved to the global fhem logfile if the loglevel is higher or equal to the verbose attribute. Set this to 1 and every logmessages is also dispatched as event. This allows you to log the events in a seperate logfile.


• flashCommand
  This is the command, that is executed to performa the firmware flash. Do not edit, if you don't know what you are doing.
  If the attribute not defined, it uses the default settings. If the user defines the attribute manually, the system uses the specifications!
  
  • default for nano, nanoCC1101, miniculCC1101, promini: avrdude -c arduino -b [BAUDRATE] -P [PORT] -p atmega328p -vv -U flash:w:[HEXFILE] 2>[LOGFILE]
  • default for radinoCC1101: avrdude -c avr109 -b [BAUDRATE] -P [PORT] -p atmega32u4 -vv -D -U flash:w:[HEXFILE] 2>[LOGFILE]
  It contains some place-holders that automatically get filled with the according values:
  
  • [BAUDRATE]
    is the speed (e.g. 57600)
  • [PORT]
    is the port the Signalduino is connectd to (e.g. /dev/ttyUSB0) and will be used from the defenition
  • [HEXFILE]
    is the .hex file that shall get flashed. There are three options (applied in this order):
    - passed in set flash as first argument
    - taken from the hexFile attribute
    - the default value defined in the module
    
  • [LOGFILE]
    The logfile that collects information about the flash process. It gets displayed in FHEM after finishing the flash process
  
  note: ! Sometimes there can be problems flashing radino on Linux. Here in the wiki under the point "radino & Linux" is a patch!


• hardware
  Currently, there are serval hardware options with different receiver options available. The simple single wire option, consists of a single wire connected receiver and a single wire connected transmitter which are connected over a single digital port with the microcontroller. The receiver only sends data and the transmitter receives only from the microcontroller. The other option consists of the cc1101 (sub 1 GHZ) chip, which can transmit and receiver. It's a transceiver which is connected via spi. ESP8266 hardware type, currently doesn't support flashing out of the module and needs at leat 1 MB of flash.
  • esp32s: ESP32 with simple single wire receiver
  • esp32cc1101: ESP32 with CC1101 (spi connected) receiver
  • esp8266s: ESP8266 with simple single wire receiver
  • esp8266cc1101: ESP8266 with CC1101 (spi connected) receiver
  • MAPLEMINI_F103CBs: MapleMini F103CB (STM32 family) with simple single wire receiver
  • MAPLEMINI_F103CBcc1101: MapleMini F103CB (STM32 family) with CC1101 (spi connected) receiver
  • miniculCC1101: Arduino pro Mini with CC110x (spi connected) receiver and cables as a minicul
  • nano328: Arduino Nano 328 with simple single wired receiver
  • nanoCC1101: Arduino Nano 328 with CC110x (spi connected) receiver
  • promini8s: Arduino Pro Mini 328 8Mhz with simple single wired receiver
  • promini8cc1101: Arduino Pro Mini 328 8Mhz with CC110x (spi connected) receiver
  • promini16s: Arduino Pro Mini 328 16Mhz with simple single wired receiver
  • promini16cc1101: Arduino Pro Mini 328 16Mhz with CC110x (spi connected) receiver
  • radinoCC1101: Arduino compatible radino with cc1101 (spi connected) receiver


• longids
  Comma separated list of device-types for SIGNALduino that should be handled using long IDs. This additional ID allows it to differentiate some weather sensors, if they are sending on the same channel. Therfor a random generated id is added. If you choose to use longids, then you'll have to define a different device after battery change.
  
  
  Examples:

        # Default, use of long IDs is defined by logical modules. Mostly disabled except for OREGON:
        deleteattr sduino longids 
        # Do not use any long IDs for any devices:
        attr sduino longids 0
        # Use any long IDs for all devices:
        attr sduino longids 1
        # Use longids for BTHR918N devices.
        # Will generate devices names like BTHR918N_f3.
        attr sduino longids BTHR918N
      

• maxMuMsgRepeat
  MU signals can contain multiple repeats of the same message. The results are all send to a logical module. You can limit the number of scanned repetitions. Defaukt is 4, so after found 4 repeats, the demoduation is aborted.


• minsecs
  This is a very special attribute. It is provided to other modules. minsecs should act like a threshold. All logic must be done in the logical module. If specified, then supported modules will discard new messages if minsecs isn't past.


• noMsgVerbose
  With this attribute you can control the logging of debug messages from the io device. If set to 3, this messages are logged if global verbose is set to 3 or higher.


• rawmsgEvent
  When set to "1" received raw messages triggers events


• rfmode
  Configures the RF transceiver of the SIGNALduino (CC1101). The available arguments:
  • Avantek
    Modulation 2-FSK, Datarate=50.087 kbps, Sync Word=0869, FIFO-THR=8 Byte, Frequency 433.3 MHz
    Example: AVANTEK Wireless Digital Door Bell
  • Bresser_5in1
    Modulation 2-FSK, Datarate=8.23 kbps, Sync Word=2DD4, Packet Length=26 Byte, Frequency 868.3 MHz
    Example: BRESSER 5-in-1 weather center, BRESSER rain gauge, Fody E42, Fody E43
  • Bresser_6in1
    modulation 2-FSK, Datarate=8.23 kbps, Sync Word=2DD4, FIFO-THR=20 Byte, frequency 868.3 MHz
  • Bresser_7in1
    modulation 2-FSK, Datarate=8.23 kbps, Sync Word=2DD4, Packet Length=22 Byte, frequency 868.3 MHz
  • Fine_Offset_WH51_434
    Modulation 2-FSK, Datarate=17.26 kbps, Sync Word=2DD4, Packet Length=14 Byte, Frequency 433.92 MHz
    Example: Soil moisture sensor Fine Offset WH51, ECOWITT WH51, MISOL/1, Froggit DP100
  • Fine_Offset_WH51_868
    Modulation 2-FSK, Datarate=17.26 kbps, Sync Word=2DD4, Packet Length=14 Byte, Frequency 868.35 MHz
    Example: Soil moisture sensor Fine Offset WH51, ECOWITT WH51, MISOL/1, Froggit DP100
  • Fine_Offset_WH57_434
    Modulation 2-FSK, Datarate=17.26 kbps, Sync Word=2DD4, Packet Length=9 Byte, Frequency 433.92 MHz
    Example: Thunder and lightning sensor Fine Offset WH57, Froggit DP60, Ambient Weather WH31L
  • Fine_Offset_WH57_868
    Modulation 2-FSK, Datarate=17.26 kbps, Sync Word=2DD4, Packet Length= Byte, Frequency 868.35 MHz
    Example: Thunder and lightning sensor Fine Offset WH57, Froggit DP60, Ambient Weather WH31L
  • Inkbird_IBS-P01R
    Modulation 2-FSK, Datarate=10.00 kbps, Sync Word=2DD4, Packet Length=18 Byte, Frequency 433.92 MHz
    Example: Inkbird IBS-P01R pool thermometer, ITH-20R thermometer/hygrometer
  • KOPP_FC
    modulation GFSK, Datarate=4.7855 kbps, Sync Word=AA54, frequency 868.3MHz
  • Lacrosse_mode1
    modulation 2-FSK, Datarate=17.25769 kbps, Sync Word=2DD4, frequency 868.3MHz
    
    example: TX25-IT, TX27-IT, TX29-IT, TX29DTH-IT, TX37, 30.3143.IT, 30.3144.IT
  • Lacrosse_mode2
    modulation 2-FSK, Datarate=9.579 kbps, Sync Word=2DD4, frequency 868.3MHz
    
    example: TX35TH-IT, TX35DTH-IT, TX38-IT, 30.3155WD, 30.3156WD
  • PCA301
    modulation 2-FSK, Datarate=6.62041 kbps, Sync Word=2DD4, frequency 868.950 MHz
  • Rojaflex
    modulation GFSK, Datarate=9.99 kbps, Sync Word=D391D391, frequency 433.920 MHz
  • SlowRF
    modulation ASK/OOK, loads the standard setting from the uC


• suppressDeviceRawmsg
  When set to 1, the internal "RAWMSG" will not be updated with the received messages


• updateChannelFW
  The module can search for new firmware versions (SIGNALDuino and SIGNALESP). Depending on your choice, only stable versions are displayed or also prereleases are available for flash. The option testing does also provide the stable ones.
  • stable: only versions marked as stable are available. These releases are provided very infrequently
  • testing: These versions needs some verifications and are provided in shorter intervals
  
  Reload the available Firmware via get availableFirmware manually.


• whitelist_IDs
  This attribute allows it, to specify whichs protocos are considured from this module. Protocols which are not considured, will not generate logmessages or events. They are then completly ignored. This makes it possible to lower ressource usage and give some better clearnes in the logs. You can specify multiple whitelistIDs wih a colon : 0,3,7,12
  With a # at the beginnging whitelistIDs can be deactivated.
  Not using this attribute or deactivate it, will process all stable protocol entrys. Protocols which are under development, must be activated explicit via this Attribute.


• WS09_CRCAUS
  
  • 0: CRC-Check WH1080 CRC = 0 on, default
  • 2: CRC = 49 (x031) WH1080, set OK


• MatchList
  This attribute adds additional items to the module matchlist. Items has to be described in a PERL Hash format:
  • Format: { 'number:module' => 'protocol-pattern' , 'nextNumber:nextModule' => 'protocol-pattern' , ... }
  • Example: { '34:MyModule' => '^u98#.{8}' , '35:MyModule2' => '^u99#.{10}' }

Information menu

• Display protocollist
  Shows the current implemented protocols from the SIGNALduino and to what logical FHEM Modul data is sent.
  Additional there is an checkbox symbol, which shows you if a protocol will be processed. This changes the Attribute whitlistIDs for you in the background. The attributes whitelistIDs and blacklistIDs affects this state. Protocols which are flagged in the row dev, are under development
  • If a row is flagged via 'm', then the logical module which provides you with an interface is still under development. Per default, these protocols will not send data to logcial module. To allow communication to a logical module you have to enable the protocol.
  • If a row is flagged via 'p', then this protocol entry is reserved or in early development state.
  • If a row is flalged via 'y' then this protocol isn't fully tested or reviewed.
  
  If you are using blacklistIDs, then you also can not activate them via the button, delete the attribute blacklistIDs if you want to control enabled protocols via this menu.

SIGNALduino_un

[EN DE]

The SIGNALduino_un module is a testing and debugging module to decode some devices, it will catch only all messages from the signalduino which can't be send to another module.
It can create one help devices after define development attribute on SIGNALduino device. You get a hint from Verbose 4 in the FHEM Log.

example: SIGNALduino_unknown sduino_dummy Protocol:40 | To help decode or debug, please add u40! (attr sduino_dummy development u40)


Define
define <name> SIGNALduino_un <code>

You can define a Device, but currently you can do nothing with it. The function of this module is only to output some logging at verbose 4 or higher at FHEM-logfile or logging to help device. May some data is decoded correctly but it's also possible that this does not work. The Module will try to process all messages, which where not handled by other modules.

Created devices / logfiles must be deleted manually after removing the protocol from the attribute development. (example: u40, y84)


Set
UserInfo "comment" - the user can put comments in the logfile which are arranged to his bits of the device
(example: to write off the digital display of the thermometer at the time of reception or states of switches ...)


Get
N/A


Attributes
• ignore
• stateFormat
• verbose


Generated readings
• bitCount (Length of the signal, binary)
• bitCountLength (Length range of all received signals of the protocol)
• bitMsg
• bitMsg_invert (Message binary, inverted)
• hexCount_or_nibble (Length of the signal, hexadecimal)
• hexMsg
• hexMsg_invert (Message hexadecimal, inverted)
• lastInputDev (Device at the last reception)
• past_seconds (Duration in seconds since the readings were last updated)

SIP

[EN DE]

Define a SIP-Client device.
Wiki : https://wiki.fhem.de/wiki/SIP-Client
Forum : https://forum.fhem.de/index.php/topic,67443.0.html

Define
define <name> SIP

Example:
define MySipClient SIP


Set
• set <name> <SIP password>
  Stores the password for the SIP users. Without stored password the functions set call and set listen are blocked !
  IMPORTANT : if you rename the fhem Device you must set the password again!
• set <name> reset
  Stop any listen process and initialize device.
  
• set <name> call <number> [<maxtime>] [<message>]
  Start a call to the given number.
  Optionally you can supply a max time. Default is 30. Optionally you can supply a message which is either a full path to an audio file or a relativ path starting from the home directory of the fhem.pl.
• set <name> listen
  attr sip_listen = dtmf :
  Start a listening process that receives calls. The device goes into an echo mode when a call comes in. If you press # on the keypad followed by 2 numbers and hang up the reading dtmf will reflect that number.
  attr sip_listen = wfp :
  Start a listening process that waits for incoming calls. If a call comes in for the SIP-Client the state will change to ringing. If you manually set the state to fetch the call will be picked up and the sound file given in attribute sip_audiofile will be played to the caller. After that the devive will go gack into state listenwfp.
  

Attributes
• sip_audiofile_wfp
  Audio file that will be played after fetch command. The audio file has to be generated via
  sox <file>.wav -t raw -r 8000 -c 1 -e a-law <file>.al
  since only raw audio format is supported.


• sip_audiofile_call
• sip_audiofile_dtmf
• sip_audiofile_ok
• sip_listen (none , dtmf , wfp)
• sip_from
  My sip client info, defaults to sip:620@fritz.box


• sip_ip
  external IP address of the FHEM server


• sip_port
  Optionally portnumber used for sip client
  If attribute is not set a random port number between 44000 and 45000 will be used


• sip_registrar
  Hostname or IP address of the SIP server you are connecting to, defaults to fritz.box


• sip_ringtime
  Ringtime for incomming calls (dtmf &wfp)


• sip_user
  User name of the SIP client, defaults to 620


• sip_waittime
  Maximum waiting time in state listen_for_wfp it will wait to pick up the call


• sip_dtmf_size 1 to 4 , default is 2


• sip_dtmf_loop once or loop , default once


• sip_force_interval default 300


• sip_force_max default 99


• phonebook default none , filename of own phonebook. each row : number,name


• history_size default 0 , max rows in history list


• history_file default none, filename of history list

SISPM

[EN DE]

Define
define <name> SISPM </path/to/sispmctl>


When using multiple SIS PMs on one host, sispmctl up to and including V 2.7 has a bug:

plug-2:# sispmctl -v -s -d 1 -g all -d 2 -g all

SiS PM Control for Linux 2.7

(C) 2004, 2005, 2006, 2007, 2008 by Mondrian Nuessle, (C) 2005, 2006 by Andreas Neuper.
This program is free software.
[...]

Gembird #0 is USB device 013.This device is a 4-socket SiS-PM.
[...]

Gembird #1 is USB device 015.This device is a 4-socket SiS-PM.
[...]

Accessing Gembird #1 USB device 015
Status of outlet 1:     on
Status of outlet 2:     on
Status of outlet 3:     on
Status of outlet 4:     on
Error performing requested action
Libusb error string: error sending control message: Invalid argument
Terminating
*** glibc detected *** sispmctl: double free or corruption (fasttop): 0x000251e0 ***
[...]

Well, the fix is simple and will be sent upstream, but in case it's not incorporated at the time you need it, here it is; it's easy to apply even by hand ;-)

--- src/main.c-old      2010-01-19 16:56:15.000000000 +0100
+++ src/main.c  2010-01-19 16:54:56.000000000 +0100
@@ -441,7 +441,7 @@
            }
            break;
        case 'd': // replace previous (first is default) device by selected one
-           if(udev!=NULL) usb_close (udev);
+           if(udev!=NULL) { usb_close (udev); udev=NULL; }
            devnum = atoi(optarg);
            if(devnum>=count) devnum=count-1;
            break;


Defines a path to the program "sispmctl", which is used to control (locally attached) "Silver Shield Power Manager" devices. Usually these are connected to the local computer via USB, more than one "sispm" device per computer is supported. (Please note that, due to neglections in their USB driver, AVM's Fritz!Box 7170 (and derivates, like Deutsche Telekom's Speedport W901V) is not able to talk to these devices ... The Fritz!Box 72xx and 73xx should be fine.) The communication between FHEM and the Power Manager device is done by using the open source sispmctl program. Thus, for the time being, THIS functionality is only available running FHEM on Linux (or any other platform where you can get the sispmctl program compiled and running). On the bright side: by interfacing via commandline, it is possible to define multiple SISPM devices, e. g. with a wrapper that does execute sispmctl on a remote (Linux) system. And: sispmctl runs happily on Marvells SheevaPlug ;) Please note: if you're not running FHEM as root, you most likely have to make sispmctl setuid root (chmod 4755 /path/to/sispmctl) or fiddle with udev so that the devices of the Power Manager are owned by the user running FHEM. After defining a SISPM device, a first test is done, identifying attached PMs. If this succeeds, an internal task is scheduled to read the status every 30 seconds. (Reason being that someone else could have switched sockets externally to FHEM.) To actually control any power sockets, you need to define a SIS_PMS device ;) If autocreate is enabled, those should be autocreated for your convenience as soon as the first scan took place (30 seconds after the define). Implementation of SISPM.pm tries to be nice, that is it reads from the pipe only non-blocking (== if there is data), so it should be safe even to use it via ssh or a netcat-pipe over the Internet, but this, as well, has not been tested extensively yet.

Attributes:
• model: SISPM (ignored for now)

Example:
define PMS_Terrarium SISPM /usr/bin/sispmctl



Set
N/A

Get
N/A

Attributes
• model (SISPM)

SIS_PMS

[EN DE]

This module is responsible for handling the actual sockets (power on, power off, toggle) on a "Silver Shield Power Manager", see SISPM for how to define access to one (SIS_PMS stands for "Silver Shield Power Manager Socket").

Define
define <name> SIS_PMS <serial> <socket>

To securely distinguish multiple attached Power Manager devices, the serial number of those is used. You get these with "sispmctl -s" - or just let autocreate define the sockets attached for you.

• <serial> is the serial number of the Power Manager device, see above.
• <socket> is a number between 1 and 4 (for a 4 socket model)

Examples:
define lamp SIS_PMS 01:02:03:04:05 1
define otherlamp SIS_PMS 01:02:03:04:05 3
define tv SIS_PMS 01:01:38:44:55 1

Set
set <name> <value> [<time>]

where value is one of:


    off
    on
    toggle
    on-till           # Special, see the note
    off-till          # Special, see the note
    

Examples:
set lamp on
set lamp1,lamp2,lamp3 on
set lamp1-lamp3 on
set hql_lamp on-till 18:45


Notes:
• As an external program is used, a noticeable delay may occur.
• *-till requires an absolute time in the "at" format (HH:MM:SS, HH:MM or { <perl code> }, where the perl-code returns a time specification). If the current time is greater than the specified time, then the command is ignored, else an "on" or "off" command, respectively, is generated, and for the given time an "off"/"on" command is scheduleld via the at command.

Get
N/A

Attributes
• do_not_notify


• dummy
  Set the device attribute dummy to define devices which should not output any signals. Associated notifys will be executed if the signal is received. Used e.g. to react to a code from a sender, but it will not actually switch if triggered in the web frontend.


• loglevel

SMAEM

[EN DE]

Define

define <name> SMAEM [<interface>]

Defines a SMA Energy Meter (SMAEM), a bidirectional energy meter/counter used in photovoltaics. The optional parameter interface defines a specific network interface to use, e.g. "eth0".

You need at least one SMAEM on your local subnet or behind a multicast enabled network of routers to receive multicast messages from the SMAEM over the multicast group 239.12.255.254 on udp/9522. Multicast messages are sent by SMAEM once a second (firmware 1.02.04.R, March 2016).

The update interval will be set by attribute "interval". If not set, it defaults to 60s. Since the SMAEM sends updates once a second, you can update the readings once a second by lowering the interval to 1 (Not recommended, since it puts FHEM under heavy load).

The parameter "disableSernoInReading" changes the way readings are named: if disableSernoInReading is false or unset, the readings will be named "SMAEM<serialnumber_>.....". If set to true, the prefix "SMAEM<serialnumber_>" is skipped. Set this to true if you only have one SMAEM device on your network and you want shorter reading names. If unsure, leave it unset.

You need the perl module IO::Socket::Multicast. Under Debian (based) systems it can be installed with apt-get install libio-socket-multicast-perl.

Set

• reset
  The automatically created file "cacheSMAEM" is deleted. The file is reinitialized by the module. This function is used to reset a possible error state of the device, but can also be executed at any time.

Attribute

• diffAccept
  The attribute diffAccept determines the threshold, up to that a calaculated difference between two straight sequently meter readings (Readings with *_Diff) should be commenly accepted (default = 10).
  Hence faulty DB entries with a disproportional high difference values will be eliminated, don't tamper the result and the measure cycles will be discarded.


• disable
  Disable or enable the device.


• disableSernoInReading
  Prevents the prefix "SMAEM<serialnumber_>....."


• feedinPrice
  The individual amount of refund of one kilowatt hour


• interval
  Evaluation interval in seconds


• noCoprocess
  If set, the energy evaluation takes place in a separate backround process. At default a parallel background process is started every evaluation period. This attribute can be helpful to optimize the FHEM system.


• powerCost
  The individual amount of power cost per kWh


• serialNumber
  The serial number(s) (e.g. 1900212213) of the SMA Energy Meter to be received by the SMAEM device. Multiple serial numbers must be separated by spaces.
  (default: no restriction)


• timeout
  Adjustment timeout of backgound processing (default 60s). The value of timeout has to be higher than the value of "interval".

SMAEVCharger

[EN DE]

Module for the integration of a SMA EVCharger over it's Speedwire (=Ethernet) Interface.
Tested on SMA EV Charger 22

Requirements

This module requires:

• Perl Module: Date::Time (apt-get install libdatetime-perl)
• Perl Module: Time::HiRes
• Perl Module: JSON
• FHEM Module: Blocking.pm

Definition

define <name> SMAEVCharger <hostname/ip> <user> <password>


• hostname/ip: IP-Adress of the charger, should be without protocol (for now hostname not testet!).
• Example: define myWallbox 192.168.xxx.xxx username userpassword

Operation method

The module logs on to the SMA Wallbox and reads live data (monitoring measurement values) as well as available parameters (configuration parameters).
All values ​​that can be changed via the web interface can also be changed with the module. To reduce readings, the values ​​to be displayed and the values ​​that can be changed
can be adjusted with the 'detail-level' and 'setting-level' attributes.

Get

• get <name> data
  
  The request of the charger will be executed directly. Otherwise all seconds the charge will be called automated (look at attribute interval)
  
• get <name> showAccount
  
  Shows the decrypted account infos
  

Attributes

• disable [1|0]
  Deactivate/activate the module.


• interval
  Request cycle in seconds. (default: 60)


• detail-level
  Set level for showing Live-Data Readings
  0: Basic
  1: Adanced
  2: Expert


• setting-level
  Set level for changing Parameters with fhem set-command. The module checks corresponding detail-level attribute.
  0: Basic
  1: Adanced
  2: Expert

Readings

Following infos will show readings (livedata, parameter) and there corresponding detail-level and setting-level. There are additional readings which will be calculated from the values of the wallbox.
• Anzahl_Ladevorgaenge
  Counts the charging starts since last connecting


• Startzeit_Verbindung
  Last connecting time

To start charging there are different options:

• Param_Betriebsart_Ladevorgang
  Optimiertes Laden: default for using planning algorithm from wallbox
  Laden mit Vorgabe: predefined charging. To set this option the params 'Param_Dauer_Ladevorgang' and 'Param_Energiemenge_Ladevorgang' must be filled.
  If both values are set then this param will be set automatically and charging starts.
  Ladestopp: stop charging


• Param_Dauer_Ladevorgang
  Duration of the charging process. This values sets date/time till charging should be finished (Param_Ende_Ladevorgang)


• Param_Energiemenge_Ladevorgang
  Set energy for charging in kWh. Value can be changed during charging process.


• Param_Minimaler_Ladestrom
  Set minimum power for starting charging process. Minimum is 6A. Some vehicles need more power to start, so change this value.

• Name in Webinterface : Name in FHEM : comment
• LIVEDATA
• Measurement.ChaSess.WhIn :Energie_Ladevorgang : unit Wh (detail-level: 0)
• Measurement.Chrg.ModSw :Schalterstellung Drehschalter : (detail-level: 0)
• Measurement.GridMs.A.phsA : Netzstrom_Phase_L1 : (detail-level: 0)
• Measurement.GridMs.A.phsB : Netzstrom_Phase_L2 : (detail-level: 0)
• Measurement.GridMs.A.phsC : Netzstrom_Phase_L3 : (detail-level: 0)
• Measurement.GridMs.PhV.phsA : Netzspannung_Phase_L1 : (detail-level: 0)
• Measurement.GridMs.PhV.phsB : Netzspannung_Phase_L2 : (detail-level: 0)
• Measurement.GridMs.PhV.phsC : Netzspannung_Phase_L3 : (detail-level: 0)
• Measurement.Metering.GridMs.TotWIn : Leistung_Bezug : unit: W (detail-level: 0)
• Measurement.Metering.GridMs.TotWIn.ChaSta : Leistung_Ladestation : unit W (detail-level: 0)
• Measurement.Metering.GridMs.TotWhIn : Zaehlerstand_Bezugszaehler : unit Wh (detail-level: 0)
• Measurement.Metering.GridMs.TotWhIn.ChaSta : Zaehlerstand_Ladestation : unit Wh (detail-level: 0)
• Measurement.Operation.EVeh.ChaStt : Status_Ladevorgang: (detail-level: 0)
• Measurement.Operation.EVeh.Health : Status_verbundenes_Fahrzeug: (detail-level: 0)
• Measurement.Operation.Evt.Msg : Status_Meldung : (detail-level: 0)
• Measurement.Operation.Health : Status_Zustand : (detail-level: 0)
• Setpoint.PlantControl.Inverter.FstStop : Schnellabschaltung : (detail-level: 0)
• Measurement.GridMs.Hz : Netzfrequenz : (detail-level: 1)
• Measurement.GridMs.TotPF : Verschiebungsfaktor : (detail-level: 1)
• Measurement.GridMs.TotVA : Scheinleistung : (detail-level: 1)
• Measurement.GridMs.TotVAr : Blindleistung : (detail-level: 1)
• Measurement.Wl.AcqStt : Status_WLAN_Scan : (detail-level: 1)
• Measurement.Wl.ConnStt : Status_WLAN_Verbindung : (detail-level: 1)
• Measurement.Wl.SigPwr : Signalstaerke_Netzwerk : (detail-level: 1)
• Measurement.InOut.GI1 : digitaler_Gruppeneingang : (detail-level: 2)
• Measurement.Operation.WMaxLimSrc : Digitaler_Eingang : (detail-level: 2)
• Measurement.Wl.SoftAcsConnStt : Status_Soft_Access_Point : (detail-level: 2)
• PARAMS:
• Parameter.Chrg.ActChaMod : Param_Betriebsart_Ladevorgang: (detail-level: 0 / setting-level: 0)
• Parameter.Chrg.AMinCha : Param_Minimaler_Ladestrom: (detail-level: 0 / setting-level: 0)
• Parameter.Chrg.Plan.DurTmm : Param_Dauer_Ladevorgang : (detail-level: 0 / setting-level: 0)
• Parameter.Chrg.Plan.En : Param_Energiemenge_Ladevorgang : (detail-level: 0 / setting-level: 0)
• Parameter.Chrg.Plan.StopTm : Param_Ende_Ladevorgang: (detail-level: 0)
• Parameter.Chrg.StpWhenFl : Param_Trennung_nach_Vollladung: (detail-level: 0 / setting-level: 1)
• Parameter.Chrg.StpWhenFlTm : Param_Ladebereitschaft_bis_Trennung: (detail-level: 0 / setting-level: 1)
• Parameter.Chrg.ChrgApv : Param_Manuelle_Ladefreigabe: (detail-level: 0 / setting-level: 0)
• Parameter.Chrg.ChrgLok : Param_Ladefreigabe_ueber_App: (detail-level: 0 / setting-level: 0)
• Parameter.GridGuard.Cntry.VRtg : Param_Netz_Nennspannung: (detail-level: 0)
• Parameter.PCC.ARtg : Param_Nennstrom_Netzanschluss: (detail-level: 0 / setting-level: 1)
• Parameter.PCC.FlbInv.WMax : Param_Fallback_Wirkleistungsbegrenzung: (detail-level: 0 / setting-level: 1)
• Parameter.Chrg.UseEnergyMeter : Param_Betrieb_mit_Netzanschlusspunktzaehler: (detail-level: 1 / setting-level: 1)
• Parameter.Chrg.MinSwTms : Param_Minimale_Schaltdauer_Relais : (detail-level: 1 / setting-level: 1)
• Parameter.Inverter.WMax : Param_Nennwirkleistung_WMaxOut: (detail-level: 1 / setting-level: 1)
• Parameter.Inverter.WMaxIn : Param_Nennwirkleistung_WMaxIn: (detail-level: 1 / setting-level: 1)
• Parameter.Inverter.WMaxInRtg : Param_Bemessungswirkleistung_WMaxInRtg: (detail-level: 1)
• Parameter.Inverter.AcALim : Param_AC_Strom_Begrenzung: (detail-level: 0 / setting-level: 1)
• Parameter.Nameplate.ARtg : Param_Nennstrom_alle_Phasen: (detail-level: 1)
• Parameter.Nameplate.Location : Param_Geraetename : (detail-level: 1)
• Parameter.PCC.WMaxAsym : Param_Maximale_Schieflast: (detail-level: 1 / setting-level: 1)
• Parameter.Nameplate.ChrgCtrl.ChrgTypTxt :Param_Typ_Ladecontroller : (detail-level: 2)
• Parameter.Nameplate.ChrgCtrl.SerNumTxt :Param_Seriennummer_Ladecontrollers : (detail-level: 2)
• Parameter.Nameplate.ChrgCtrl.SusyId :Param_SusyID_Ladecontrollers : (detail-level: 2)
• Parameter.Nameplate.ChrgCtrl.SwRevTxt :Param_SWVersion_Ladecontroller : (detail-level: 2)
• Parameter.Nameplate.CmpMain.HwRev :Param_HWVersion_Hauptprozessor : (detail-level: 2)
• Parameter.Nameplate.CmpMain.Rev :Param_Umbaustand_Hauptprozessor : (detail-level: 2)
• Parameter.Nameplate.CmpMain.SerNum :Param_Seriennummer_Hauptprozessor : (detail-level: 2)
• Parameter.Nameplate.CmpMain.SusyId :Param_SUSyID_Hauptprozessor : (detail-level: 2)
• Parameter.Nameplate.CmpOS.SwRev :Param_Firmware_Version_Betriebssystem : (detail-level: 2)
• Parameter.Nameplate.MacId :Param_MAC-Adresse : (detail-level: 2)
• Parameter.Nameplate.MainModel :Param_Geraeteklasse : (detail-level: 2)
• Parameter.Nameplate.Model :Param_Geraetetyp : (detail-level: 2)
• Parameter.Nameplate.ModelStr :Param_Typenbezeichnung : (detail-level: 2)
• Parameter.Nameplate.PkgRev :Param_Softwarepaket : (detail-level: 2)
• Parameter.Nameplate.SerNum :Param_Seriennummer : (detail-level: 2)
• Parameter.Nameplate.Vendor :Param_Hersteller : (detail-level: 2)
• Parameter.Nameplate.WlMacId :Param_WLAN_MAC : (detail-level: 2)
• Parameter.DevUpd.IsOn : Param_Geraete_Update_ein : (detail-level: 2)
• Parameter.Inverter.OutPhs : Param_Phasenzuordnung : (detail-level: 2)
• Parameter.Operation.ComTmOut : Param_Timeout_nach_Kommunikationsverlust: (detail-level: 2)
• Parameter.Spdwr.IgmpQryTms : Param_IGMP_Query_Intervall: (detail-level: 2)
• Parameter.Spdwr.IgmpQryTx : Param_IGMP_Anfragen_senden: (detail-level: 2)
• Parameter.Spdwr.ActlDnsSrvIp :Param_Akt_Speedwire_Serveradresse : (detail-level: 2)
• Parameter.Spdwr.ActlGwIp :Param_Akt_Speedwire_Gateway : (detail-level: 2)
• Parameter.Spdwr.ActlIp :Param_Akt_Speedwire_IP : (detail-level: 2)
• Parameter.Spdwr.ActlSnetMsk :Param_Akt_Speedwire_Subnetzmaske : (detail-level: 2)
• Parameter.Spdwr.AutoCfgIsOn :Automatische_Speedwire-Konfig_an : (detail-level: 2)
• Parameter.Sys.DevRstr : Param_Geraeteneustart_ausloesen: (detail-level: 2)
• Parameter.SwCmp.CmpEnnexOS.Frwk.SwRev :Param_ennexOS_Framework_Version : (detail-level: 2)
• Parameter.Upd.AutoUpdIsOn : Param_Auto_Update_an: (detail-level: 2)
• Parameter.Upd.AvalChkIstl :Param_Auto_Speedwire_Konfig_an : (detail-level: 2)
• Parameter.Wl.ActlGwIp :Param_IP_Gateway_WLAN : (detail-level: 2)
• Parameter.Wl.ActlDnsSrvIp :Aktuelle_Speedwire-DNS-Serveradresse : (detail-level: 2)
• Parameter.Wl.ActlIp :Param_IP_WLAN : (detail-level: 2)
• Parameter.Wl.ActlSnetMsk :Param_IP_Subnetz_WLAN : (detail-level: 2)
• Parameter.Wl.DoAcq :Param_WLAN_suchen : (detail-level: 2)
• Parameter.Wl.DoWPS :Param_WPS_aktivieren : (detail-level: 2)
• Parameter.Wl.ExsNetw[] :Param_Gefundenes_WLAN : (detail-level: 2)
• Parameter.Wl.Sec.Cry :Param_Verschluesselung_WLAN : (detail-level: 2)
• Parameter.Wl.Sec.Psk :Param_WLAN-Passwort : (detail-level: 2)
• Parameter.Wl.Sec.Ssid :Param_SSID_WLAN : (detail-level: 2)
• Parameter.Wl.AutoCfgIsOn : Param_Auto_Update_an: (detail-level: 2)
• Parameter.Wl.IsOn : Param_WLAN_eingeschaltet: (detail-level: 2)
• Parameter.Wl.SoftAcsIsOn : Param_Soft_Access_Point_an: (detail-level: 2)

SMAInverter

[EN DE]

Module for the integration of a SMA Inverter over it's Speedwire (=Ethernet) Interface.
Tested on Sunny Tripower 6000TL-20 and Sunny Island 4.4 with Speedwire/Webconnect Piggyback.

Questions and discussions about this module you can find in the FHEM-Forum link:
76_SMAInverter.pm - Abfrage von SMA Wechselrichter.

Requirements

This module requires:

• Perl Module: IO::Socket::INET (apt-get install libio-socket-multicast-perl)
• Perl Module: Date::Time (apt-get install libdatetime-perl)
• Perl Module: Time::HiRes
• FHEM Module: 99_SUNRISE_EL.pm
• FHEM Module: Blocking.pm

Definition

define <name> SMAInverter <pin> <hostname/ip>


• pin: password of the inverter. Default is 0000.
  inverter without webinterface: The password for the inverter can be changed by "Sunny Explorer" Client Software
  inverter with webinterface: The password changed by the webinterface is also valid for the device definition.
• hostname/ip: Hostname or IP-Adress of the inverter (or it's speedwire piggyback module).
• The Speedwire port is 9522 by default. A Firewall has to allow connection on this port if present !

Operation method

The module sends commands to the inverter and checks if they are supported by the inverter.
In case of a positive answer the data is collected and displayed in the readings according to the detail-level.

The normal operation time of the inverter is supposed from sunrise to sunset. In that time period the inverter will be polled. The time of sunrise and sunset will be calculated by functions of FHEM module 99_SUNRISE_EL.pm which is loaded automatically by default. Therefore the global attribute "longitude" and "latitude" should be set to determine the position of the solar system (see Commandref SUNRISE_EL).

By the attribute "suppressSleep" the sleep mode between sunset and sunrise can be suppressed. Using attribute "offset" you may prefer the sunrise and defer the sunset virtually. So the working period of the inverter will be extended.

In operating mode "automatic" the inverter will be requested periodically corresponding the preset attribute "interval". The operating mode can be switched to "manual" to realize the retrieval manually (e.g. to synchronize the requst with a SMA energy meter by notify).

During inverter operating time the average energy production of the last 5, 10 and 15 minutes will be calculated and displayed in the readings "avg_power_lastminutes_05", "avg_power_lastminutes_10" and "avg_power_lastminutes_15". Note: To permit a precise calculation, you should also set the real request interval into the attribute "interval" although you would use the "manual" operation mode !

The retrieval of the inverter will be executed non-blocking. You can adjust the timeout value for this background process by attribute "timeout".

Get

• get <name> data
  
  The request of the inverter will be executed. Those possibility is especifically created for the "manual" operation mode (see attribute "mode").
  

Attributes

• detail-level [0|1|2]
  Defines the complexity of the generated readings.
  
  

  0	- only Power and Energy
  1	- as 0, additional voltage and current
  2	- as 1, additional voltage and current



• readEnergyMeter-data [1|0]
  Deactivates/activates the reading of the energy meter/smart meter data via the inverter.
  The Readings Meter_xxx are then created and filled with data.


• disable [1|0]
  Deactivate/activate the module.


• interval
  Request cycle in seconds. (default: 60)


• mode [automatic|manual]
  The request mode of the inverter. (default: automatic)
  
  

  automatic	- the inverter will be polled regularly as defined by attribute "interval"
  manual	- query only by command "get <name> data"



• offset <0 - 7200>
  Time in seconds to forward the real sunrise respectively defer the real sunset. You will be able to extend the working period of the module.


• SBFSpotComp [1|0]
  The reading names are created like the SBFSpot-style. (default: 0)


• showproctime [1|0]
  Shows the processing time in background and the wasted time to retrieve inverter data. (default: 0)


• suppressSleep [1|0]
  The sleep mode (after sunset and before sunrise) is deactivated and the inverter will be polled continuously. (default: 0)


• target-serial
  In case of a Multigate the target serial number has to be defined. If more than one inverter is installed, you have to set the inverter serial number to assign the inverter to the device definition. If only one inverter available, the attribut is set automatically once the serial number of the inverter was detected. (default: 0xFFFFFFFF = means any serial number)


• target-susyid
  In case of a Multigate the target SUSyID has to be defined. If more than one inverter is installed, you have to set the inverter-SUSyID to assign the inverter to the device definition. If only one inverter available, the attribut is set automatically once the SUSyID of the inverter was detected. (default: 0xFFFF = means any SUSyID)


• timeout
  Setup timeout of inverter data request in seconds. (default 60)

Readings

• BAT_CYCLES / bat_cycles : Battery recharge cycles
• BAT_IDC [A,B,C] / bat_idc [A,B,C] : Battery Current [A,B,C]
• BAT_TEMP [A,B,C] / bat_temp [A,B,C] : Battery temperature [A,B,C]
• BAT_UDC [A,B,C] / bat_udc [A,B,C] : Battery Voltage [A,B,C]
• BAT_PDC / bat_pdc : Battery power (only Hybrid-Inverter), calculated from I and U
• BAT_P_CHARGE / bat_p_charge : Battery chargepower (only Hybrid-Inverter)
• BAT_P_DISCHARGE / bat_p_discharge : Battery dischargepower (only Hybrid-Inverter)
• ChargeStatus / chargestatus : Battery Charge status
• BAT_CAPACITY / bat_capacity : Battery (remaining) Capacity (SOH)
• BAT_RATED_CAPACITY / bat_rated_capacity : Battery reted Capacity Wh/kWh
• BAT_LOADTODAY : Battery Load Today
• BAT_LOADTOTAL : Battery Load Total
• BAT_UNLOADTODAY : Battery Unload Today
• BAT_UNLOADTOTAL : Battery Unload Total
• CLASS / device_class : Inverter Class
• PACMAX1 / pac_max_phase_1 : Nominal power in Ok Mode
• PACMAX1_2 / pac_max_phase_1_2 : Maximum active power device (Some inverters like SB3300/SB1200)
• PACMAX2 / pac_max_phase_2 : Nominal power in Warning Mode
• PACMAX3 / pac_max_phase_3 : Nominal power in Fault Mode
• Serialnumber / serial_number : Inverter Serialnumber
• SPOT_ETODAY / etoday : Today yield
• SPOT_ETOTAL / etotal : Total yield
• SPOT_EPVTODAY / epvtoday : Today PV yield
• SPOT_EPVTOTAL / epvtotal : Total PV yield
• SPOT_FEEDTM / feed-in_time : Feed-in time
• SPOT_FREQ / grid_freq : Grid Frequency
• SPOT_CosPhi / coshhi : displacement factor
• SPOT_IAC1 / phase_1_iac : Grid current phase L1
• SPOT_IAC2 / phase_2_iac : Grid current phase L2
• SPOT_IAC3 / phase_3_iac : Grid current phase L3
• SPOT_IDC1 / string_1_idc : DC current input
• SPOT_IDC2 / string_2_idc : DC current input
• SPOT_IDC3 / string_3_idc : DC current input
• SPOT_OPERTM / operation_time : Operation Time
• SPOT_PAC1 / phase_1_pac : Power L1
• SPOT_PAC2 / phase_2_pac : Power L2
• SPOT_PAC3 / phase_3_pac : Power L3
• SPOT_PACTOT / total_pac : Total Power
• SPOT_PDC1 / string_1_pdc : DC power input 1
• SPOT_PDC2 / string_2_pdc : DC power input 2
• SPOT_PDC3 / string_3_pdc : DC power input 3
• SPOT_PDC / strings_pds : DC power summary (only Hybrid-Inverter)
• SPOT_UAC1 / phase_1_uac : Grid voltage phase L1
• SPOT_UAC2 / phase_2_uac : Grid voltage phase L2
• SPOT_UAC3 / phase_3_uac : Grid voltage phase L3
• SPOT_UAC1_2 / phase_1_2_uac : Grid voltage phase L1-L2
• SPOT_UAC2_3 / phase_2_3_uac : Grid voltage phase L2-L3
• SPOT_UAC3_1 / phase_3_1_uac : Grid voltage phase L3-L1
• SPOT_UDC1 / string_1_udc : DC voltage input
• SPOT_UDC2 / string_2_udc : DC voltage input
• SPOT_UDC3 / string_3_udc : DC voltage input
• SUSyID / susyid : Inverter SUSyID
• INV_TEMP / device_temperature : Inverter temperature
• INV_TYPE / device_type : Inverter Type
• POWER_IN / power_in : Battery Charging power
• POWER_OUT / power_out : Battery Discharging power
• INV_GRIDRELAY / gridrelay_status : Grid Relay/Contactor Status
• INV_BACKUPRELAY / backuprelay_status : Backup Relay/Contactor Status (only Hybrid-Inverter)
• INV_GridConection / grid_conection : state of Gridconection (public grid/disconnected) (only SI-Inverter)
• INV_GeneralOperatingStatus / general_operating_status
• : General Status from the Inverter (MPP/Activated/Derating)
• INV_OperatingStatus / operating_status : operating status from the Inverter (Parallel grid operation/Backup) (only Hybrid-Inverter)
• INV_STATUS / device_status : Inverter Status
• INV_FIRMWARE / device_firmware : Inverter firmware version
• SPOT_BACKUP_IAC1 / phase_backup_1_iac : Backup current phase L1
• SPOT_BACKUP_IAC2 / phase_backup_2_iac : Backup current phase L2
• SPOT_BACKUP_IAC3 / phase_backup_3_iac : Backup current phase L3
• SPOT_BACKUP_PAC1 / phase_backup_1_pac : Backup power phase L1
• SPOT_BACKUP_PAC2 / phase_backup_2_pac : Backup power phase L2
• SPOT_BACKUP_PAC3 / phase_backup_3_pac : Backup power phase L3
• opertime_start : Begin of iverter operating time corresponding the calculated time of sunrise with consideration of the attribute "offset" (if set)
• opertime_stop : End of iverter operating time corresponding the calculated time of sunrise with consideration of the attribute "offset" (if set)
• modulstate : shows the current module state "normal" or "sleep" if the inverter won't be requested at the time.
• avg_power_lastminutes_05 : average power of the last 5 minutes.
• avg_power_lastminutes_10 : average power of the last 10 minutes.
• avg_power_lastminutes_15 : average power of the last 15 minutes.
• inverter_processing_time : wasted time to retrieve the inverter data
• background_processing_time : total wasted time by background process (BlockingCall)
• Meter_Grid_FeedIn_PACx / Meter_Grid_FeedIn_phase_x_pac : Power Grid_FeedIn phase Lx
• Meter_Grid_Consumation_PACx / Meter_Grid_Consumation_phase_x_pac : Power Grid_Consumation phase Lx
• Meter_Power_Grid_FeedIn / Meter_Power_Grid_FeedIn : total Power Grid_FeedIn
• Meter_Power_Grid_Consumation / Meter_Power_Grid_Consumation : total Power Grid_Consumation
• Meter_TOTAL_FeedIn / Meter_TOTAL_FeedIn : total Energie Grid_FeedIn
• Meter_TOTAL_Consumation / Meter_TOTAL_Consumation : total Energie Grid_Consumation
• Meter_TOTAL_Grid_FeedIn / Meter_TOTAL_Grid_FeedIn : total Energie Grid_FeedIn
• Meter_TOTAL_Grid_Consumation / Meter_TOTAL_Grid_Consumation : total Energie Grid_Consumation

SMARTMON

[EN DE]

This module is a FHEM frontend to the Linux tool smartctl. It provides various information on the SMART System of the hard drive.

Define

define <name> SMARTMON <device> [<Interval>]

This statement creates a new SMARTMON instance. The parameters specify a device to be monitored and the update interval in minutes.

Example: define sm SMARTMON /dev/sda 60

Readings:


• last_exit_code
  Exit code of smartctl.
• overall_health_test
  Specifies the general condition of the HDD (PASSED or FAILED).


• warnings
  Specifies the number of stored alerts.

Furthermore, the available SMART parameters can be displayed as Readings (RAW and / or (partially) interpreted).

Get:


• version
  Displays the module version.


• update
  Updates all readings.


• list
  Displays various information:
  • devices:
    List of available devices in the system.
  
  
  • info:
    Information about the current device.
  
  
  • data:
    List of SMART parameters for the current device.
  
  
  • health:
    Information about overall health status for the device.
  
  For the Last 3 commands can also be another Device specified (as an additional parameter).



Attributes:


• show_raw
  Valid values: 0: no RAW Readings (default), 1: show all, are not included in interpreted Readings, 2: show all.


• show_device_info
  Valid values: 0: no device info as reading, 1: show show device info as readings.


• include
  Comma separated list of IDs for desired SMART parameters. If nothing passed, all available values are displayed.


• disable
  Valid values: 0: Module active (default), 1: module is disabled (no updates).


• parameters
  Additional values for smartctl.




• ssh_host
  remote machine adresse. If defined, smartctrl is executed via SSH.

For more information see smartctrl documentation.

SMASTP

[EN DE]

Module for the integration of a Sunny Tripower Inverter build by SMA over it's Speedwire (=Ethernet) Interface.
Tested on Sunny Tripower 6000TL-20, 10000-TL20 and 10000TL-10 with Speedwire/Webconnect Piggyback.

Define

define <name> SMASTP <pin> <hostname/ip> [port]


• pin: User-Password of the SMA STP Inverter. Default is 0000. Can be changed by "Sunny Explorer" Windows Software
• hostname/ip: Hostname or IP-Adress of the inverter (or it's speedwire piggyback module).
• port: Port of the inverter. 9522 by default.

Modus

The module automatically detects the inactvity of the inverter due to a lack of light (night).
This inactivity is therefore called "nightmode". During nightmode, the inverter is not queried over the network.
By default nightmode is between 9pm and 5am. This can be changed by "starttime" (start of inverter
operation, end of nightmode) and "endtime" (end of inverter operation, start of nightmode).
Further there is the inactivitymode: in inactivitymode, the inverter is queried but readings are not updated.

Parameter

• interval: Queryintreval in seconds
• suppress-night-mode: The nightmode is deactivated
• suppress-inactivity-mode: The inactivitymode is deactivated
• starttime: Starttime of inverter operation (default 5am)
• endtime: Endtime of inverter operation (default 9pm)
• force-sleepmode: The nightmode is activated on inactivity, even the endtime is not reached
• enable-modulstate: Turns the reading "modulstate" (normal / inactive / sleeping) on
• alarm1-value, alarm2-value, alarm3-value: Set an alarm on the reading SpotP in watt.
  The readings Alarm1..Alarm3 are set accordingly: -1 for SpotP < alarmX-value and 1 for SpotP >= alarmX-value

Readings

• SpotP: spotpower - Current power in watt delivered by the inverter
• AvP01: average power 1 minute: average power in watt of the last minute
• AvP05: average power 5 minutes: average power in watt of the five minutes
• AvP15: average power 15 minutes: average power in watt of the fifteen minutes
• SpotPDC1: current d.c. voltage delivered by string 1
• SpotPDC2: current d.c. voltage delivered by string 2
• TotalTodayP: generated power in Wh of the current day
• AlltimeTotalP: all time generated power in Wh
• Alarm1..3: alrm trigger 1..3. Set by parameter alarmN-value

SML

[EN DE]

This module supports "Intelligenter Strom Zhler"(ENBW) and "Sparzhler" (Yellow Strom).
The electricity meter will be polled in a defined interval (1-100) for new values.

Define
define <name> SML <host> <port> [<interval> <timeout>]


Example:
define StromZ1 SML 192.168.178.20
define StromZ2 SML 192.168.10.25 60 60


Set
set <name> <value> <nummber>
where value is one of:


• TOTALPOWER
• YEARPOWER
• MONTHPOWER
• DAYPOWER
• Interval

Example:
set <name> TOTALPOWER 12345

Get
get <name> <value>
where value is one of:

• TOTALPOWER
• YEARPOWER
• MONTHPOWER
• DAYPOWER
• Interval

Example:
get <name> DAYPOWER
get <name> YEARPOWER

SOMFY - Somfy RTS / Simu Hz protocol

The Somfy RTS (identical to Simu Hz) protocol is used by a wide range of devices, which are either senders or receivers/actuators. Right now only SENDING of Somfy commands is implemented in the CULFW, so this module currently only supports devices like blinds, dimmers, etc. through a CUL device (which must be defined first). Reception of Somfy remotes is only supported indirectly through the usage of an FHEMduino http://www.fhemwiki.de/wiki/FHEMduino which can then be used to connect to the SOMFY device.

Define
define <name> SOMFY <address> [<encryption-key>] [<rolling-code>]

The address is a 6-digit hex code, that uniquely identifies a single remote control channel. It is used to pair the remote to the blind or dimmer it should control.
Pairing is done by setting the blind in programming mode, either by disconnecting/reconnecting the power, or by pressing the program button on an already associated remote.
Once the blind is in programming mode, send the "prog" command from within FHEM to complete the pairing. The blind will move up and down shortly to indicate completion.
You are now able to control this blind from FHEM, the receiver thinks it is just another remote control.
• <address> is a 6 digit hex number that uniquely identifies FHEM as a new remote control channel.
  You should use a different one for each device definition, and group them using a structure.
• The optional <encryption-key> is a 2 digit hex number (first letter should always be A) that can be set to clone an existing remote control channel.
• The optional <rolling-code> is a 4 digit hex number that can be set to clone an existing remote control channel.
  If you set one of them, you need to pick the same address as an existing remote. Be aware that the receiver might not accept commands from the remote any longer,
  if you used FHEM to clone an existing remote.
  This is because the code is original remote's codes are out of sync.

Rolling code and encryption key in the device definition will be always updated on commands sent and can be also changed manually by modifying the original definition (e.g in FHEMWeb - modify).

Examples:
define rollo_1 SOMFY 000001
define rollo_2 SOMFY 000002
define rollo_3_original SOMFY 42ABCD A5 0A1C


Set
set <name> <value> [<time>]

where value is one of:


    on
    off
    go-my
    stop
    pos value (0..100) # see note
    prog  # Special, see note
    wind_sun_9 
    wind_only_a
    on-for-timer
    off-for-timer
    manual 0,...,100,200,on,off
	

Examples:
set rollo_1 on
set rollo_1,rollo_2,rollo_3 on
set rollo_1-rollo_3 on
set rollo_1 off
set rollo_1 pos 50


Notes:
• prog is a special command used to pair the receiver to FHEM: Set the receiver in programming mode (eg. by pressing the program-button on the original remote) and send the "prog" command from FHEM to finish pairing.
  The blind will move up and down shortly to indicate success.
• on-for-timer and off-for-timer send a stop command after the specified time, instead of reversing the blind.
  This can be used to go to a specific position by measuring the time it takes to close the blind completely.
• pos value
  The position is variying between 0 completely open and 100 for covering the full window. The position must be between 0 and 100 and the appropriate attributes drive-down-time-to-100, drive-down-time-to-close, drive-up-time-to-100 and drive-up-time-to-open must be set. See also positionInverse attribute.
  
• wind_sun_9 and wind_only_a send special commands to the Somfy device that to represent the codes sent from wind and sun detector (with the respective code contained in the set command name)
• manual will only set the position without sending any commands to the somfy device - can be used to correct the position manually
The position reading distinuishes between multiple cases
• Without timing values (see attributes) set only generic values are used for status and position:

  open, closed, moving

  are used
• With timing values set but drive-down-time-to-close equal to drive-down-time-to-100 and drive-up-time-to-100 equal 0 the device is considered to only vary between 0 and 100 (100 being completely closed)
• With full timing values set the device is considerd a window shutter (Rolladen) with a difference between covering the full window (position 100) and being completely closed (position 200)

Get
N/A

Attributes
• IODev
  Set the IO or physical device which should be used for sending signals for this "logical" device. An example for the physical device is a CUL.
  Note: The IODev has to be set, otherwise no commands will be sent!
  If you have both a CUL868 and CUL433, use the CUL433 as IODev for increased range.


• positionInverse
  Inverse operation for positions instead of 0 to 100-200 the positions are ranging from 100 to 10 (down) and then to 0 (closed). The pos set command will point in this case to the reversed pos values. This does NOT reverse the operation of the on/off command, meaning that on always will move the shade down and off will move it up towards the initial position.


• additionalPosReading
  Position of the shutter will be stored in the reading pos as numeric value. Additionally this attribute might specify a name for an additional reading to be updated with the same value than the pos.


• finalPosReading
  This attribute can specify the name of an additional posReading that is only set at the end of a move. Meaning intermediate values are not set. The name can not be any of the standard readings


• fixed_enckey 1|0
  If set to 1 the enc-key is not changed after a command sent to the device. Default is value 0 meaning enc-key is changed normally for the RTS protocol.


• autoStoreRollingCode 1|0
  If set to 1 the rolling code is stored automatically in the FHEM uniqueID file (Default is 0 - off). After setting the attribute, the code is first saved after the next change of the rolling code.


• rawDevice [ ]
  If set this SOMFY device is representing a manual remote, that is used to control a somfy blind. The address of the blind (the physical blind) is specified in the rawdevice attribute to sync position changes in the blind when the remote is used. This requires an iodevice able to receive somfy commands (e.g. signalduino). Multiple physical blinds can be specified separated by space in the attribute.


• eventMap
  Replace event names and set arguments. The value of this attribute consists of a list of space separated values, each value is a colon separated pair. The first part specifies the "old" value, the second the new/desired value. If the first character is slash(/) or comma(,) then split not by space but by this character, enabling to embed spaces. Examples:
  attr store eventMap on:open off:closed
attr store eventMap /on-for-timer 10:open/off:closed/
set store open


• do_not_notify


• loglevel


• showtime


• model
  The model attribute denotes the model type of the device. The attributes will (currently) not be used by the fhem.pl directly. It can be used by e.g. external programs or web interfaces to distinguish classes of devices and send the appropriate commands (e.g. "on" or "off" to a switch, "dim..%" to dimmers etc.).
  The spelling of the model names are as quoted on the printed documentation which comes which each device. This name is used without blanks in all lower-case letters. Valid characters should be a-z 0-9 and - (dash), other characters should be ommited.
  Here is a list of "official" devices:
  Receiver/Actor: somfyblinds
  


• ignore
  Ignore this device, e.g. if it belongs to your neighbour. The device won't trigger any FileLogs/notifys, issued commands will silently ignored (no RF signal will be sent out, just like for the dummy attribute). The device won't appear in the list command (only if it is explicitely asked for it), nor will it appear in commands which use some wildcard/attribute as name specifiers (see devspec). You still get them with the "ignored=1" special devspec.


• drive-down-time-to-100
  The time the blind needs to drive down from "open" (pos 0) to pos 100.
  In this position, the lower edge touches the window frame, but it is not completely shut.
  For a mid-size window this time is about 12 to 15 seconds.


• drive-down-time-to-close
  The time the blind needs to drive down from "open" (pos 0) to "close", the end position of the blind.
  Note: If set, this value always needs to be higher than drive-down-time-to-100 This is about 3 to 5 seonds more than the "drive-down-time-to-100" value.


• drive-up-time-to-100
  The time the blind needs to drive up from "close" (endposition) to "pos 100".
  This usually takes about 3 to 5 seconds.


• drive-up-time-to-open
  The time the blind needs drive up from "close" (endposition) to "open" (upper endposition).
  Note: If set, this value always needs to be higher than drive-down-time-to-100 This value is usually a bit higher than "drive-down-time-to-close", due to the blind's weight.

SONOS

[EN DE]

FHEM-Module to communicate with the Sonos-System via UPnP

For more informations have also a closer look at the wiki at http://www.fhemwiki.de/wiki/SONOS

For correct functioning of this module it is neccessary to have some Perl-Modules installed, which are eventually installed already manually:

• LWP::Simple
• LWP::UserAgent
• SOAP::Lite
• HTTP::Request

Installation e.g. as Debian-Packages (via "sudo apt-get install <packagename>"):

• LWP::Simple-Packagename (incl. LWP::UserAgent and HTTP::Request): libwww-perl
• SOAP::Lite-Packagename: libsoap-lite-perl

Installation e.g. as Windows ActivePerl (via Perl-Packagemanager)

• Install Package LWP (incl. LWP::UserAgent and HTTP::Request)
• Install Package SOAP::Lite
• SOAP::Lite-Special for Versions after 5.18:
  • Add another Packagesource from suggestions or manual: Bribes de Perl (http://www.bribes.org/perl/ppm)
  • Install Package: SOAP::Lite

Windows ActivePerl 5.20 does currently not work due to missing SOAP::Lite

Attention!
This Module will not work on any platform, because of the use of Threads and the neccessary Perl-modules.

More information is given in a (german) Wiki-article: http://www.fhemwiki.de/wiki/SONOS

The system consists of two different components:
1. A UPnP-Client which runs as a standalone process in the background and takes the communications to the sonos-components.
2. The FHEM-module itself which connects to the UPnP-client to make fhem able to work with sonos.

The client will be started by the module itself if not done in another way.
You can start this client on your own (to let it run instantly and independent from FHEM):
perl 00_SONOS.pm 4711: Starts a UPnP-Client in an independant way who listens to connections on port 4711. This process can run a long time, FHEM can connect and disconnect to it.

Example

Simplest way to define:
define Sonos SONOS

Example with control over the used port and the isalive-checker-interval:
define Sonos SONOS localhost:4711 45

Define

define <name> SONOS [upnplistener [interval [waittime [delaytime]]]]

Define a Sonos interface to communicate with a Sonos-System.

[upnplistener]
The name and port of the external upnp-listener. If not given, defaults to localhost:4711. The port has to be a free portnumber on your system. If you don't start a server on your own, the script does itself.
If you start it yourself write down the correct informations to connect.

[interval]
The interval is for alive-checking of Zoneplayer-device, because no message come if the host disappear :-)
If omitted a value of 10 seconds is the default.

[waittime]
With this value you can configure the waiting time for the starting of the Subprocess.

[delaytime]
With this value you can configure a delay time before starting the network-part.

Set

• Common Tasks
  • RefreshShareIndex
    Starts the refreshing of the library.
  • RescanNetwork
    Restarts the player discovery.
• Control-Commands
  • Mute <state>
    Sets the mute-state on all players.
  • PauseAll
    Pause all Zoneplayer.
  • Pause
    Alias for PauseAll.
  • StopAll
    Stops all Zoneplayer.
  • Stop
    Alias for StopAll.
• Bookmark-Commands
  • DisableBookmark <Groupname>
    Disables the group with the given name.
  • EnableBookmark <Groupname>
    Enables the group with the given name.
  • LoadBookmarks [Groupname]
    Loads the given group (or all if parameter not set) from the filesystem.
  • SaveBookmarks [Groupname]
    Saves the given group (or all if parameter not set) to the filesystem.
• Group-Commands
  • Groups <GroupDefinition>
    Sets the current groups on the whole Sonos-System. The format is the same as retreived by getter 'Groups'.
    A reserved word is Reset. It can be used to directly extract all players out of their groups.

Get

• Group-Commands
  • Groups
    Retreives the current group-configuration of the Sonos-System. The format is a comma-separated List of Lists with devicenames e.g. [Sonos_Kueche], [Sonos_Wohnzimmer, Sonos_Schlafzimmer]. In this example there are two groups: the first consists of one player and the second consists of two players.
    The order in the sublists are important, because the first entry defines the so-called group-coordinator (in this case Sonos_Wohnzimmer), from which the current playlist and the current title playing transferred to the other member(s).

Attributes

'''Attention'''
The most of the attributes can only be used after a restart of fhem, because it must be initially transfered to the subprocess.

• Common
  • allowedWebAccess <value>
    Defines a regular Expression for allowed addresses for loading data. If not set, every access is allowed. e.g. ^http:\/\/192\.168\.0\.\d+.*$ for restricting access to local IP-addresses.
  • coverLoadTimeout <value>
    One of (0..10,15,20,25,30). Defines the timeout for waiting of the Sonosplayer for Cover-Downloads. Defaults to 5.
  • deviceRoomView <Both|DeviceLineOnly>
    Defines the style of the Device in the room overview. Both means "normal" Deviceline incl. Cover-/Titleview and maybe the control area, DeviceLineOnly means only the "normal" Deviceline-view.
  • disable <value>
    One of (0,1). With this value you can disable the whole module. Works immediatly. If set to 1 the subprocess will be terminated and no message will be transmitted. If set to 0 the subprocess is again started.
    It is useful when you install new Sonos-Components and don't want any disgusting devices during the Sonos setup.
  • getFavouritesListAtNewVersion <value>
    One of (0,1). With this attribute set, the module will refresh the Favourites-List automatically upon changes (if the Attribute getListsDirectlyToReadings is set).
  • getPlaylistsListAtNewVersion <value>
    One of (0,1). With this attribute set, the module will refresh the Playlists-List automatically upon changes (if the Attribute getListsDirectlyToReadings is set).
  • getQueueListAtNewVersion <value>
    One of (0,1). With this attribute set, the module will refresh the current Queue-List automatically upon changes (if the Attribute getListsDirectlyToReadings is set).
  • getRadiosListAtNewVersion <value>
    One of (0,1). With this attribute set, the module will refresh the Radios-List automatically upon changes (if the Attribute getListsDirectlyToReadings is set).
  • getListsDirectlyToReadings <value>
    One of (0,1). With this attribute you can define that the module fills the readings for the lists of Favourites, Playlists, Radios and the Queue directly without the need of userReadings.
  • getLocalCoverArt <value>
    One of (0,1). With this attribute the loads and saves the Coverart locally (default till now).
  • ignoredIPs <IP-Address>[,IP-Address]
    With this attribute you can define IP-addresses, which has to be ignored by the UPnP-System of this module. e.g. "192.168.0.11,192.168.0.37"
  • pingType <string>
    One of (none,tcp,udp,icmp,syn). Defines which pingType for alive-Checking has to be used. If set to 'none' no checks will be done.
  • reusePort <int>
    One of (0,1). If defined the socket-Attribute 'reuseport' will be used for SSDP Discovery-Port. Can solve restart-problems. If you don't have such problems don't use this attribute.
  • SubProcessLogfileName <Path>
    If given, the subprocess logs into its own logfile. Under Windows this is a recommended way for logging, because the two Loggings (Fehm and the SubProcess) overwrite each other. If "-" is given, the logging goes to STDOUT (and therefor in the Fhem-log) as usual. The main purpose of this attribute is the short-use of separated logging. No variables are substituted. The value is used as configured.
  • usedonlyIPs <IP-Adresse>[,IP-Adresse]
    With this attribute you can define IP-addresses, which has to be exclusively used by the UPnP-System of this module. e.g. "192.168.0.11,192.168.0.37"
• Bookmark Configuration
  • bookmarkSaveDir <path>
    Defines a directory where the saved bookmarks can be placed. If not defined, "." will be used.
  • bookmarkTitleDefinition <Groupname>:<PlayerdeviceRegEx>:<TrackURIRegEx>:<MinTitleLength>:<RemainingLength>:<MaxAge>:<ReadOnly>
    Definition of Bookmarks for titles.
  • bookmarkPlaylistDefinition <Groupname>:<PlayerdeviceRegEx>:<MinListLength>:<MaxListLength>:<MaxAge>
    Definition of bookmarks for playlists.
• Proxy Configuration
  • generateProxyAlbumArtURLs <int>
    One of (0, 1). If defined, all Cover-Links (the readings "currentAlbumArtURL" and "nextAlbumArtURL") are generated as links to the internal Sonos-Module-Proxy. It can be useful if you access Fhem over an external proxy and therefore have no access to the local network (the URLs are direct URLs to the Sonosplayer instead).
  • proxyCacheDir <Path>
    Defines a directory where the cached Coverfiles can be placed. If not defined "/tmp" will be used.
  • proxyCacheTime <int>
    A time in seconds. With a definition other than "0" the caching mechanism of the internal Sonos-Module-Proxy will be activated. If the filetime of the chached cover is older than this time, it will be reloaded from the Sonosplayer.
  • webname <String>
    With the attribute you can define the used webname for coverlinks. Defaults to 'fhem' if not given.
• Speak Configuration
  • targetSpeakDir <string>
    Defines, which Directory has to be used for the Speakfiles
  • targetSpeakMP3FileConverter <string>
    Defines an MP3-File converter, which properly converts the resulting speaking-file. With this option you can avoid timedisplay problems. Please note that the waittime before the speaking starts can increase with this option be set.
  • targetSpeakMP3FileDir <string>
    The directory which should be used as a default for text-embedded MP3-Files.
  • targetSpeakURL <string>
    Defines, which URL has to be used for accessing former stored Speakfiles as seen from the SonosPlayer
  • targetSpeakFileTimestamp <int>
    One of (0, 1). Defines, if the Speakfile should have a timestamp in his name. That makes it possible to store all historical Speakfiles.
  • targetSpeakFileHashCache <int>
    One of (0, 1). Defines, if the Speakfile should have a hash-value in his name. If this value is set to one an already generated file with the same hash is re-used and not newly generated.
  • Speak1 <Fileextension>:<Commandline>
    Defines a systemcall commandline for generating a speaking file out of the given text. If such an attribute is defined, an associated setter at the Sonosplayer-Device is available. The following placeholders are available:
    '''%language%''': Will be replaced by the given language-parameter
    '''%filename%''': Will be replaced by the complete target-filename (incl. fileextension).
    '''%text%''': Will be replaced with the given text.
    '''%textescaped%''': Will be replaced with the given url-encoded text.
  • Speak2 <Fileextension>:<Commandline>
    See Speak1
  • Speak3 <Fileextension>:<Commandline>
    See Speak1
  • Speak4 <Fileextension>:<Commandline>
    See Speak1
  • SpeakCover <Filename>
    Defines a Cover for use by the speak generation process. If not defined the Fhem-logo will be used.
  • Speak1Cover <Filename>
    See SpeakCover
  • Speak2Cover <Filename>
    See SpeakCover
  • Speak3Cover <Filename>
    See SpeakCover
  • Speak4Cover <Filename>
    See SpeakCover
  • SpeakGoogleURL <GoogleURL>
    The google-speak-url that has to be used. If empty a default will be used. You have to define placeholders for replacing the language- and text-value: %1$s -> Language, %2$s -> Text
    The Default-URL is currently: http://translate.google.com/translate_tts?tl=%1$s&client=tw-ob&q=%2$s

SONOSPLAYER

[EN DE]

FHEM module to work with a Sonos Zoneplayer

For more informations have also a closer look at the wiki at http://www.fhemwiki.de/wiki/SONOS

Normally you don't have to define a Sonosplayer-Device on your own, because the Sonos-Device will do this for you during the discovery-process.

Example

define Sonos_Wohnzimmer SONOSPLAYER RINCON_000EFEFEFEF401400_MR

Define

define <name> SONOSPLAYER <udn>

<udn>
MAC-Address based identifier of the zoneplayer

Set

• Common Tasks
  • Alarm (Create|Update|Delete|Enable|Disable) <ID[,ID]|All> <Datahash>
    Can be used for working on alarms:
    • Create: Creates an alarm-entry with the given datahash.
    • Update: Updates the alarm-entry with the given id(s) and datahash.
    • Delete: Deletes the alarm-entry with the given id(s).
    • Enable: Enables the alarm-entry with the given id(s).
    • Disable: Disables the alarm-entry with the gven id(s).
    If the Word 'All' is given as ID, all alarms of this player are changed.
    The Datahash:
    The Format is a perl-hash and is interpreted with the eval-function.
    e.g.: { Repeat => 1 }
    
    The following entries are allowed/neccessary:
    • StartTime
    • Duration
    • Recurrence_Once
    • Recurrence_Monday
    • Recurrence_Tuesday
    • Recurrence_Wednesday
    • Recurrence_Thursday
    • Recurrence_Friday
    • Recurrence_Saturday
    • Recurrence_Sunday
    • Enabled
    • ProgramURI
    • ProgramMetaData
    • Shuffle
    • Repeat
    • Volume
    • IncludeLinkedZones
    
    e.g.:
    • set Sonos_Wohnzimmer Alarm Create 0 { Enabled => 1, Volume => 35, StartTime => '00:00:00', Duration => '00:15:00', Repeat => 0, Shuffle => 0, ProgramURI => 'x-rincon-buzzer:0', ProgramMetaData => '', Recurrence_Once => 0, Recurrence_Monday => 1, Recurrence_Tuesday => 1, Recurrence_Wednesday => 1, Recurrence_Thursday => 1, Recurrence_Friday => 1, Recurrence_Saturday => 0, Recurrence_Sunday => 0, IncludeLinkedZones => 0 }
    • set Sonos_Wohnzimmer Alarm Update 17 { Shuffle => 1 }
    • set Sonos_Wohnzimmer Alarm Delete 17 {}
  • AudioDelay <Level>
    Sets the audiodelay of the player to the given value. The value can range from 0 to 5.
  • AudioDelayLeftRear <Level>
    Sets the audiodelayleftrear of the player to the given value. The value can range from 0 to 2. The values has the following meanings: 0: >3m, 1: >0.6m und <3m, 2: <0.6m
  • AudioDelayRightRear <Level>
    Sets the audiodelayrightrear of the player to the given value. The value can range from 0 to 2. The values has the following meanings: 0: >3m, 1: >0.6m und <3m, 2: <0.6m
  • ButtonLockState <int>
    One of (0, 1) Sets the current state of the ButtonLockState.
  • DailyIndexRefreshTime <Timestring>
    Sets the current DailyIndexRefreshTime for the whole bunch of Zoneplayers.
  • DialogLevel <State>
    Sets the dialoglevel for playbar-systems.
  • ExportSonosBibliothek <filename>
    Exports a file with a textual representation of a structure- and titlehash of the complete Sonos-Bibliothek. Warning: Will use a large amount of CPU-Time and RAM!
  • Name <Zonename>
    Sets the Name for this Zone
  • NightMode <State>
    Sets the nightmode for playbar-systems.
  • OutputFixed <State>
    Sets the outputfixed-state. Retrieves the new state as the result.
  • Reboot
    Initiates a reboot on the Zoneplayer.
  • ResetAttributesToDefault <DeleteAllOtherAttributes>
    Sets the attributes to the inital state. If the parameter "DeleteAllOtherAttributes" is set to "1" or "on", all attributes will be deleted before the defaults will be newly retrieved from the player and set.
  • RoomIcon <Iconname>
    Sets the Icon for this Zone
  • SnoozeAlarm <Timestring|Seconds>
    Snoozes a currently playing alarm for the given time
  • SubEnable <State>
    Sets the substate for sub-systems.
  • SubGain <Level>
    Sets the sub-gain for sub-systems. The value can range from -15 to 15.
  • SubPolarity <Level>
    Sets the sub-polarity for sub-systems. The value can range from 0 to 2.
  • SurroundEnable <State>
    Sets the surround-state for surround-systems (like playbars).
  • SurroundLevel <Level>
    Sets the surround-level for surround-systems (like playbars). The value can range from -15 to 15.
  • TruePlay <State>
    Sets the TruePlay-State of the given player.
  • Wifi <State>
    Sets the WiFi-State of the given Player. Can be 'off', 'persist-off' or 'on'.
• Playing Control-Commands
  • CurrentTrackPosition <TimePosition>
    Sets the current timeposition inside the title to the given timevalue (e.g. 0:01:15) or seconds (e.g. 81). You can make relative jumps like '+0:00:10' or just '+10'. Additionally you can make a call with a percentage value like '+10%'. This relative value can be negative.
  • Pause
    Pause the playing
  • Previous
    Jumps to the beginning of the previous title.
  • Play
    Starts playing
  • PlayT
    Starts playing, if player is currently stopped, pauses playing otherwise
  • PlayURI <songURI> [Volume]
    Plays the given MP3-File with the optional given volume.
  • PlayURITemp <songURI> [Volume]
    Plays the given MP3-File with the optional given volume as a temporary file. After playing it, the whole state is reconstructed and continues playing at the former saved position and volume and so on. If the file given is a stream (exactly: a file where the running time could not be determined), the call would be identical to ,PlayURI, e.g. nothing is restored after playing.
  • Next
    Jumps to the beginning of the next title
  • Speak <Volume> <Language> <Text>
    Uses the Google Text-To-Speech-Engine for generating MP3-Files of the given text and plays it on the SonosPlayer. Possible languages can be obtained from Google. e.g. "de", "en", "fr", "es"...
  • StartFavourite <Favouritename> [NoStart]
    Starts the named sonos-favorite. The parameter should be URL-encoded for proper naming of lists with special characters. If the Word 'NoStart' is given as second parameter, than the Loading will be done, but the playing-state is leaving untouched e.g. not started.
    Additionally it's possible to use a regular expression as the name. The first hit will be used. The format is e.g. /meine.hits/.
  • StartPlaylist <Playlistname> [EmptyQueueBeforeImport]
    Loads the given Playlist and starts playing immediately. For all Options have a look at "LoadPlaylist".
  • StartRadio <Radiostationname>
    Loads the named radiostation (favorite) and starts playing immediately. For all Options have a look at "LoadRadio".
  • StartSearchlist <Categoryname> <CategoryElement> [[TitlefilterRegEx]/[AlbumfilterRegEx]/[ArtistfilterRegEx] [maxElem]]
    Loads the searchlist and starts playing immediately. For all Options have a look at "LoadSearchlist".
  • Stop
    Stops the playing
  • Track <TrackNumber|Random>
    Sets the track with the given tracknumber as the current title. If the tracknumber is the word Random a random track will be selected.
• Playing Settings
  • Balance <BalanceValue>
    Sets the balance to the given value. The value can range from -100 (full left) to 100 (full right). Retrieves the new balancevalue as the result.
  • Bass <BassValue>
    Sets the bass to the given value. The value can range from -10 to 10. Retrieves the new bassvalue as the result.
  • CrossfadeMode <State>
    Sets the crossfade-mode. Retrieves the new mode as the result.
  • LEDState <State>
    Sets the LED state. Retrieves the new state as the result.
  • Loudness <State>
    Sets the loudness-state. Retrieves the new state as the result.
  • Mute <State>
    Sets the mute-state. Retrieves the new state as the result.
  • MuteT
    Toggles the mute state. Retrieves the new state as the result.
  • Repeat <State>
    Sets the repeat-state. Retrieves the new state as the result.
  • RepeatOne <State>
    Sets the repeatOne-state. Retrieves the new state as the result.
  • RepeatOneT
    Toggles the repeatOne-state. Retrieves the new state as the result.
  • RepeatT
    Toggles the repeat-state. Retrieves the new state as the result.
  • Shuffle <State>
    Sets the shuffle-state. Retrieves the new state as the result.
  • ShuffleT
    Toggles the shuffle-state. Retrieves the new state as the result.
  • SleepTimer <Timestring|Seconds>
    Sets the Sleeptimer to the given Time. It must be in the full format of "HH:MM:SS". Deactivate with "00:00:00" or "off".
  • Treble <TrebleValue>
    Sets the treble to the given value. The value can range from -10 to 10. Retrieves the new treblevalue as the result.
  • Volume <VolumeLevel> [RampType]
    Sets the volume to the given value. The value could be a relative value with + or - sign. In this case the volume will be increased or decreased according to this value. Retrieves the new volume as the result.
    Optional can be a RampType defined with a value between 1 and 3 which describes different templates defined by the Sonos-System.
  • VolumeD
    Turns the volume by volumeStep-ticks down.
  • VolumeRestore
    Restores the volume of a formerly saved volume.
  • VolumeSave <VolumeLevel>
    Sets the volume to the given value. The value could be a relative value with + or - sign. In this case the volume will be increased or decreased according to this value. Retrieves the new volume as the result. Additionally it saves the old volume to a reading for restoreing.
  • VolumeU
    Turns the volume by volumeStep-ticks up.
• Control the current Playlist
  • AddURIToQueue <songURI>
    Adds the given MP3-File at the current position into the queue.
  • CurrentPlaylist
    Sets the current playing to the current queue, but doesn't start playing (e.g. after hearing of a radiostream, where the current playlist still exists but is currently "not in use")
  • DeleteFromQueue
    Deletes the elements from the current queue with the given indices. You can use the ususal perl-array-formats like "1..12,17,20..22". The indices reference to the position in the current view of the list (this usually differs between the normal playmode and the shuffleplaymode).
  • DeletePlaylist
    Deletes the Sonos-Playlist with the given name. According to the possibilities of the playlistname have a close look at LoadPlaylist.
  • EmptyPlaylist
    Clears the current queue
  • LoadFavourite <Favouritename>
    Loads the named sonos-favorite. The parameter should be URL-encoded for proper naming of lists with special characters.
    Additionally it's possible to use a regular expression as the name. The first hit will be used. The format is e.g. /meine.hits/.
  • LoadPlaylist <Playlistname|Fhem-Devicename> [EmptyQueueBeforeImport]
    Loads the named playlist to the current playing queue. The parameter should be URL-encoded for proper naming of lists with special characters. The Playlistnamen can be an Fhem-Devicename, then the current playlist of this referenced player will be copied. The Playlistname can also be a filename and then must be startet with 'file:' (e.g. 'file:c:/Test.m3u')
    If EmptyQueueBeforeImport is given and set to 1, the queue will be emptied before the import process. If not given, the parameter will be interpreted as 1.
    Additionally it's possible to use a regular expression as the name. The first hit will be used. The format is e.g. /hits.2014/.
  • LoadRadio <Radiostationname>
    Loads the named radiostation (favorite). The current queue will not be touched but deactivated. The parameter should be URL-encoded for proper naming of lists with special characters.
    Additionally it's possible to use a regular expression as the name. The first hit will be used. The format is e.g. /radio/.
  • LoadSearchlist <Categoryname> <CategoryElement> [[TitlefilterRegEx]/[AlbumfilterRegEx]/[ArtistfilterRegEx] [[*]maxElem[+|-]]]
    Loads titles from the Sonos-Bibliothek into the current playlist according to the given category and filtervalues. Please consult the (german) Wiki for detailed informations.
  • SavePlaylist <Playlistname>
    Saves the current queue as a playlist with the given name. An existing playlist with the same name will be overwritten. The parameter should be URL-encoded for proper naming of lists with special characters. The Playlistname can be a filename and then must be startet with 'file:' (e.g. 'file:c:/Test.m3u')
• Groupcontrol
  • AddMember <devicename>
    Adds the given devicename to the current device as a groupmember. The current playing of the current device goes on and will be transfered to the given device (the new member).
  • CreateStereoPair <rightPlayerDevicename>
    Adds the given devicename to the current device as the right speaker of a stereopair. The current playing of the current device goes on (as left-side speaker) and will be transfered to the given device (as right-side speaker).
  • GroupMute <State>
    Sets the mute state of the complete group in one step. The value can be on or off.
  • GroupVolume <VolumeLevel>
    Sets the group-volume in the way the original controller does. This means, that the relative volumelevel between the different players will be saved during change.
  • GroupVolumeD
    Turns the group volume by volumeStep-ticks down.
  • GroupVolumeU
    Turns the group volume by volumeStep-ticks up.
  • MakeStandaloneGroup
    Makes this Player a standalone group.
  • RemoveMember <devicename>
    Removes the given device, so that they both are not longer a group. The current playing of the current device goes on normally. The cutted device stops his playing and has no current playlist anymore (since Sonos Version 4.2 the old playlist will be restored).
  • SeparateStereoPair
    Divides the stereo-pair into two independant devices.
  • SnapshotGroupVolume
    Save the current volume-relation of all players of the same group. It's neccessary for the use of "GroupVolume" and is stored until the next call of "SnapshotGroupVolume".

Get

• Common
  • Alarm <ID>
    It's an exception to the normal getter semantics. Returns directly a Perl-Hash with the Alarm-Informations to the given id. It's just a shorthand for eval(ReadingsVal(<Devicename>, 'Alarmlist', ()))->{<ID>};.
  • EthernetPortStatus <PortNumber>
    Gets the Ethernet-Portstatus of the given Port. Can be 'Active' or 'Inactive'.
  • PossibleRoomIcons
    Retreives a list of all possible Roomiconnames for the use with "set RoomIcon".
  • SupportLinks
    Shows a list with direct links to the player-support-sites.
  • WifiPortStatus
    Gets the Wifi-Portstatus. Can be 'Active' or 'Inactive'.
• Lists
  • Favourites
    Retrieves a list with the names of all sonos favourites. This getter retrieves the same list on all Zoneplayer. The format is a comma-separated list with quoted names of favourites. e.g. "Liste 1","Entry 2","Test"
  • FavouritesWithCovers
    Retrieves a list with the stringrepresentation of a perl-hash which can easily be converted with "eval". It consists of the names and coverlinks of all of the favourites stored in Sonos e.g. {'FV:2/22' => {'Cover' => 'urlzumcover', 'Title' => '1. Favorit'}}
  • Playlists
    Retrieves a list with the names of all saved queues (aka playlists). This getter retrieves the same list on all Zoneplayer. The format is a comma-separated list with quoted names of playlists. e.g. "Liste 1","Liste 2","Test"
  • PlaylistsWithCovers
    Retrieves a list with the stringrepresentation of a perl-hash which can easily be converted with "eval". It consists of the names and coverlinks of all of the playlists stored in Sonos e.g. {'SQ:14' => {'Cover' => 'urlzumcover', 'Title' => '1. Playlist'}}
  • Queue
    Retrieves a list with the names of all titles in the current queue. This getter retrieves the same list on all Zoneplayer. The format is a comma-separated list with quoted names of the titles. e.g. "1. Liste 1 [0:02:14]","2. Eintrag 2 [k.A.]","3. Test [0:14:00]"
  • QueueWithCovers
    Retrieves a list with the stringrepresentation of a perl-hash which can easily be converted with "eval". It consists of the names and coverlinks of all of the titles in the current queue. e.g.: {'Q:0/22' => {'Cover' => 'urlzumcover', 'Title' => '1. Titel'}}.
  • Radios
    Retrieves a list with the names of all saved radiostations (favorites). This getter retrieves the same list on all Zoneplayer. The format is a comma-separated list with quoted names of radiostations. e.g. "Sender 1","Sender 2","Test"
  • RadiosWithCovers
    Retrieves a list with the stringrepresentation of a perl-hash which can easily be converted with "eval". It consists of the names and coverlinks of all of the radiofavourites stored in Sonos e.g. {'R:0/0/2' => {'Cover' => 'urlzumcover', 'Title' => '1. Radiosender'}}
  • SearchlistCategories
    Retrieves a list with the possible categories for the setter "LoadSearchlist". The Format is a comma-separated list with quoted names of categories.
• Informations on the current Title
  • CurrentTrackPosition
    Retrieves the current timeposition inside a title

Attributes

'''Attention'''
The attributes can only be used after a restart of fhem, because it must be initially transfered to the subprocess.

• Common
  • disable <int>
    One of (0,1). Disables the event-worker for this Sonosplayer.
  • generateSomethingChangedEvent <int>
    One of (0,1). 1 if a 'SomethingChanged'-Event should be generated. This event is thrown every time an event is generated. This is useful if you wants to be notified on every change with a single event.
  • generateVolumeEvent <int>
    One of (0,1). Enables an event generated at volumechanges if minVolume or maxVolume is set.
  • generateVolumeSlider <int>
    One of (0,1). Enables a slider for volumecontrol in detail view.
  • getAlarms <int>
    One of (0..1). Initializes a callback-method for Alarms. This included the information of the DailyIndexRefreshTime.
  • suppressControlButtons <int>
    One of (0,1). Enables the control-section shown under the Cover-/Titleview.
  • volumeStep <int>
    One of (0..100). Defines the stepwidth for subsequent calls of VolumeU and VolumeD.
• Information Generation
  • generateInfoSummarize1 <string>
    Generates the reading 'InfoSummarize1' with the given format. More Information on this in the examples-section.
  • generateInfoSummarize2 <string>
    Generates the reading 'InfoSummarize2' with the given format. More Information on this in the examples-section.
  • generateInfoSummarize3 <string>
    Generates the reading 'InfoSummarize3' with the given format. More Information on this in the examples-section.
  • generateInfoSummarize4 <string>
    Generates the reading 'InfoSummarize4' with the given format. More Information on this in the examples-section.
  • getTitleInfoFromMaster <int>
    One of (0, 1). Gets the current Playing-Informations from the Masterplayer (if one is present).
  • simulateCurrentTrackPosition <int>
    One of (0,1,2,3,4,5,6,7,8,9,10,15,20,25,30,45,60). Starts an internal Timer which refreshs the current trackposition into the Readings currentTrackPositionSimulated and currentTrackPositionSimulatedSec. At the same time the Reading currentTrackPositionSimulatedPercent (between 0.0 and 100.0) will also be refreshed.
  • simulateCurrentTrackPositionPercentFormat <Format>
    Defines the format of the percentformat in the Reading currentTrackPositionSimulatedPercent.
  • stateVariable <string>
    One of (TransportState,NumberOfTracks,Track,TrackURI,TrackDuration,Title,Artist,Album,OriginalTrackNumber,AlbumArtist,
    Sender,SenderCurrent,SenderInfo,StreamAudio,NormalAudio,AlbumArtURI,nextTrackDuration,nextTrackURI,nextAlbumArtURI,
    nextTitle,nextArtist,nextAlbum,nextAlbumArtist,nextOriginalTrackNumber,Volume,Mute,Shuffle,Repeat,RepeatOne,CrossfadeMode,Balance,
    HeadphoneConnected,SleepTimer,Presence,RoomName,SaveRoomName,PlayerType,Location,SoftwareRevision,SerialNum,InfoSummarize1,
    InfoSummarize2,InfoSummarize3,InfoSummarize4). Defines, which variable has to be copied to the content of the state-variable.
• Controloptions
  • maxVolume <int>
    One of (0..100). Define a maximal volume for this Zoneplayer
  • minVolume <int>
    One of (0..100). Define a minimal volume for this Zoneplayer
  • maxVolumeHeadphone <int>
    One of (0..100). Define a maximal volume for this Zoneplayer for use with headphones
  • minVolumeHeadphone <int>
    One of (0..100). Define a minimal volume for this Zoneplayer for use with headphones
  • buttonEvents <Time:Pattern>[ <Time:Pattern> ...]
    Defines that after pressing a specified sequence of buttons at the player an event has to be thrown. The definition itself is a tupel: the first part (before the colon) is the time in seconds, the second part (after the colon) is the button sequence of this event.
    The following button-shortcuts are possible:
    • M: The Mute-Button
    • H: The Headphone-Connector
    • U: Up-Button (Volume Up)
    • D: Down-Button (Volume Down)
    
    The event thrown is named ButtonEvent, the value is the defined button-sequence.
    E.G.: 2:MM
    Here an event is defined, where in time of 2 seconds the Mute-Button has to be pressed 2 times. The created event is named ButtonEvent and has the value MM.
• saveSleeptimerInAction <int>
  One of (0..1). If set, a possibly set Attribute "stopSleeptimerInAction" will be ignored.
• stopSleeptimerInAction <int>
  One of (0..1). If set, a change of the current transportState to "PAUSED_PLAYBACK" or "STOPPED" will cause a stopping of an eventually running SleepTimer.

Examples / Tips

• Format of InfoSummarize:
  infoSummarizeX := <NormalAudio>:summarizeElem:</NormalAudio> <StreamAudio>:summarizeElem:</StreamAudio>|:summarizeElem:
:summarizeElem: := <:variable:[ prefix=":text:"][ suffix=":text:"][ instead=":text:"][ ifempty=":text:"]/[ emptyVal=":text:"]>
:variable: := TransportState|NumberOfTracks|Track|TrackURI|TrackDuration|Title|Artist|Album|OriginalTrackNumber|AlbumArtist|
Sender|SenderCurrent|SenderInfo|StreamAudio|NormalAudio|AlbumArtURI|nextTrackDuration|nextTrackURI|nextAlbumArtURI|
nextTitle|nextArtist|nextAlbum|nextAlbumArtist|nextOriginalTrackNumber|Volume|Mute|Shuffle|Repeat|RepeatOne|CrossfadeMode|Balance|
HeadphoneConnected|SleepTimer|Presence|RoomName|SaveRoomName|PlayerType|Location|SoftwareRevision|SerialNum|InfoSummarize1|
InfoSummarize2|InfoSummarize3|InfoSummarize4
:text: := [Any text without double-quotes]
  

SSCal

[EN DE]

This module is used to integrate Synology Calendar Server with FHEM. The SSCal module is based on functions of Synology Calendar API.

The connection to the calendar server is established via a session ID after successful login. Requirements/queries of the server are stored internally in a queue and processed sequentially. If the calendar server is temporarily unavailable the saved queries are retrieved as soon as the connection to the server is working again.

Both appointment calendars (Events) and task lists (ToDo) can be processed. For these different calendar types different device models can be defined, Model Diary for appointments and Model Tasks for Task lists.

If you want discuss about or like to support the development of this module, there is a thread in the FHEM forum:
57_SSCal - Modul für den Synology Kalender.

Further information about the module you can find in the (german) FHEM Wiki:
SSCal - Integration des Synology Calendar Servers.


Preparation


As basic requirement the Synology Calendar Package must be installed on your Synology Disc Station.
In Synology DSM a user as member of the administrator group must be defined for access use. This user must also have the rights to read and/or write the relevant calendars. The entitlement for the calendars are set directly in the Synology calendar application. The login credentials are assigned later by the set credentials command to the defined device.

Furthermore some more Perl modules must be installed or available:



JSON
Data::Dumper
MIME::Base64
Time::HiRes
Encode
POSIX
HttpUtils	(FHEM module)
Blocking	(FHEM module)
Meta	(FHEM module)




Definition

The creation of SSCal devices is differed between the definition of diaries and task lists.

The definition is done with:


define <Name> SSCal <ServerAddr> [<Port>] [<Protocol>] [Tasks]


The parameters are in detail:



Name	Name of the device in FHEM
ServerAddr	IP address of Synology Disc Station. Note: If you use DNS name instead of IP address, don't forget to set the attribute dnsServer in global device !
Port	optional - Port of Synology Disc Station (default: 5000).
Protocol	optional - Protocol used for communication with the calendar server, http or https (default: http).
Tasks	optional - to define a task list device add "Tasks" to the definition



Examples:

      define Appointments SSCal 192.168.2.10 
      define Appointments SSCal 192.168.2.10 5001 https 
      # creates a diary device on default port (5000/http) respectively https on port 5001

      define Tasklist SSCal ds.myds.org 5001 https Tasks 
      # creates a task list device with protocol https on port 5001
     

After definition of a device only the command credentials is available. First of all you have to set the credentials for communication with the Synology calendar server by using this command.

If the login was successful, all for the user accessible calendars will be determined. The calendars to retrieve are selectable by attribute usedCalendars.



Set

The following set commands are valid for both device models Diary/Tasks or partly for one of these device models.


• calUpdate [<list of calendars>]
  Fetch entries of the selected calendars (see attribute usedCalendars). Alternatively you can enter a list of calendars to fetch separated by comma. The calendar names may contain spaces.
  
  
  Examples:
  
  set Appointments calUpdate
  # fetch the entries of calendars specified in attribute usedCalendars
  
  set Appointments calUpdate Heikos Kalender,Abfall
  # fetch the entries of both calendars "Heikos Kalender" and "Abfall".
  
  


• cleanCompleteTasks     (only model "Tasks")
  All completed tasks in the specified task lists (see attribute usedCalendars) are deleted.
  


• deleteEventId <Id>
  The specified Event Id (see reading x_x_EventId) will be delted from calendar or tas list.
  


• credentials <User> <Passwort>
  Store the credentials for calendar communication.
  


• eraseReadings
  Delete all calendar readings. It doesn't effect the calendar entries itself !
  


• listSendqueue
  Shows all entries in the sendqueue. Normally the queue is filled only for a short time, but may contain entries permanently in case of problems. Thereby the occured failures can be identified and assigned.
  


• logout
  The user will be logged out and the session to the Synology Disc Station will be cleared.
  


• purgeSendqueue
  Deletes entries from the sendqueue. Several options are usable dependend from situation:
  
  

  -all-	deletes all entries from sendqueue
  -permError-	deletes all entries which are suspended from further processing caused by a permanent error
  <Index>	deletes the specified entry from sendqueue



• restartSendqueue
  The processing of entries in sendqueue will be new started manually. Because of the sendqueue will be restarted automatically by every new retrieval it is normally not necessary to execute this command.
  


Get


• apiInfo
  Retrieves the API informations of the Synology calendar server and open a popup window with its data.
  


• calAsHtml
  Shows a popup with the time summary. In own perl routines and for integration in a weblink device this overview can be used as follows:
  
  
  { FHEM::SSCal::calAsHtml ("<SSCal-Device>") }


• getCalendars
  Requests the existing calendars from your Synology Disc Station and open a popup window with informations about each available calendar.



• storedCredentials
  Shows the stored User/Password combination.



• versionNotes
  Shows important informations and hints about the module.



Attribute


• asyncMode
  If set to "1", the data parsing will be executed within a background process and avoid possible blocking situations.
  (default: 0)


• createATDevs
  If set to "1", FHEM commands and Perl routines to be executed are recognised automatically in a calendar entry by SSCal. In this case SSCal defines, changes or deletes at-devices to execute these commands independently.
  A FHEM command to be executed has to be included into { } in the field Description of Synology Calendar application WebUI, Perl routines has to be included into double {{ }}.
  For further detailed information please read the Wiki (germnan) section: at-Devices für Steuerungen automatisch erstellen und verwalten lassen.
  (default: 0)


• cutOlderDays
  Entries in calendars are ignored if the due date is older than the number of specified days.
  (default: 5)
  
  
  Example:
  
  attr <Name> cutOlderDays 30
  


• cutLaterDays
  Entries in calendars are ignored if the due date is later than the number of specified days.
  (default: 5)
  
  
  Example:
  
  attr <Name> cutLaterDays 90
  


• filterCompleteTask     (only model "Tasks")
  Entries of the calendar are filtered dependend from their completion:
  
  

  1	only completed tasks are shown
  2	only not completed tasks are shown
  3	completed and not completed tasks are shown (default)



• filterDueTask     (only model "Tasks")
  Entries in taks lists with/without due date are filtered:
  
  

  1	only tasks with due date are shown
  2	only tasks without due date are shown
  3	tasks with and without due date are shown (default)



• interval <seconds>
  Interval in seconds to fetch calendar entries automatically. If "0" is specified, no calendar fetch is executed. (default)
  
  
  Example:
  
  Set the attribute as follows if the calendar entries should retrieved every hour:
  attr <Name> interval 3600
  


• loginRetries
  Number of attempts for the initial user login.
  (default: 3)


• showRepeatEvent     (only model "Diary")
  If "true", one-time events as well as recurrent events are fetched. Otherwise only one-time events are retrieved.
  (default: true)


• showPassInLog
  If "1", the password respectively the SID will be shown in the logfile.
  (default: 0)


• tableColumnMap
  Determines how the link to a map is shown in the table column "Map":
  
  

  icon	shows a user customisable symbol (default)
  data	shows the GPS data
  text	shows a text adjustable by the user

  
  To make further adjustments, there are some more possibilities to specify properties in the attribute tableSpecs. For detailed informations about the possibilities to configure the overview table please consult the (german) Wiki chapter Darstellung der Übersichtstabelle in Raum- und Detailansicht beeinflussen.
  


• tableInDetail
  An overview diary or taks table will be displayed in detail view.
  (default: 1)


• tableInRoom
  An overview diary or taks table will be displayed in room view.
  (default: 1)


• tableFields
  Selection of the fields to be displayed in the overview table in room or detail view.
  


• tableSpecs
  By several key-value pair combinations the presentation of informations in the overview table can be adjusted. The (german) Wiki chapter Darstellung der Übersichtstabelle in Raum- und Detailansicht beeinflussen provides more detailed help for it.


• timeout <seconds>
  Timeout for calendar fetch in seconds.
  (default: 20)


• usedCalendars
  Selection of calendars to fetch from a popup window. The list of accessible calendars will initial be created during FHEM startup. At all times it can also be done manually with command:
  
  
  get <Name> getCalendars
  
  
  As long as the accessible calendars are not successfully fetched, this attribute only contains simply the entry:
  
  
  --wait for Calendar list--
  



Hints for event generation

Depending on the volume of the retrieved data, a large number of readings can be created. To avoid too extensive event generation in FHEM, the attribute event-on-update-reading is preset after definition of the calendar device to:


attr event-on-update-reading.*Summary.*,state

If events are to be created for all readings, event-on-update-reading must be set to .* and mustn't be deleted.

SSCal generates additional events for each event, which contains a start time, with each new read-in of a calendar. These events provide the user with assistance in creating his own control logic in FHEM based on calendar entries.

The event composite contains the information fields:


• block number of the appointment
• Event ID of the appointment
• indicator for a serial appointment (0=no serial appointment or 1=serial appointment)
• start time in ISO 8601 format
• Status of the event
• the text in Description (corresponds to the Description field in Synology Calendar WebUI) or the text in Summary if Description is not set

The event compositeBlockNumbers contains the block numbers of all events of the calendar. If there are no appointments, this event has only the value none.

SSCam

[EN DE]

Using this Module you are able to operate cameras which are defined in Synology Surveillance Station (SVS) and execute functions of the SVS. It is based on the SVS API and supports the SVS version 7 and above.
At present the following functions are available:


• Start a recording and send it optionally by Email and/or Telegram
• Stop a recording by command or automatically after an adjustable period
• Trigger of snapshots / recordings and optional send them alltogether by Email using the integrated Email client or by Synology Chat / Telegram
• Trigger snapshots of all defined cams and optionally send them alltogether by Email using the integrated Email client
• Deaktivate a Camera in Synology Surveillance Station
• Activate a Camera in Synology Surveillance Station
• Control of the exposure modes day, night and automatic
• switchover the motion detection by camera, by SVS or deactivate it
• control of motion detection parameters sensitivity, threshold, object size and percentage for release
• Retrieval of Camera Properties (also by Polling) as well as informations about the installed SVS-package
• Move to a predefined Preset-position (at PTZ-cameras)
• Start a predefined Patrol (at PTZ-cameras)
• Positioning of PTZ-cameras to absolute X/Y-coordinates
• continuous moving of PTZ-camera lense
• trigger of external events 1-10 (action rules in SVS)
• start and stop of camera livestreams incl. audio replay, show the last recording and snapshot
• fetch of livestream-Url's with key (login not needed in that case)
• playback of last recording and playback the last snapshot
• switch the Surveillance Station HomeMode on/off and retrieve the HomeModeState
• show the stored credentials of a device
• fetch the Surveillance Station Logs, exploit the newest entry as reading
• create a gallery of the last 1-10 snapshots (as Popup or in a discrete device)
• Start/Stop Object Tracking (only supported PTZ-Cams with this capability)
• set/delete a Preset (at PTZ-cameras)
• set a Preset or current position as Home Preset (at PTZ-cameras)
• provides a panel for camera control (at PTZ-cameras)
• create different types of discrete Streaming-Devices (createStreamDev)
• Activation / Deactivation of a camera integrated PIR sensor
• Creation of a readingsGroup device to display an overview of all defined SSCam devices (createReadingsGroup)
• automatized definition of all in SVS available cameras in FHEM (autocreateCams)
• save the last recording or the last snapshot of camera locally
• Selection of several cache types for image data storage (attribute cacheType)
• execute Zoom actions (only if PTZ camera supports Zoom)

The recordings and snapshots will be stored in Synology Surveillance Station (SVS) and are managed like the other (normal) recordings / snapshots defined by Surveillance Station rules.
For example the recordings are stored for a defined time in Surveillance Station and will be deleted after that period.

If you like to discuss or help to improve this module please use FHEM-Forum with link:
49_SSCam: Fragen, Hinweise, Neuigkeiten und mehr rund um dieses Modul.

Integration into FHEM TabletUI:

There is a widget provided for integration of SSCam-Streaming devices (Type SSCamSTRM) into FTUI. For further information please be informed by the (german) FHEM Wiki article:
FTUI Widget für SSCam Streaming Devices (SSCamSTRM).


Prerequisites


This module uses the Perl-modules JSON and MIME::Lite which are usually have to be installed in addition.
On Debian-Linux based systems these modules can be installed by:

sudo apt-get install libjson-perl
sudo apt-get install libmime-lite-perl

SSCam is completely using the nonblocking functions of HttpUtils respectively HttpUtils_NonblockingGet.
In DSM respectively in Synology Surveillance Station an User has to be created. The login credentials are needed later when using a set-command to assign the login-data to a device.
Further informations could be find among Credentials.

Overview which Perl-modules SSCam is using:



JSON
Data::Dumper
MIME::Base64
Time::HiRes
Encode
POSIX
HttpUtils	(FHEM-module)
Blocking	(FHEM-module)
Meta	(FHEM-module)
Net::SMTP	(if integrated image data transmission is used)
MIME::Lite	(if integrated image data transmission is used)
CHI	(if Cache is used)
CHI::Driver::Redis	(if Cache is used)
Cache::Cache	(if Cache is used)


SSCam uses its own icons. In order for the system to find the icons, the attribute iconPath must be supplemented with sscam in the FHEMWEB device.


Example
attr WEB iconPath default:fhemSVG:openautomation:sscam



Define

There is a distinction between the definition of a camera-device and the definition of a Surveillance Station (SVS) device, that means the application on the discstation itself. Dependend on the type of defined device the internal MODEL will be set to "<vendor> - <camera type>" or "SVS" and a proper subset of the described set/get-commands are assigned to the device.
The scope of application of set/get-commands is denoted to every particular command (valid for CAM, SVS, CAM/SVS).
The cameras can be defined manually discrete, but alternatively with an automatical procedure by set "autocreateCams" command in a previously defined SVS device.

A camera device is defined by:


define <Name> SSCAM <camera name in SVS> <ServerAddr> [Port] [Protocol]


At first the devices have to be set up and has to be operable in Synology Surveillance Station 7.0 and above.

A SVS-device to control functions of the Surveillance Station (SVS) is defined by:


define <Name> SSCAM SVS <ServerAddr> [Port] [Protocol]


In that case the term <camera name in SVS> become replaced by SVS only.
Is the SVS defined and after setting the appropriate creadentials ready for use, all cameras available in SVS can be created automatically in FHEM with the set command "autocreateCams".

The Modul SSCam ist based on functions of Synology Surveillance Station API.

The parameters are in detail:



Name	the name of the new device to use in FHEM
Cameraname	camera name as defined in Synology Surveillance Station if camera-device, "SVS" if SVS-Device. Spaces are not allowed in camera name.
ServerAddr	IP-address of Synology Surveillance Station Host. Note: avoid using hostnames because of DNS-Calls are not unblocking in FHEM
Port	optional - the port of synology disc station. If not set, the default "5000" is used
Protocol	optional - the protocol (http or https) to access the synology disc station. If not set, the default "http" is used



Examples:

      define CamCP SSCAM Carport 192.168.2.20 [5000] [http]
      define CamCP SSCAM Carport 192.168.2.20 [5001] [https]
      # creates a new camera device CamCP

      define DS1 SSCAM SVS 192.168.2.20 [5000] [http]
      define DS1 SSCAM SVS 192.168.2.20 [5001] [https]
      # creares a new SVS device DS1
    

When a new Camera is defined, as a start the recordingtime of 15 seconds will be assigned to the device.
Using the rectime attribute you can adapt the recordingtime for every camera individually.
The value of "0" for rectime will lead to an endless recording which has to be stopped by a "set <name> off" command.
Due to a Log-Entry with a hint to that circumstance will be written.

If the rectime attribute would be deleted again, the default-value for recording-time (15s) become active.

With command "set <name> on [rectime]" a temporary recordingtime is determinded which would overwrite the dafault-value of recordingtime
and the attribute "rectime" (if it is set) uniquely.

In that case the command "set <name> on 0" leads also to an endless recording as well.

If you have specified a pre-recording time in SVS it will be considered too.

If the module recognizes the defined camera as a PTZ-device (Reading "DeviceType = PTZ"), then a control panel is created automatically in the detal view. This panel requires SVS >= 7.1. The properties and the behave of the panel can be affected by attributes "ptzPanel_.*".
Please see also command "set <name> createPTZcontrol" in this context.



Credentials


After a camera-device is defined, firstly it is needed to save the credentials. This will be done with command:

     set <name> credentials <username> <password>
    

The password length has a maximum of 20 characters.
The operator can, dependend on what functions are planned to execute, create an user in DSM respectively in Synology Surveillance Station as well.
If the user is member of admin-group, he has access to all module functions. Without this membership the user can only execute functions with lower need of rights.
Is 2-step verification activated in DSM, the setup to a session with Surveillance Station is necessary (session = SurveillanceStation attribute).

The required minimum rights to execute functions are listed in a table further down.
Alternatively to DSM-user a user created in SVS can be used. Also in that case a user of type "manager" has the right to execute all functions,
whereat the access to particular cameras can be restricted by the privilege profile (please see help function in SVS for details).
As best practice it is proposed to create an user in DSM as well as in SVS too:


• DSM-User as member of admin group: unrestricted test of all module functions -> session: DSM
• SVS-User as Manager or observer: adjusted privilege profile -> session: SurveillanceStation

Using the session attribute can be selected, if the session should be established to DSM or the SVS instead. Further informations about user management in SVS are available by execute "get <name> versionNotes 5".
If the session will be established to DSM, SVS Web-API methods are available as well as further API methods of other API's what possibly needed for processing.

After device definition the default is "login to DSM", that means credentials with admin rights can be used to test all camera-functions firstly.
After this the credentials can be switched to a SVS-session with a restricted privilege profile as needed on dependency what module functions are want to be executed.

The following list shows the minimum rights that the particular module function needs.



set ... on	session: ServeillanceStation - observer with enhanced privilege "manual recording"
set ... off	session: ServeillanceStation - observer with enhanced privilege "manual recording"
set ... snap	session: ServeillanceStation - observer
set ... delPreset	session: ServeillanceStation - observer
set ... disable	session: ServeillanceStation - manager with edit camera right
set ... enable	session: ServeillanceStation - manager with edit camera right
set ... expmode	session: ServeillanceStation - manager
set ... extevent	session: DSM - user as member of admin-group
set ... goPreset	session: ServeillanceStation - observer with privilege objective control of camera
set ... homeMode	ssession: ServeillanceStation - observer with privilege Home Mode switch (valid for SVS-device ! )
set ... motdetsc	session: ServeillanceStation - manager
set ... runPatrol	session: ServeillanceStation - observer with privilege objective control of camera
set ... goAbsPTZ	session: ServeillanceStation - observer with privilege objective control of camera
set ... move	session: ServeillanceStation - observer with privilege objective control of camera
set ... runView	session: ServeillanceStation - observer with privilege liveview of camera
set ... setHome	session: ServeillanceStation - observer
set ... setPreset	session: ServeillanceStation - observer
set ... snap	session: ServeillanceStation - observer
set ... snapGallery	session: ServeillanceStation - observer
set ... stopView	-
set ... credentials	-
get ... caminfo[all]	session: ServeillanceStation - observer
get ... eventlist	session: ServeillanceStation - observer
get ... listLog	session: ServeillanceStation - observer
get ... listPresets	session: ServeillanceStation - observer
get ... scanVirgin	session: ServeillanceStation - observer
get ... svsinfo	session: ServeillanceStation - observer
get ... snapfileinfo	session: ServeillanceStation - observer
get ... snapinfo	session: ServeillanceStation - observer
get ... stmUrlPath	session: ServeillanceStation - observer




HTTP-Timeout Settings


All functions of SSCam use HTTP-calls to SVS Web API.
You can set the attribute httptimeout > 0 to adjust the value as needed in your technical environment.




Set

The specified set-commands are available for CAM/SVS-devices or only valid for CAM-devices or rather for SVS-Devices. They can be selected in the drop-down-menu of the particular device.


• autocreateCams     (valid for SVS)

If a SVS device is defined, all in SVS integrated cameras are able to be created automatically in FHEM by this command. If the camera is already defined, it is overleaped. The new created camera devices are created in the same room as the used SVS device (default SSCam). Further helpful attributes are preset as well.


• createStreamDev [generic | hls | lastsnap | mjpeg | switched]     (valid for CAM)
  respectively
  createStreamDev [master]     (valid for SVS)
  
  A separate Streaming-Device (type SSCamSTRM) will be created. This device can be used as a discrete device in a dashboard for example. The current room of the parent camera device is assigned to the new device if it is set there.
  
  

  generic	- the streaming device playback a content determined by attribute genericStrmHtmlTag
  hls	- the streaming device playback a permanent HLS video stream
  lastsnap	- the streaming device playback the newest snapshot
  mjpeg	- the streaming device playback a permanent MJPEG video stream (Streamkey method)
  switched	- playback of different streaming types. Buttons for mode control are provided.
  master	- with the master device another defined streaming device can be adopted and its content displayed

  
  
  You can control the design with HTML tags in attribute htmlattr of the camera device or by specific attributes of the SSCamSTRM-device itself.
  
  
Streaming device "hls"

The Streaming-device of type "hls" uses the library hls.js to playback the video stream and is executable on most current browsers with MediaSource extensions (MSE). With hlsNetScript attribute can be specified, whether the local installed version of hls.js (./www/pgm2/sscam_hls.js) or the newest online library version from the hls.js project site should be used. This attribute has to be set centrally in a device of type "SVS" !
If this kind of streaming device is used, the hlsStrmObject attribute must be set in the parent camera device (see Internal PARENT).

Streaming device "switched hls"

This type of streaming device uses the HLS video stream native delivered by Synology Surveillance Station. If HLS (HTTP Live Streaming) is used in Streaming-Device of type "switched", then the camera has to be set to video format H.264 in the Synology Surveillance Station and the SVS-Version has to support the HLS format. Therefore the selection button of HLS is only provided by the Streaming-Device if the Reading "CamStreamFormat" contains "HLS".
HTTP Live Streaming is currently only available on Mac Safari or modern mobile iOS/Android devices.

Streaming device "generic"

A streaming device of type "generic" needs the complete definition of HTML-Tags by the attribute "genericStrmHtmlTag". These tags specify the content to playback.


Example:

attr <name> genericStrmHtmlTag <video $HTMLATTR controls autoplay>
                                 <source src='http://192.168.2.10:32000/$NAME.m3u8' type='application/x-mpegURL'>
                               </video>

attr <name> genericStrmHtmlTag <img $HTMLATTR
                                 src="http://192.168.2.10:32774"
                                 onClick="FW_okDialog('<img src=http://192.168.2.10:32774 $PWS>')"
                               >
      

The variables $HTMLATTR, $NAME and $PWS are placeholders and absorb the attribute "htmlattr" (if set), the SSCam-Devicename respectively the value of attribute "popupWindowSize" in streamin-device, which specify the windowsize of a popup window.


Streaming device "lastsnap"

This type of streaming device playback the last (newest) snapshot. As default the snapshot is retrieved in a reduced resolution. In order to use the original resolution, the attribute "snapGallerySize = Full" has to be set in the associated camera device (compare Internal PARENT). There also the attribute "pollcaminfoall" should be set to retrieve the newest snapshot regularly.

Streaming Device "master"

This type cannot play back streams itself. Switching the playback of the content of another defined Streaming Devices is done by the Set command adopt in the Master Streaming Device.



• createPTZcontrol     (valid for PTZ-CAM)

A separate PTZ control panel will be created (type SSCamSTRM). The current room of the parent camera device is assigned if it is set there (default "SSCam"). With the "ptzPanel_.*"-attributes or respectively the specific attributes of the SSCamSTRM-device the properties of the control panel can be affected.




• createReadingsGroup [<name of readingsGroup>]     (valid for CAM/SVS)

This command creates a readingsGroup device to display an overview of all defined SSCam devices. A name for the new readingsGroup device can be specified. Is no own name specified, the readingsGroup device will be created with name "RG.SSCam".



• createSnapGallery     (valid for CAM)

A snapshot gallery will be created as a separate device (type SSCamSTRM). The device will be provided in room "SSCam". With the "snapGallery..."-attributes respectively the specific attributes of the SSCamSTRM-device you are able to manipulate the properties of the new snapshot gallery device.

Note
The camera names in Synology SVS should not be very similar, otherwise the retrieval of snapshots could come to inaccuracies.


• credentials <username> <password>     (valid for CAM/SVS)

set username / password combination for access the Synology Surveillance Station. See Credentials
for further informations.


• delPreset <PresetName>     (valid for PTZ-CAM)

Deletes a preset "<PresetName>". In FHEMWEB a drop-down list with current available presets is provieded.



• disableCam     (gilt für CAM)
  Disables the camera in Synology Surveillance Station.



• enableCam     (gilt für CAM)
  Activate the camera in Synology Surveillance Station.



• expmode [day|night|auto]     (valid for CAM)
  With this command you are able to control the exposure mode and can set it to day, night or automatic mode. Thereby, for example, the behavior of camera LED's will be suitable controlled. The successful switch will be reported by the reading CamExposureMode (command "get ... caminfoall").
  
  Note:
  The successfully execution of this function depends on if SVS supports that functionality of the connected camera. Is the field for the Day/Night-mode shown greyed in SVS -> IP-camera -> optimization -> exposure mode, this function will be probably unsupported.



• extevent [ 1-10 ]     (valid for SVS)

This command triggers an external event (1-10) in SVS. The actions which will are used have to be defined in the actionrule editor of SVS at first. There are the events 1-10 possible. In the message application of SVS you may select Email, SMS or Mobil (DS-Cam) messages to release if an external event has been triggerd. Further informations can be found in the online help of the actionrule editor. The used user needs to be a member of the admin-group and DSM-session is needed too.



• goAbsPTZ [ X Y | up | down | left | right ]     (valid for CAM)

This command can be used to move a PTZ-camera to an arbitrary absolute X/Y-coordinate, or to absolute position using up/down/left/right. The option is only available for cameras which are having the Reading "CapPTZAbs=true". The property of a camera can be requested with "get <name> caminfoall" .

Example for a control to absolute X/Y-coordinates:


    set <name> goAbsPTZ 120 450
  

In this example the camera lense moves to position X=120 und Y=450.
The valuation is:

    X = 0 - 640      (0 - 319 moves lense left, 321 - 640 moves lense right, 320 don't move lense)
    Y = 0 - 480      (0 - 239 moves lense down, 241 - 480 moves lense up, 240 don't move lense)
  

The lense can be moved in smallest steps to very large steps into the desired direction. If necessary the procedure has to be repeated to bring the lense into the desired position.

If the motion should be done with the largest possible increment the following command can be used for simplification:

   set <name> goAbsPTZ up [down|left|right]
  

In this case the lense will be moved with largest possible increment into the given absolute position. Also in this case the procedure has to be repeated to bring the lense into the desired position if necessary.



• goPreset <Preset>     (valid for CAM)

Using this command you can move PTZ-cameras to a predefined position.
The Preset-positions have to be defined first of all in the Synology Surveillance Station. This usually happens in the PTZ-control of IP-camera setup in SVS. The Presets will be read ito FHEM with command "get <name> caminfoall" (happens automatically when FHEM restarts). The import process can be repeated regular by camera polling. A long polling interval is recommendable in this case because of the Presets are only will be changed if the user change it in the IP-camera setup itself.

Here it is an example of a PTZ-control depended on IR-motiondetector event:

    define CamFL.Preset.Wandschrank notify MelderTER:on.* set CamFL goPreset Wandschrank, ;; define CamFL.Preset.record at +00:00:10 set CamFL on 5 ;;;; define s3 at +*{3}00:00:05 set CamFL snap ;; define CamFL.Preset.back at +00:00:30 set CamFL goPreset Home
  

Operating Mode:
The IR-motiondetector registers a motion. Hereupon the camera "CamFL" moves to Preset-posion "Wandschrank". A recording with the length of 5 seconds starts 10 seconds later. Because of the prerecording time of the camera is set to 10 seconds (cf. Reading "CamPreRecTime"), the effectice recording starts when the camera move begins.
When the recording starts 3 snapshots with an interval of 5 seconds will be taken as well.
After a time of 30 seconds in position "Wandschrank" the camera moves back to postion "Home".

An extract of the log illustrates the process:

   2016.02.04 15:02:14 2: CamFL - Camera Flur_Vorderhaus has moved to position "Wandschrank"
   2016.02.04 15:02:24 2: CamFL - Camera Flur_Vorderhaus Recording with Recordtime 5s started
   2016.02.04 15:02:29 2: CamFL - Snapshot of Camera Flur_Vorderhaus has been done successfully
   2016.02.04 15:02:30 2: CamFL - Camera Flur_Vorderhaus Recording stopped
   2016.02.04 15:02:34 2: CamFL - Snapshot of Camera Flur_Vorderhaus has been done successfully
   2016.02.04 15:02:39 2: CamFL - Snapshot of Camera Flur_Vorderhaus has been done successfully
   2016.02.04 15:02:44 2: CamFL - Camera Flur_Vorderhaus has moved to position "Home"
  




• homeMode [on|off]     (valid for SVS)

Switch the HomeMode of the Surveillance Station on or off. Further informations about HomeMode you can find in the Synology Onlinehelp.


• motdetsc [camera|SVS|disable]     (valid for CAM)

The command "motdetsc" (stands for "motion detection source") switchover the motion detection to the desired mode. If motion detection will be done by camera / SVS without any parameters, the original camera motion detection settings are kept. The successful execution of that opreration one can retrace by the state in SVS -> IP-camera -> event detection -> motion.

For the motion detection further parameter can be specified. The available options for motion detection by SVS are "sensitivity" and "threshold".



set <name> motdetsc SVS [sensitivity] [threshold]	# command pattern
set <name> motdetsc SVS 91 30	# set the sensitivity to 91 and threshold to 30
set <name> motdetsc SVS 0 40	# keep the old value of sensitivity, set threshold to 40
set <name> motdetsc SVS 15	# set the sensitivity to 15, threshold keep unchanged



If the motion detection is used by camera, there are the options "sensitivity", "object size", "percentage for release" available.



set <name> motdetsc camera [sensitivity] [object size] [percentage]	# command pattern
set <name> motdetsc camera 89 0 20	# set the sensitivity to 89, percentage to 20
set <name> motdetsc camera 0 40 10	# keep old value for sensitivity, set threshold to 40, percentage to 10
set <name> motdetsc camera 30	# set the sensitivity to 30, other values keep unchanged



Please consider always the sequence of parameters. Unwanted options have to be set to "0" if further options which have to be changed are follow (see example above). The numerical values are between 1 - 99 (except special case "0").

The each available options are dependend of camera type respectively the supported functions by SVS. Only the options can be used they are available in SVS -> edit camera -> motion detection. Further informations please read in SVS online help.

With the command "get <name> caminfoall" the Reading "CamMotDetSc" also will be updated which documents the current setup of motion detection. Only the parameters and parameter values supported by SVS at present will be shown. The camera itself may offer further options to adjust.

Example:

   CamMotDetSc    SVS, sensitivity: 76, threshold: 55
  




• move [ right | up | down | left | dir_X ] [Sekunden]     (valid for CAM up to SVS version 7.1)
move [ right | upright | up | upleft | left | downleft | down | downright ] [Sekunden]     (valid for CAM and SVS Version 7.2 and above)

With this command a continuous move of a PTZ-camera will be started. In addition to the four basic directions up/down/left/right is it possible to use angular dimensions "dir_X". The grain size of graduation depends on properties of the camera and can be identified by the Reading "CapPTZDirections".

The radian measure of 360 degrees will be devided by the value of "CapPTZDirections" and describes the move drections starting with "0=right" counterclockwise. That means, if a camera Reading is "CapPTZDirections = 8" it starts with dir_0 = right, dir_2 = top, dir_4 = left, dir_6 = bottom and respectively dir_1, dir_3, dir_5 and dir_7 the appropriate directions between. The possible moving directions of cameras with "CapPTZDirections = 32" are correspondingly divided into smaller sections.

In opposite to the "set <name> goAbsPTZ"-command starts "set <name> move" a continuous move until a stop-command will be received. The stop-command will be generated after the optional assignable time of [seconds]. If that retention period wouldn't be set by the command, a time of 1 second will be set implicit.

Examples:


    set <name> move up 0.5      : moves PTZ 0,5 Sek. (plus processing time) to the top
    set <name> move dir_1 1.5   : moves PTZ 1,5 Sek. (plus processing time) to top-right
    set <name> move dir_20 0.7  : moves PTZ 1,5 Sek. (plus processing time) to left-bottom ("CapPTZDirections = 32)"
  



• off     (valid for CAM)

Stops the current recording.



• on [<rectime>]
  [recEmailTxt:"subject => <subject text>, body => <message text>"]
  [recTelegramTxt:"tbot => <TelegramBot device>, peers => [<peer1 peer2 ...>], subject => [<subject text>], option => [silent]"]
  [recChatTxt:"chatbot => <SSChatBot device>, peers => [<peer1 peer2 ...>], subject => [<subject text>]"]
      (valid for CAM)

A recording will be started. The default recording time is 15 seconds. It can be individually changed by the rectime attribute. The recording time can be overwritten on-time by "set <name> on <rectime>" for the current recording. The recording will be stopped after processing time "rectime"automatically.
A special case is start recording by "set <name> on 0" respectively the attribute value "rectime = 0". In this case an endless-recording will be started. One have to explicitely stop this recording with command "set <name> off".
Furthermore the recording behavior can be impacted with recextend attribute as explained as follows.

Attribute "recextend = 0" or not set (default):

• if, for example, a recording with rectimeme=22 is started, no other startcommand (for a recording) will be accepted until this started recording is finished. A hint will be logged in case of verboselevel = 3.

Attribute "recextend = 1" is set:

• a before started recording will be extend by the recording time "rectime" if a new start command is received. That means, the timer for the automatic stop-command will be renewed to "rectime" given bei the command, attribute or default value. This procedure will be repeated every time a new start command for recording is received. Therefore a running recording will be extended until no start command will be get.
• a before started endless-recording will be stopped after recordingtime 2rectime" if a new "set on"-command is received (new set of timer). If it is unwanted make sure you don't set the recextend attribute in case of endless-recordings.

The shipping of recording by Synology Chat can be activated permanently by setting attribute recChatTxt Of course, the SSChatBot device which is used for send data, must be defined and fully functional before.
If you want temporary overwrite the message text as set in attribute "recChatTxt", you can optionally specify the "recChatTxt:"-tag as shown above. If the attribute "recChatTxt" is not set, the shipping by Telegram is activated one-time. (the tag-syntax is equivalent to the "recChatTxt" attribute)

The Email shipping of recordings can be activated by setting recEmailTxt attribute. Before you have to prepare the Email shipping as described in section Setup Email shipping. (for further information execute "get <name> versionNotes 7")
Alternatively you can activate the Email-shipping one-time when you specify the "recEmailTxt:"-tag in the "on"-command. In this case the tag-text is used for creating the Email instead the text specified in "recEmailTxt"-attribute. (the tag syntax is identical to the "recEmailTxt" attribute)

The shipping of the last recording by Telegram can be activated permanently by setting recTelegramTxt attribute. Of course, the TelegramBot device which is used, must be defined and fully functional before.
If you want temporary overwrite the message text as set with attribute "recTelegramTxt", you can optionally specify the "recTelegramTxt:"-tag as shown above. If the attribute "recTelegramTxt" is not set, the shipping by Telegram is activated one-time. (the tag-syntax is equivalent to the "recTelegramTxt" attribute)

Examples:

set <name> on [rectime]
# starts a recording, stops automatically after [rectime]

set <name> on 0
# starts a permanent record which must be stopped with the "off"-command.

set <name> on recEmailTxt:"subject => New recording for $CAM created, body => The last recording of $CAM is atteched."
# starts a recording and send it after completion by Email.

set <name> on recTelegramTxt:"tbot => teleBot, peers => @xxxx , subject => Movement alarm by $CAM. The snapshot $FILE was created at $CTIME, option => silent"
# starts a recording and send it after completion by Telegram in silent-mode.

set <name> on recChatTxt:"chatbot => SynChatBot, peers => , subject => Movement alarm by $CAM. The snapshot $FILE was created at $CTIME."
# starts a recording and send it after completion by Synology Chat.




• optimizeParams [mirror:<value>] [flip:<value>] [rotate:<value>] [ntp:<value>]     (gilt für CAM)

Set one or several properties of the camera. The video can be mirrored (mirror), turned upside down (flip) or rotated (rotate). Specified properties must be supported by the camera type. With "ntp" you can set a time server the camera use for time synchronization.

<value> can be for:

• mirror, flip, rotate: true | false
• ntp: the name or the IP-address of time server


Examples:
set <name> optimizeParams mirror:true flip:true ntp:time.windows.com
# The video will be mirrored, turned upside down and the time server is set to "time.windows.com".
set <name> optimizeParams ntp:Surveillance%20Station
# The Surveillance Station is set as time server. (NTP-service has to be activated in DSM)
set <name> optimizeParams mirror:true flip:false rotate:true
# The video will be mirrored and rotated round 90 degrees.



• pirSensor [activate | deactivate]     (valid for CAM)

Activates / deactivates the infrared sensor of the camera (only posible if the camera has got a PIR sensor).



• runPatrol <Patrolname>     (valid for CAM)

This commans starts a predefined patrol (tour) of a PTZ-camera.
At first the patrol has to be predefined in the Synology Surveillance Station. It can be done in the PTZ-control of IP-Kamera Setup -> PTZ-control -> patrol. The patrol tours will be read with command "get <name> caminfoall" which is be executed automatically when FHEM restarts. The import process can be repeated regular by camera polling. A long polling interval is recommendable in this case because of the patrols are only will be changed if the user change it in the IP-camera setup itself. Further informations for creating patrols you can get in the online-help of Surveillance Station.



• runView [live_fw | live_link | live_open [<room>] | lastrec_fw | lastrec_fw_MJPEG | lastrec_fw_MPEG4/H.264 | lastrec_open [<room>] | lastsnap_fw]     (valid for CAM)



live_fw	- MJPEG-Livestream. Audio playback is provided if possible.
live_fw_hls	- HLS-Livestream (currently only Mac Safari Browser and mobile iOS/Android-Devices)
live_link	- Link of a MJPEG-Livestream
live_open [<room>]	- opens MJPEG-Livestream in separate Browser window
lastrec_fw	- playback last recording as iFrame object
lastrec_fw_MJPEG	- usable if last recording has format MJPEG
lastrec_fw_MPEG4/H.264	- usable if last recording has format MPEG4/H.264
lastrec_open [<room>]	- playback last recording in a separate Browser window
lastsnap_fw	- playback last snapshot



With "live_fw, live_link" a MJPEG-Livestream will be started, either as an embedded image or as a generated link.
The option "live_open" starts a new browser window with a MJPEG-Livestream. If the optional "<room>" is set, the window will only be started if the specified room is currently opened in a FHEMWEB-session.
If a HLS-Stream by "live_fw_hls" is requested, the camera has to be setup to video format H.264 (not MJPEG) in the Synology Surveillance Station and the SVS-Version has to support the HLS format. Therefore this possibility is only present if the Reading "CamStreamFormat" is set to "HLS".

Access to the last recording of a camera can be done using "lastrec_fw.*" respectively "lastrec_open". By "lastrec_fw" the recording will be opened in an iFrame. There are some control elements provided if available.
The "lastrec_open" command can be extended optionally by a room. In this case the new window opens only, if the room is the same as a FHEMWEB-session has currently opened.
The command "set <name> runView lastsnap_fw" shows the last snapshot of the camera embedded.
The Streaming-Device properties can be affected by HTML-tags in htmlattr attribute.

Examples:


    attr <name> htmlattr width="500" height="375"
    attr <name> htmlattr width="700",height="525",top="200",left="300"
  

The command "set <name> runView live_open" starts the stream immediately in a new browser window. A browser window will be initiated to open for every FHEMWEB-session which is active. If you want to change this behavior, you can use command "set <name> runView live_open <room>". In this case the new window opens only, if the room is the same as a FHEMWEB-session has currently opened.
The settings of livestreamprefix attribute overwrite the data for protocol, servername and port in Reading "LiveStreamUrl". By "livestreamprefix" the LivestreamURL (is shown if showStmInfoFull attribute is set) can be modified and used for distribution and external access to the Livestream.

Example:


    attr <name> livestreamprefix https://<Servername>:<Port>
  

The livestream can be stopped again by command "set <name> stopView". The "runView" function also switches Streaming-Devices of type "switched" into the appropriate mode.

Dependend of the content to playback, different control buttons are provided:



Start Recording	- starts an endless recording
Stop Recording	- stopps the recording
Take Snapshot	- take a snapshot
Switch off	- stops a running playback


Note for HLS (HTTP Live Streaming):
The video starts with a technology caused delay. Every stream will be segemented into some little video files (with a lenth of approximately 10 seconds) and is than delivered to the client. The video format of the camera has to be set to H.264 in the Synology Surveillance Station and not every camera type is a proper device for HLS-Streaming. At the time only the Mac Safari Browser and modern mobile iOS/Android-Devices are able to playback HLS-Streams.

Note for MJPEG:
The MJPEG stream is SVS internal transcoded from other codec and is usally only about 1 fps.



• setHome <PresetName>     (valid for PTZ-CAM)

Set the Home-preset to a predefined preset name "<PresetName>" or the current position of the camera.



• setPreset <PresetNumber> [<PresetName>] [<Speed>]     (valid for PTZ-CAM)

Sets a Preset with name "<PresetName>" to the current postion of the camera. The speed can be defined optionally (<Speed>). If no PresetName is specified, the PresetNummer is used as name. For this reason <PresetName> is defined as optional, but should usually be set.



• setZoom < .++ | + | stop | - | --. >     (valid for PTZ-CAM)

Provides controls for zoom functions if the camera supports this feature.



• snap [<number>] [<time difference>]
  [snapEmailTxt:"subject => <subject text>, body => <message text>"]
  [snapTelegramTxt:"tbot => <TelegramBot device>, peers => [<peer1 peer2 ...>], subject => [<subject text>], option => [silent]"]
  [snapChatTxt:"chatbot => <SSChatBot device>, peers => [<peer1 peer2 ...>], subject => [<subject text>]"]
      (valid for CAM)

One or multiple snapshots are triggered. The number of snapshots to trigger and the time difference (in seconds) between each snapshot can be optionally specified. Without any specification only one snapshot is triggered.
The ID and the filename of the last snapshot will be displayed in Reading "LastSnapId" respectively "LastSnapFilename".
To get data of the last 1-10 snapshots in various versions, the attribute snapReadingRotate can be used.

A snapshot shipping by Synology Chat can be permanently activated by setting attribute snapChatTxt. Of course, the SSChatBot device which is used must be defined and fully functional before.
If you want temporary overwrite the subject set in attribute "snapChatTxt", you can optionally specify the "snapChatTxt:"-tag as shown above. If the attribute "snapChatTxt" is not set, the shipping by SSChatBot is activated one-time (the tag-syntax is equivalent to the "snapChatTxt" attribute).
In either case the attribute videofolderMap has to be set before. It must contain an URL to the root directory of recordings and snapshots (e.g. http://server.me:8081/surveillance).

The snapshot Email shipping can be activated by setting attribute snapEmailTxt. Before you have to prepare the Email shipping as described in section Setup Email shipping. (for further information execute "get <name> versionNotes 7")
If you want temporary overwrite the message text set in attribute "snapEmailTxt", you can optionally specify the "snapEmailTxt:"-tag as shown above. If the attribute "snapEmailTxt" is not set, the Email shipping is activated one-time. (the tag-syntax is equivalent to the "snapEmailTxt" attribut)

A snapshot shipping by Telegram can be permanently activated by setting attribute snapTelegramTxt. Of course, the TelegramBot device which is used must be defined and fully functional before.
If you want temporary overwrite the message text set in attribute "snapTelegramTxt", you can optionally specify the "snapTelegramTxt:"-tag as shown above. If the attribute "snapTelegramTxt" is not set, the shipping by Telegram is activated one-time. (the tag-syntax is equivalent to the "snapTelegramTxt" attribut)

Examples:

    set <name> snap
    set <name> snap 4
    set <name> snap 3 3 snapEmailTxt:"subject => Movement alarm $CAM, body => A movement was recognised at Carport"
    set <name> snap 2 snapTelegramTxt:"tbot => teleBot, peers => , subject => Movement alarm by $CAM. The snapshot $FILE was created at $CTIME, option => silent"
    set <name> snap 2 snapChatTxt:"chatbot => SynChatBot , peers => Frodo Sam, subject => Movement alarm by $CAM. At $CTIME the snapshot  $FILE was created. Now it is: $TIME."
  




• snapCams [<number>] [<time difference>] [CAM:"<camera>, <camera>, ..."]     (valid for SVS)

One or multiple snapshots of denoted cameras are triggered. If no cameras are denoted, the snapshots are triggered in all of the defined cameras in FHEM. Optionally the number of snapshots to trigger (default: 1) and the time difference (in seconds) between each snapshot (default: 2) can be specified.
The ID and the filename of the last snapshot will be displayed in Reading "LastSnapId" respectively "LastSnapFilename" of the appropriate camera device.

The snapshot Email shipping can be activated by setting snapEmailTxt attribute in the SVS device AND in the camera devices whose snapshots should be shipped. Before you have to prepare the Email shipping as described in section Setup Email shipping. (for further information execute "get <name> versionNotes 7")
Only the message text set in attribute "snapEmailTxt" of the SVS device is used in the created Email. The settings of those attribute in the camera devices is ignored !!

Examples:

    set <name> snapCams 4
    set <name> snapCams 3 3 CAM:"CamHE1, CamCarport"
  




• snapGallery [1-10]     (valid for CAM)

The command is only available if the attribute "snapGalleryBoost=1" is set.
It creates an output of the last [x] snapshots as well as "get ... snapGallery". But differing from "get" with snapGalleryBoost=1 attribute no popup will be created. The snapshot gallery will be depicted as an browserpage instead. All further functions and attributes are appropriate the "get <name> snapGallery" command.
If you want create a snapgallery output by triggering, e.g. with an "at" or "notify", you should use the "get <name> snapGallery" command instead of "set".

Note
The camera names in Synology SVS should not be very similar, otherwise the retrieval of snapshots could come to inaccuracies.



• startTracking     (valid for CAM with tracking capability)

Starts object tracking of camera. The command is only available if surveillance station has recognised the object tracking capability of camera (Reading "CapPTZObjTracking").



• stopTracking     (valid for CAM with tracking capability)

Stops object tracking of camera. The command is only available if surveillance station has recognised the object tracking capability of camera (Reading "CapPTZObjTracking").




Get

With SSCam the properties of SVS and defined Cameras could be retrieved.
The specified get-commands are available for CAM/SVS-devices or only valid for CAM-devices or rather for SVS-Devices. They can be selected in the drop-down-menu of the particular device.


• apiInfo
  Retrieves the API information of the Synology Surveillance Station and open a popup window with its data.
  


• caminfoall     (valid for CAM/SVS)
caminfo     (valid for CAM)

Dependend of the type of camera (e.g. Fix- or PTZ-Camera) the available properties are retrieved and provided as Readings.
For example the Reading "Availability" will be set to "disconnected" if the camera would be disconnected from Synology Surveillance Station and can't be used for further processing like creating events.
"getcaminfo" retrieves a subset of "getcaminfoall".



• eventlist     (valid for CAM)

The Reading "CamEventNum" and "CamLastRecord" will be refreshed which containes the total number of in SVS registered camera events and the path/name of the last recording. This command will be implicit executed when "get <name> caminfoall" is running.
The videofolderMap attribute replaces the content of reading "VideoFolder". You can use it for example if you have mounted the videofolder of SVS under another name or path and want to access by your local pc.



• homeModeState     (valid for SVS)

HomeMode-state of the Surveillance Station will be retrieved.



• listLog [severity:<Loglevel>] [limit:<Number of lines>] [match:<Searchstring>]     (valid for SVS)
  Fetches the Surveillance Station Log from Synology server. Without any further options the whole log will be retrieved.
  You can specify all or any of the following options:
  
  
  • <Loglevel> - Information, Warning or Error. Only datasets having this severity are retrieved (default: all)
  • <Number of lines> - the specified number of lines (newest) of the log are retrieved (default: all)
  • <Searchstring> - only log entries containing the searchstring are retrieved (Note: no Regex possible, the searchstring will be given into the call to SVS)
  
  
Examples

get <name> listLog severity:Error limit:5
Reports the last 5 Log entries with severity "Error"
get <name> listLog severity:Information match:Carport
Reports all Log entries with severity "Information" and containing the string "Carport"
get <name> listLog severity:Warning
Reports all Log entries with severity "Warning"


If the polling of SVS is activated by setting the pollcaminfoall attribute, the Reading "LastLogEntry" will be created.
In the protocol-setup of the SVS you can adjust what data you want to log. For further informations please have a look at Synology Online-Help.



• listPresets     (valid for PTZ-CAM)

Get a popup with a lists of presets saved for the camera.



• saveLastSnap [<Pfad>]     (gilt für CAM)

The (last) snapshot currently specified in the reading "LastSnapId" is saved locally as a jpg file. Optionally, the path to save the file can be specified in the command (default: modpath in global Device).
The file is locally given the same name as contained in the reading "LastSnapFilename".
The resolution of the snapshot is determined by the attribute "snapGallerySize".


Example:

get <name> saveLastSnap /opt/fhem/log



• saveRecording [<path>]     (valid for CAM)

The current recording present in Reading "CamLastRec" is saved lcally as a MP4 file. Optionally you can specify the path for the file to save (default: modpath in global device).
The name of the saved local file is the same as displayed in Reading "CamLastRec".


Example:

get <name> saveRecording /opt/fhem/log



• scanVirgin     (valid for CAM/SVS)

This command is similar to get caminfoall, informations relating to SVS and the camera will be retrieved. In difference to caminfoall in either case a new session ID will be generated (do a new login), the camera ID will be new identified and all necessary API-parameters will be new investigated.



• snapGallery [1-10]     (valid for CAM)

A popup with the last [x] snapshots will be created. If the snapGalleryBoost attribute is set, the last snapshots (default 3) are requested by polling and they will be stored in the FHEM-servers main memory. This method is helpful to speed up the output especially in case of full size images, but it can be possible that NOT the newest snapshots are be shown if they have not be initialized by the SSCAm-module itself.
The function can also be triggered, e.g. by an "at" or "notify". In that case the snapshotgallery will be displayed on all connected FHEMWEB instances as a popup.

To control this function behavior there are further attributes:


• snapGalleryBoost
• snapGalleryColumns
• snapGalleryHtmlAttr
• snapGalleryNumber
• snapGallerySize

available.


Note:
Depended from quantity and resolution (quality) of the snapshot images adequate CPU and/or main memory ressources are needed. The camera names in Synology SVS should not be very similar, otherwise the retrieval of snapshots could come to inaccuracies.



• snapfileinfo     (valid for CAM)

The filename of the last snapshot will be retrieved. This command will be executed with "get <name> snap" automatically.



• snapinfo     (valid for CAM)

Informations about snapshots will be retrieved. Heplful if snapshots are not triggerd by SSCam, but by motion detection of the camera or surveillance station instead.



• stmUrlPath     (valid for CAM)

This command is to fetch the streamkey information and streamurl using that streamkey. The reading "StmKey" will be filled when this command will be executed and can be used to send it and run by your own application like a browser (see example). If the showStmInfoFull attribute is set, additional stream readings like "StmKeyUnicst", "StmKeymjpegHttp" will be shown and can be used to run the appropriate livestream without session id. Is the attribute "livestreamprefix" (usage: "http(s)://<hostname><port>) used, the servername / port will be replaced if necessary. The strUrlPath function will be included automatically if polling is used.

Example to create an http-call to a livestream using StmKey:


    http(s)://<hostname><port>/webapi/entry.cgi?api=SYNO.SurveillanceStation.VideoStreaming&version=1&method=Stream&format=mjpeg&cameraId=5&StmKey="31fd87279976d89bb98409728cced890"
  

cameraId (Internal CAMID) and StmKey has to be replaced by valid values.

Note:
If you use the stream-call from external and replace hostname / port with valid values and open your router ip ports, please make shure that no unauthorized person could get this sensible data !



• storedCredentials     (valid for CAM/SVS)

Shows the stored login credentials in a popup as plain text.



• svsinfo     (valid for CAM/SVS)

Determines common informations about the installed SVS-version and other properties.




• versionNotes [hints | rel | <key>]     (valid for CAM/SVS)

Shows realease informations and/or hints about the module. It contains only main release informations for module users.
If no options are specified, both release informations and hints will be shown. "rel" shows only release informations and "hints" shows only hints. By the <key>-specification only the hint with the specified number is shown.


Setup Email shipping


Snapshots and recordings can be sent by Email after creation. For this purpose the module contains its own Email client. Before you can use this function you have to install the Perl-module MIME::Lite. On debian systems it can be installed with command:


sudo apt-get install libmime-lite-perl

There are some attributes must be set or can be used optionally.
At first the Credentials for access the Email outgoing server must be set by command "set <name> smtpcredentials <user> <password>". The connection establishment to the server is initially done unencrypted and switches to an encrypted connection if SSL encryption is available. In that case the transmission of User/Password takes place encrypted too. If attribute "smtpSSLPort" is defined, the established connection to the Email server will be encrypted immediately. Attributes which are optional are marked:



snapEmailTxt	- Activates the Email shipping of snapshots. This attribute has the format: subject => <subject text>, body => <message text> The placeholder $CAM, $DATE and $TIME can be used. Optionally you can specify the "snapEmailTxt:"-tag when trigger a snapshot with the "snap"-command. In this case the Email shipping is activated one-time for the snapshot or the tag-text is used instead of the text defined in the "snapEmailTxt"-attribute.
recEmailTxt	- Activates the Email shipping of recordings. This attribute has the format: subject => <subject text>, body => <message text> The placeholder $CAM, $DATE and $TIME can be used. Optionally you can specify the "recEmailTxt:"-tag when start recording with the "on"-command. In this case the Email shipping is activated one-time for the started recording or the tag-text is used instead of the text defined in the "recEmailTxt"-attribute.
smtpHost	- Hostname of outgoing Email server (e.g. securesmtp.t-online.de)
smtpFrom	- Return address (<name>@<domain>)
smtpTo	- Receiving address(es) (<name>@<domain>)
smtpPort	- (optional) Port of outgoing Email server (default: 25)
smtpCc	- (optional) carbon-copy receiving address(es) (<name>@<domain>)
smtpNoUseSSL	- (optional) "1" if no SSL encryption should be used for Email shipping (default: 0)
smtpSSLPort	- (optional) Port for SSL encrypted connection (default: 465)
smtpDebug	- (optional) switch on the debugging of SMTP connection


Description of the placeholders:



$CAM	- Device alias respectively the name of the camera in SVS if the device alias isn't set
$DATE	- current date
$TIME	- current time
$FILE	- name of the snapshot file
$CTIME	- creation time of the snapshot





Polling of Camera/SVS-Properties


Retrieval of Camera-Properties can be done automatically if the attribute "pollcaminfoall" will be set to a value > 10.
As default that attribute "pollcaminfoall" isn't be set and the automatic polling isn't be active.
The value of that attribute determines the interval of property-retrieval in seconds. If that attribute isn't be set or < 10 the automatic polling won't be started
respectively stopped when the value was set to > 10 before.

The attribute "pollcaminfoall" is monitored by a watchdog-timer. Changes of the attribute-value will be checked every 90 seconds and transact corresponding.
Changes of the pollingstate and pollinginterval will be reported in FHEM-Logfile. The reporting can be switched off by setting the attribute "pollnologging=1".
Thereby the needless growing of the logfile can be avoided. But if verbose level is set to 4 or above even though the attribute "pollnologging" is set as well, the polling
will be actived due to analysis purposes.

If FHEM will be restarted, the first data retrieval will be done within 60 seconds after start.

The state of automatic polling will be displayed by reading "PollState":


• PollState = Active - automatic polling will be executed with interval correspondig value of attribute "pollcaminfoall"
• PollState = Inactive - automatic polling won't be executed

The readings are described here.

Notes:

If polling is used, the interval should be adjusted only as short as needed due to the detected camera values are predominantly static.
A feasible guide value for attribute "pollcaminfoall" could be between 600 - 1800 (s).
Per polling call and camera approximately 10 - 20 Http-calls will are stepped against Surveillance Station.
Because of that if HTTP-Timeout (pls. refer attribute httptimeout) is set to 4 seconds, the theoretical processing time couldn't be higher than 80 seconds.
Considering a safety margin, in that example you shouldn't set the polling interval lower than 160 seconds.

If several Cameras are defined in SSCam, attribute "pollcaminfoall" of every Cameras shouldn't be set exactly to the same value to avoid processing bottlenecks
and thereby caused potential source of errors during request Synology Surveillance Station.
A marginal difference between the polling intervals of the defined cameras, e.g. 1 second, can already be faced as sufficient value.


Internals


The meaning of used Internals is depicted in following list:


• CAMID - the ID of camera defined in SVS, the value will be retrieved automatically on the basis of SVS-cameraname
• CAMNAME - the name of the camera in SVS
• COMPATIBILITY - information up to which SVS-version the module version is currently released/tested (see also Reading "compstate")
• CREDENTIALS - the value is "Set" if Credentials are set
• NAME - the cameraname in FHEM
• MODEL - distinction between camera device (CAM) and Surveillance Station device (SVS)
• OPMODE - the last executed operation of the module
• SERVERADDR - IP-Address of SVS Host
• SERVERPORT - SVS-Port



Attributes


• cacheServerParam
  Specification of connection parameters to a central data cache.
  
  

  redis

  : if network connection is used: <IP-address>:<port> / if Unix-Socket is used: <unix>:</path/to/socket>

  
  


• cacheType
  Defines the used Cache for storage of snapshots, recordings und other mass data. (Default: internal).
  Maybe further perl modules have to be installed, e.g. with help of the FHEM Installer.
  The data are saved in "Namespaces" to permit the usage of central Caches (e.g. redis).
  The cahe types "file" and "redis" are convenient if the data shouldn't be hold in the RAM of the FHEM-Server. For the usage of Redis at first a the Redis Key-Value Store has to be provide, e.g. in a Docker image on the Synology Diskstation (redis).
  
  

  internal	: use the module internal storage (Default)
  mem	: very fast Cache, copy data into the RAM
  rawmem	: fastest Cache for complex data, stores references into the RAM
  file	: create and use a file structure in subdirectory "FhemUtils"
  redis	: use a external Redis Key-Value Store over TCP/IP or Unix-Socket. Please see also attribute "cacheServerParam".

  
  


• customSVSversion
  A logical change to the specified SVS version is performed. The attribute could be useful to temporarily eliminate incompatibilities that may occur when updating/upgrading Synology Surveillance Station. Incompatibilities should be reported to the maintainer in a timely manner.


• debugactivetoken
  If set, the state of active token will be logged - only for debugging, don't use it in normal operation !


• debugCachetime
  Shows the consumed time of cache operations.


• disable
  deactivates the device definition


• genericStrmHtmlTag
  This attribute contains HTML-Tags for video-specification in a Streaming-Device of type "generic". (see also "set <name> createStreamDev generic")
  
  
  Examples:

  attr <name> genericStrmHtmlTag <video $HTMLATTR controls autoplay>
                                   <source src='http://192.168.2.10:32000/$NAME.m3u8' type='application/x-mpegURL'>
                                 </video>
  
  attr <name> genericStrmHtmlTag <img $HTMLATTR
                                   src="http://192.168.2.10:32774"
                                   onClick="FW_okDialog('<img src=http://192.168.2.10:32774 $PWS>')"
                                 >
        

  The variables $HTMLATTR, $NAME and $PWS are placeholders and absorb the attribute "htmlattr" (if set), the SSCam-Devicename respectively the value of attribute "popupWindowSize" in streaming-device, which specify the windowsize of a popup window.
  
  
  
• hlsNetScript     (settable in device model "SVS")
  If set, the latest hls.js library version from the project site is used (internet connection is needed).
  In default the local installed library version (./www/pgm2/sscam_hls.js) is uses for playback in all streaming devices of type "hls" (please see also "set <name> createStreamDev hls"). This attribute has to be set in a device model "SVS" and applies to all streaming devices !


• hlsStrmObject
  If a streaming device was defined by "set <name> createStreamDev hls", this attribute has to be set and must contain the link to the video object to play back.
  The attribute must specify a HTTP Live Streaming object with the extension ".m3u8".
  The variable $NAME can be used as a placeholder and will be replaced by the camera device name.
  
  
  Examples:
  attr <name> hlsStrmObject https://bitdash-a.akamaihd.net/content/MI201109210084_1/m3u8s/f08e80da-bf1d-4e3d-8899-f0f6155f6efa.m3u8
  attr <name> hlsStrmObject https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8
  # Sample video streams used for testing the streaming device function (internet connection is needed)
  
  attr <name> hlsStrmObject http://192.168.2.10:32000/CamHE1.m3u8
  # playback a HLS video stream of a camera witch is delivered by e.g. a ffmpeg conversion process
  
  attr <name> hlsStrmObject http://192.168.2.10:32000/$NAME.m3u8
  # Same as example above, but use the replacement with variable $NAME for "CamHE1"
  
  
• httptimeout
  Timeout-Value of HTTP-Calls to Synology Surveillance Station.
  (default: 20 seconds)


• htmlattr
  additional specifications to inline oictures to manipulate the behavior of stream, e.g. size of the image.


Example:
attr <name> htmlattr width="500" height="325" top="200" left="300"


• livestreamprefix
  Overwrites the specifications of protocol, servername and port for further use in livestream address and StmKey.*-readings , e.g. as a link for external use.
  It can be specified of two ways as follows:
  
  

  DEF	: the protocol, servername and port as specified in device definition is used
  http(s)://<servername>:<port>	: your own address specification is used

  
  Servername can be the name or the IP-address of your Synology Surveillance Station.


• loginRetries
  set the amount of login-repetitions in case of failure (default = 3)


• noQuotesForSID
  This attribute delete the quotes for SID and for StmKeys. The attribute may be helpful in some cases to avoid errormessages "402 - permission denied" or "105 - Insufficient user privilege" and makes login possible.
  (default: 0)


• pollcaminfoall
  Interval of the automatic property query (polling) of the device (<= 10: no polling, > 10: polling with interval)
  
  Note: It is strongly recommended to keep the polling to get the full functionality of the module.
  


• pollnologging
  "0" resp. not set = Logging device polling active (default), "1" = Logging device polling inactive


• ptzNoCapPrePat
  Some PTZ cameras cannot store presets and patrols despite their PTZ capabilities. To avoid errors and corresponding log messages, the attribute ptzNoCapPrePat can be set in these cases. The system will be notified of a missing preset / patrol capability.


• ptzPanel_Home
  In the PTZ-control panel the Home-Icon (in attribute "ptzPanel_row02") is automatically assigned to the value of Reading "PresetHome". With "ptzPanel_Home" you can change the assignment to another preset from the available Preset list.


• ptzPanel_iconPath
  Path for icons used in PTZ-control panel, default is "www/images/sscam". The attribute value will be used for all icon-files except *.svg.
  For further information execute "get <name> versionNotes 2,6".


• ptzPanel_iconPrefix
  Prefix for icons used in PTZ-control panel, default is "black_btn_". The attribute value will be used for all icon-files except *.svg.
  If the used icon-files begin with e.g. "black_btn_" ("black_btn_CAMDOWN.png"), the icon needs to be defined in attributes "ptzPanel_row[00-09]" just with the subsequent part of name, e.g. "CAMDOWN.png".


• ptzPanel_row[00-09] <command>:<icon>,<command>:<icon>,...
  For PTZ-cameras the attributes "ptzPanel_row00" to "ptzPanel_row04" are created automatically for usage by the PTZ-control panel.
  The attributes contain a comma spareated list of command:icon-combinations (buttons) each panel line. One panel line can contain a random number of buttons. The attributes "ptzPanel_row00" to "ptzPanel_row04" can't be deleted because of they are created automatically again in that case. The user can change or complement the attribute values. These changes are conserved.
  If needed the assignment for Home-button in "ptzPanel_row02" can be changed by attribute "ptzPanel_Home".
  The icons are searched in path "ptzPanel_iconPath". The value of "ptzPanel_iconPrefix" is prepend to the icon filename. Own extensions of the PTZ-control panel can be done using the attributes "ptzPanel_row05" to "ptzPanel_row09". For creation of own icons a template is provided in the SVN. Further information can be get by "get <name> versionNotes 2".
  
  Note:
  For an empty field please use ":CAMBLANK.png" respectively ":CAMBLANK.png,:CAMBLANK.png,:CAMBLANK.png,..." for an empty line.
  
  
  Example:
  attr <name> ptzPanel_row00 move upleft:CAMUPLEFTFAST.png,:CAMBLANK.png,move up:CAMUPFAST.png,:CAMBLANK.png,move upright:CAMUPRIGHTFAST.png
  # The command "move upleft" is transmitted to the camera by pressing the button(icon) "CAMUPLEFTFAST.png".
  
  
  


• ptzPanel_use
  Switch the usage of a PTZ-control panel in detail view respectively a created StreamDevice off or on (default: on).
  The PTZ panel use its own icons. Thereby the system find the icons, in FHEMWEB device the attribute "iconPath" has to be completed by "sscam" (e.g. "attr WEB iconPath default:fhemSVG:openautomation:sscam").


• recChatTxt chatbot => <SSChatBot device>, peers => [<peer1 peer2 ...>], subject => [<subject text>]
  Activates the permanent shipping of recordings by Synology Chat after its creation.
  Before activating the attribute videofolderMap has to be set. It must contain an URL to the root directory of your SVS recordings and snapshots ( e.g. http://server.me:8081/surveillance ).
  The attribute recChatTxt has to be defined in the form as described. With key "chatbot" the SSChatBot device is specified, which is used for sending the data. Of course, the SSChatBot device must be available and work well.
  The setting of "peers" is optional, but the keys must be (empty) specified. If "peer" is empty, the defaultPeer of the SSChatBot device is used.
  
  You can use the following placeholders within "subject".
  
  

  $CAM (#CAM)	- Device alias respectively the name of the camera in SVS if the device alias isn't set
  $DATE (#DATE)	- current date
  $TIME (#TIME)	- current time
  $FILE (#FILE)	- Name of recording file
  $CTIME (#CTIME)	- recording creation time

  
  Examples:
  attr <device> recChatTxt chatbot => teleBot, peers => , subject => Motion alarm ($FILE)
  attr <device> recChatTxt chatbot => teleBot, peers => Frodo Sam Gollum, subject => Motion alarm
  attr <device> recChatTxt chatbot => teleBot, peers => , subject => Motion alarm
  attr <device> recChatTxt chatbot => teleBot, peers => , subject => Motion alarm from $CAM. At $CTIME the recording $FILE was created. Now it is $TIME.
  
  


• recEmailTxt subject => <subject text>, body => <message text>
  Activates the Email shipping of recordings after whose creation.
  The attribute must be defined in the specified form.
  The following placeholders can be used in the subject or body.
  
  

  $CAM (#CAM)	- Device alias respectively the name of the camera in SVS if the device alias isn't set
  $DATE (#DATE)	- current date
  $TIME (#TIME)	- aktuelle time
  $FILE (#FILE)	- Filename of the (last) recording (only usable in body)
  $CTIME (#CTIME)	- Creation time of the (last) recording (only usable in body)

  
  
  Example:
  recEmailTxt subject => New recording $CAM, body => A new recording of $CAM is created and atteched.
  
  
• recTelegramTxt tbot => <TelegramBot-Device>, peers => [<peer1 peer2 ...>], subject => [<Text>], option => [silent]
  Enables permanent sending of recordings after their creation via TelegramBot.
  The attribute must be defined in the specified form. For optional specifications, the key must be specified >empty<.
  
  Meaning of the keys:
  
  

  tbot	Name of the TelegramBot-Device
  peers	List of recipients separated by spaces (optional).
  	It can be specified r:<Reading> to read the recipients from the <Reading>.
  	If peers is not specified, the default peer of the TelegramBot device is used.
  subject	the text to be transmitted (optional)
  option	possible TelegramBot sending options described below (optional)
  	silent : the signaling at the receiver is suppressed

  
  You can use the following placeholders within "subject".
  
  

  $CAM (#CAM)	- Device alias respectively the name of the camera in SVS if the device alias isn't set
  $DATE (#DATE)	- current date
  $TIME (#TIME)	- current time
  $FILE (#FILE)	- Name of recording file
  $CTIME (#CTIME)	- recording creation time

  
  Examples:
  attr <device> recTelegramTxt tbot => teleBot, peers => , subject => Motion alarm ($FILE)
  attr <device> recTelegramTxt tbot => teleBot, peers => @nabuko @foo @bar, subject =>
  attr <device> recTelegramTxt tbot => teleBot, peers => #nabugroup, subject =>
  attr <device> recTelegramTxt tbot => teleBot, peers => -123456, subject =>
  attr <device> recTelegramTxt tbot => teleBot, peers => , subject =>
  attr <device> recTelegramTxt tbot => teleBot, peers => r:peerTelegram, subject =>
  attr <device> recTelegramTxt tbot => teleBot, peers => , subject => without signalization, option => silent
  attr <device> recTelegramTxt tbot => teleBot, peers => , subject => Motion alarm from $CAM. At $CTIME the recording $FILE was created. Now it is $TIME.
  
  


• rectime
  determines the recordtime when a recording starts. If rectime = 0 an endless recording will be started. If it isn't defined, the default recordtime of 15s is activated


• recextend
  "rectime" of a started recording will be set new. Thereby the recording time of the running recording will be extended


• session
  selection of login-Session. Not set or set to "DSM" -> session will be established to DSM (Sdefault). "SurveillanceStation" -> session will be established to SVS.
  For establish a sesion with Surveillance Station you have to create a user with suitable privilege profile in SVS. If you need more infomations please execute "get <name> versionNotes 5".


• smtpHost <Hostname>
  The name or IP-address of outgoing email server (e.g. securesmtp.t-online.de).


• smtpCc <name>@<domain>[, <name>@<domain>][, <name>@<domain>]...
  Optional you can enter a carbon-copy receiving address. Several receiving addresses are separated by ",".


• smtpDebug
  Switch the debugging mode for SMTP connection on (if Email shipping is used).


• smtpFrom <name>@<domain>
  Return address if Email shipping is used.


• smtpPort <Port>
  Optional setting of default SMTP port of outgoing email server (default: 25).


• smtpSSLPort <Port>
  Optional setting of SSL port of outgoing email server (default: 465). If set, the established connection to the Email server will be encrypted immediately.


• smtpTo <name>@<domain>[, <name>@<domain>][, <name>@<domain>]...
  Receiving address for emal shipping. Several receiving addresses are separated by ",".


• smtpNoUseSSL
  If no Email SSL encryption should be used, set this attribute to "1" (default: 0).


• snapChatTxt chatbot => <SSChatBot-Device>, peers => [<peer1 peer2 ...>], subject => [<subject text>]
  Activates the permanent shipping of snapshots by Synology Chat after their creation. If several snapshots were triggert, they will be sequentially delivered.
  Before activating the attribute videofolderMap has to be set. It must contain an URL to the root directory of your SVS recordings and snapshots ( e.g. http://server.me:8081/surveillance ).
  The attribute snapChatTxt has to be defined in the form as described. With key "chatbot" the SSChatBot device is specified, which is used for sending the data. Of course, the SSChatBot device must be available and work well.
  The key "peers" contains valid names of Synology Chat Users who should receive the message.
  The setting of "peers" is optional, but the keys must (empty) specified. If "peer" is empty, the defaultPeer of the SSChatBot device is used.
  
  You can use the following placeholders within "subject".
  
  

  $CAM (#CAM)	- Device alias respectively the name of the camera in SVS if the device alias isn't set
  $DATE (#DATE)	- current date
  $TIME (#TIME)	- current time
  $FILE (#FILE)	- Name of snapshot file
  $CTIME (#CTIME)	- creation time of the snapshot

  
  Examples:
  attr <device> snapChatTxt chatbot => SynChatBot, peers => , subject => Motion alarm ($FILE)
  attr <device> snapChatTxt chatbot => SynChatBot, peers => Aragorn Frodo Sam, subject => A snapshot has been done
  attr <device> snapChatTxt chatbot => SynChatBot, peers => , subject => Caution !
  attr <device> snapChatTxt chatbot => SynChatBot, peers => Frodo, subject => Motion alarm from $CAM. At $CTIME the snapshot $FILE was created
  
  


• snapEmailTxt subject => <subject text>, body => <message text>
  Activates the Email shipping of snapshots after whose creation.
  The attribute must be defined in the specified form.
  The following placeholders can be used in the subject or body.
  
  

  $CAM (#CAM)	- Device alias respectively the name of the camera in SVS if the device alias isn't set
  $DATE (#DATE)	- current date
  $TIME (#TIME)	- current time
  $FILE (#FILE)	- Filename of the (last) snapshot (only usable in body)
  $CTIME (#CTIME)	- Creation time of the (last) snapshot (only usable in body)

  
  
  Example:
  snapEmailTxt subject => Motion alarm $CAM, body => A motion was recognized at $CAM.
  
  
  
• snapTelegramTxt tbot => <TelegramBot device>, peers => [<peer1 peer2 ...>], subject => [<subject text>], option => [silent]
  Enables permanent sending of snapshots after their creation via TelegramBot. If several snapshots were triggered, they are sent sequentially.
  The attribute must be defined in the specified form. For optional specifications, the key must be specified >empty<.
  
  Meaning of the keys:
  
  

  tbot	Name of the TelegramBot-Device
  peers	List of recipients separated by spaces (optional).
  	It can be specified r:<Reading> to read the recipients from the <Reading>.
  	If peers is not specified, the default peer of the TelegramBot device is used.
  subject	the text to be transmitted (optional)
  option	possible TelegramBot sending options described below (optional)
  	silent : the signaling at the receiver is suppressed

  
  You can use the following placeholders within "subject".
  
  

  $CAM (#CAM)	- Device alias respectively the name of the camera in SVS if the device alias isn't set
  $DATE (#DATE)	- current date
  $TIME (#TIME)	- current time
  $FILE (#FILE)	- Name of snapshot file
  $CTIME (#CTIME)	- creation time of the snapshot

  
  Examples:
  attr <device> snapTelegramTxt tbot => teleBot, peers => , subject => Motion alarm ($FILE)
  attr <device> snapTelegramTxt tbot => teleBot, peers => @nabuko @foo @bar, subject =>
  attr <device> snapTelegramTxt tbot => teleBot, peers => #nabugroup, subject =>
  attr <device> snapTelegramTxt tbot => teleBot, peers => -123456, subject =>
  attr <device> snapTelegramTxt tbot => teleBot, peers => , subject =>
  attr <device> snapTelegramTxt tbot => teleBot, peers => r:peerTelegram, subject =>
  attr <device> snapTelegramTxt tbot => teleBot, peers => , subject => without signalization, option => silent
  attr <device> snapTelegramTxt tbot => teleBot, peers => , subject => Motion alarm from $CAM. At $CTIME the snapshot $FILE was created
  
  


• snapGalleryBoost
  If set, the last snapshots (default 3) will be retrieved by Polling, will be stored in the FHEM-servers main memory and can be displayed by the "set/get ... snapGallery" command.
  This mode is helpful if many or full size images shall be displayed. If the attribute is set, you can't specify arguments in addition to the "set/get ... snapGallery" command. (see also attribut "snapGalleryNumber").
  
  (default: 0)


• snapGalleryColumns
  The number of snapshots which shall appear in one row of the gallery popup (default 3).


• snapGalleryHtmlAttr
  the image parameter can be controlled by this attribute.
  If the attribute isn't set, the value of attribute "htmlattr" will be used.
  If "htmlattr" is also not set, default parameters are used instead (width="500" height="325").
  
  
  Example:
  attr <name> snapGalleryHtmlAttr width="325" height="225"
  
  
• snapGalleryNumber
  The number of snapshots to retrieve (default 3).


• snapGallerySize
  By this attribute the quality of the snapshot images can be controlled (default "Icon").
  If mode "Full" is set, the images are retrieved with their original available resolution. That requires more ressources and may slow down the display. By setting attribute "snapGalleryBoost=1" the display may accelerated, because in that case the images will be retrieved by continuous polling and need only bring to display.


• snapReadingRotate 0...10
  Activates the version control of snapshot readings (default: 0). A consecutive number of readings "LastSnapFilename", "LastSnapId" and "LastSnapTime" until to the specified value of snapReadingRotate will be created and contain the data of the last X snapshots.


• showStmInfoFull
  additional stream informations like LiveStreamUrl, StmKeyUnicst, StmKeymjpegHttp will be created


• showPassInLog
  if set the used password will be shown in logfile with verbose 4. (default = 0)


• videofolderMap
  Replaces the content of reading "VideoFolder". Use it if e.g. folders are mountet with different names than original in SVS or providing an URL for acces the snapshots / recordings by a web server.


• verbose


Different Verbose-Level are supported.
Those are in detail:

0	- Start/Stop-Event will be logged
1	- Error messages will be logged
2	- messages according to important events were logged
3	- sended commands will be logged
4	- sended and received informations will be logged
5	- all outputs will be logged for error-analyses. Caution: a lot of data could be written into logfile !



• readingFnAttributes


Readings

Using the polling mechanism or retrieval by "get"-call readings are provieded, The meaning of the readings are listed in subsequent table:
The transfered Readings can be deversified dependend on the type of camera.



CamAudioType	- Indicating audio type
Availability	- Availability of Camera (disabled, enabled, disconnected, other)
CamEventNum	- delivers the total number of in SVS registered events of the camera
CamExposureControl	- indicating type of exposure control
CamExposureMode	- current exposure mode (Day, Night, Auto, Schedule, Unknown)
CamForceEnableMulticast	- Is the camera forced to enable multicast.
CamIP	- IP-Address of Camera
CamLastRec	- Path / name of last recording
CamLastRecId	- the ID of last recording
CamLastRecTime	- date / starttime - endtime of the last recording (format depends of global attribute "language")
CamLiveFps	- Frames per second of Live-Stream
CamLiveMode	- Source of Live-View (DS, Camera)
camLiveQuality	- Live-Stream quality set in SVS
camLiveResolution	- Live-Stream resolution set in SVS
camLiveStreamNo	- used Stream-number for Live-Stream
CamModel	- Model of camera
CamMotDetSc	- state of motion detection source (disabled, by camera, by SVS) and their parameter
CamNTPServer	- set time server
CamPort	- IP-Port of Camera
CamPreRecTime	- Duration of Pre-Recording (in seconds) adjusted in SVS
CamPtSpeed	- adjusted value of Pan/Tilt-activities (setup in SVS)
CamRecShare	- shared folder on disk station for recordings
CamRecVolume	- Volume on disk station for recordings
CamStreamFormat	- the current format of video streaming
CamVideoType	- Indicating video type
CamVendor	- Identifier of camera producer
CamVideoFlip	- Is the video flip
CamVideoMirror	- Is the video mirror
CamVideoRotate	- Is the video rotate
CapAudioOut	- Capability to Audio Out over Surveillance Station (false/true)
CapChangeSpeed	- Capability to various motion speed
CapPIR	- has the camera a PIR sensor feature
CapPTZAbs	- Capability to perform absolute PTZ action
CapPTZAutoFocus	- Capability to perform auto focus action
CapPTZDirections	- the PTZ directions that camera support
CapPTZFocus	- mode of support for focus action
CapPTZHome	- Capability to perform home action
CapPTZIris	- mode of support for iris action
CapPTZObjTracking	- Capability to perform objekt-tracking
CapPTZPan	- Capability to perform pan action
CapPTZPresetNumber	- The maximum number of preset supported by the model. 0 stands for preset incapability
CapPTZTilt	- mode of support for tilt action
CapPTZZoom	- Capability to perform zoom action
DeviceType	- device type (Camera, Video_Server, PTZ, Fisheye)
Error	- message text of last error
Errorcode	- error code of last error
HomeModeState	- HomeMode-state (SVS-version 8.1.0 and above)
LastLogEntry	- the neweset entry of Surveillance Station Log (only if SVS-device and if attribute pollcaminfoall is set)
LastSnapFilename[x]	- the filename of the last snapshot or snapshots
LastSnapId[x]	- the ID of the last snapshot or snapshots
LastSnapTime[x]	- timestamp of the last snapshot or snapshots (format depends of global attribute "language")
LastUpdateTime	- date / time the last update of readings by "caminfoall" (format depends of global attribute "language")
LiveStreamUrl	- the livestream URL if stream is started (is shown if showStmInfoFull attribute is set)
Patrols	- in Synology Surveillance Station predefined patrols (at PTZ-Cameras)
PollState	- shows the state of automatic polling
PresetHome	- Name of Home-position (at PTZ-Cameras)
Presets	- in Synology Surveillance Station predefined Presets (at PTZ-Cameras)
Record	- if recording is running = Start, if no recording is running = Stop
StmKey	- current streamkey. it can be used to open livestreams without session id
StmKeyUnicst	- Uni-cast stream path of the camera. (showStmInfoFull has to be set)
StmKeymjpegHttp	- Mjpeg stream path(over http) of the camera (showStmInfoFull has to be set)
SVScustomPortHttp	- Customized port of Surveillance Station (HTTP) (to get with "svsinfo")
SVScustomPortHttps	- Customized port of Surveillance Station (HTTPS) (to get with "svsinfo")
SVSlicenseNumber	- The total number of installed licenses (to get with "svsinfo")
SVSuserPriv	- The effective rights of the user used for log in (to get with "svsinfo")
SVSversion	- package version of the installed Surveillance Station (to get with "svsinfo")
UsedSpaceMB	- used disk space of recordings by Camera
VideoFolder	- Path to the recorded video
compstate	- state of compatibility (compares current/simulated SVS-version with Internal COMPATIBILITY)

SSCamSTRM

[EN DE]

The module SSCamSTRM is a special device module synchronized to the SSCam module. It is used for definition of Streaming-Devices.
Dependend of the Streaming-Device state, different buttons are provided to start actions:



Switch off	- stops a running playback
Refresh	- refresh a view (no page reload)
Restart	- restart a running content (e.g. a HLS-Stream)
MJPEG	- starts a MJPEG Livestream
HLS	- starts HLS (HTTP Live Stream)
Last Record	- playback the last recording as iFrame
Last Rec H.264	- playback the last recording if available as H.264
Last Rec MJPEG	- playback the last recording if available as MJPEG
Last SNAP	- show the last snapshot
Start Recording	- starts an endless recording
Stop Recording	- stopps the recording
Take Snapshot	- take a snapshot


Integration into FHEM TabletUI:

There is a widget provided for integration of SSCam-Streaming devices into FTUI. For further information please be informed by the (german) FHEM Wiki article:
FTUI Widget für SSCam Streaming Devices (SSCamSTRM).

Define


A SSCam Streaming-device is defined by the SSCam command:


set <name> createStreamDev <Device Typ>


Please refer to SSCam "createStreamDev" command.


Set
• adopt <Streaming device>     (only valid if MODEL = master)
  A Streaming Device of type master adopts the content of another defined Streaming Device.


• adoptForTimer <Streaming Device>     (only valid if MODEL = master)
  A Streaming Device of type master adopts the content of another defined Streaming Device for a certain time.
  The time is set with the command set <name> adoptTime.
  (default: 10 seconds)


• adoptTime <seconds>     (only valid if MODEL = master)
  Setting of the switching time when temporarily taking over the content of another Streaming Device. After the time has expired, playback is switched back to the previously set Streaming Device.
  If no argument or "0" is given, the time specification is deleted and the default (10 seconds) is used.


• snap [<number>] [<time difference>]     (only valid if MODEL = lastsnap)
  One or multiple snapshots are triggered. The number of snapshots to trigger and the time difference (in seconds) between each snapshot can be optionally specified. Without any specification only one snapshot is triggered.
  


• popupStream     (only valid if MODEL != master)
  The current streaming content is depicted in a popup window. By setting attribute "popupWindowSize" the size of display can be adjusted. The attribute "popupStreamTo" determines the type of the popup window. If "OK" is set, an OK-dialog window will be opened. A specified number in seconds closes the popup window after this time automatically (default 5 seconds).
  Optionally you can append "OK" or <seconds> directly to override the adjustment by attribute "popupStreamTo".



Get


• get <name> html
The stream object (camera live view, snapshots or replay) is fetched as HTML-code and depicted.



Attributes


• adoptSubset     (only valid for MODEL "master")
  In a Streaming master Device a subset of all defined Streaming Devices is selected and used for the adopt command is provided.
  For control in the FTUI, the selection is also stored in the Reading of the same name.


• autoRefresh
  If set, active browser pages of the FHEMWEB-Device which has called the SSCamSTRM-Device, are new reloaded after the specified time (seconds). Browser pages of a particular FHEMWEB-Device to be refreshed can be specified by attribute "autoRefreshFW" instead. This may stabilize the video playback in some cases.


• autoRefreshFW
  If "autoRefresh" is activated, you can specify a particular FHEMWEB-Device whose active browser pages are refreshed periodically.


• disable
  Deactivates the device.


• forcePageRefresh
  The attribute is evaluated by SSCam.
  If set, a reload of all browser pages with active FHEMWEB connections will be enforced when particular camera operations were finished. This may stabilize the video playback in some cases.


• genericStrmHtmlTag     (only valid for MODEL "generic")
  This attribute contains HTML-Tags for video-specification in a Streaming-Device of type "generic".
  
  
  Examples:

  attr <name> genericStrmHtmlTag <video $HTMLATTR controls autoplay>
                                   <source src='http://192.168.2.10:32000/$NAME.m3u8' type='application/x-mpegURL'>
                                 </video> 
                                 
  attr <name> genericStrmHtmlTag <img $HTMLATTR 
                                   src="http://192.168.2.10:32774"
                                   onClick="FW_okDialog('<img src=http://192.168.2.10:32774 $PWS>')"
                                 >  
        

  The variables $HTMLATTR, $NAME and $PWS are placeholders and absorb the attribute "htmlattr" (if set), the SSCam-Devicename respectively the value of attribute "popupWindowSize" in streaming-device, which specify the windowsize of a popup window.
  
  
  
• hideAudio
  Hide the control block for audio playback in the footer.


• hideButtons
  Hide the buttons in the footer. It has no impact for streaming devices of type "switched".


• hideDisplayName
  Hide the device/alias name (link to detail view).


• hideDisplayNameFTUI
  Hide the device/alias name (link to detail view) in FHEM TabletUI.


• htmlattr
  Additional HTML tags to manipulate the streaming device.
  
  
  Example:
  attr <name> htmlattr width="580" height="460"
  


• htmlattrFTUI
  Additional HTML tags to manipulate the streaming device in TabletUI.
  
  
  Example:
  attr <name> htmlattr width="580" height="460"
  


• noLink
  The device name or alias doesn't contain a link to the detail device view.


• popupStreamFW
  You can specify a particular FHEMWEB device whose active browser pages should open a popup window by the "set <name> popupStream" command (default: all active FHEMWEB devices).


• popupStreamTo [OK | <seconds>]
  The attribute "popupStreamTo" determines the type of the popup window which is opend by set-function "popupStream". If "OK" is set, an OK-dialog window will be opened. A specified number in seconds closes the popup window after this time automatically (default 5 seconds)..
  
  
  Example:
  attr <name> popupStreamTo 10
  
  
  
• popupWindowSize
  If the content of playback (Videostream or Snapshot gallery) is suitable, by clicking the content a popup window will appear. The size of display can be setup by this attribute. It is also valid for the get-function "popupStream".
  
  
  Example:
  attr <name> popupWindowSize width="600" height="425"
  


• ptzButtonSize
  Specifies the PTZ-panel button size (in %).


• ptzButtonSizeFTUI
  Specifies the PTZ-panel button size used in a Tablet UI (in %).

SSChatBot

[EN DE]

This module is used to integrate Synology Chat Server with FHEM. This makes it possible, Exchange messages between FHEM and Synology Chat Server.
A detailed description of the module is available in the Wiki available.


Definition


The definition is made with:


define <Name> SSChatBot <IP> [Port] [Protokoll]

The Port and Protocol entries are optional.


• IP: IP address or name of Synology DiskStation. If the name is used, set the dnsServer global attribute.
• Port: Port of Synology DiskStation (default 5000)
• Protocol: Protocol for messages towards chat server, http or https (default http)

During the definition, an extra FHEMWEB device for receiving messages is created in addition to the SSChaBot device in the "Chat" room. The port of the FHEMWEB device is automatically determined with start port 8082. If this port is occupied, the ports are checked in ascending order for possible assignment by an FHEMWEB device and the next free port is assigned to the new Device.
The chat integration distinguishes between "Incoming messages" (FHEM -> Chat) and "Outgoing messages (Chat -> FHEM).



Configuration


For the activation of incoming messages (FHEM -> Chat) a bot token is required. This token can be activated via the user-defined Embedding functions in the Synology Chat application can be created or modified from within the Synology Chat application. (see also the wiki section )
The token is inserted into the newly defined SSChatBot device with the command:


set <Name> botToken U6FOMH9IgT22ECJceaIW0fNwEi7VfqWQFPMgJQUJ6vpaGoWZ1SJkOGP7zlVIscCp

Use of course the real token created by the chat application.

For activation of outgoing messages (Chat -> FHEM) the field Outgoing URL must be filled in the chat application. To do so, click the Profile Photo icon in the upper right corner of the called Synology Chat Application and select "Integration." Then select the bot created in the first step in the "Bots" menu. The value of the internal OUTDEF of the created SSChatBot device is now copied into the field Outgoing URL.
For example, the string could look like this:


http://myserver.mydom:8086/sschat/outchat?botname=SynChatBot&fwcsrf=5de17731

(see also the wiki section )


General information on sending messages
Messages that FHEM sends to the chat server (incoming messages) are first placed in a queue in FHEM. The send process is started immediately. If the transmission was successful, the message is deleted from the queue. Otherwise, it remains in the queue and the send process will, in a time interval, restarted.
With the Set command restartSendqueue the processing of the queue can be started manually (for example, after Synology maintenance).

General information on message reception
To send commands from Chat Server to FHEM, slash commands (/) are used. They have to be configured before using them in Synology Chat and if necessary additionally in SSChatBot Device (User specific commands).

The following command forms are supported:


• /set
• /get
• /code
• /<User specific command> (see attribute ownCommandx)

Further detailed information on configuring message reception is available in the corresponding wiki section.


Set


• asyncSendItem <Item>
  Sends a message to one or more chat recipients.
  For more information about the available options for asyncSendItem, especially the use of interactive objects (buttons), please consult this wiki section.
  
  
  Beispiele:
  set <Name> asyncSendItem First message line to post.\n You can also have a second message line. [users="<User>"]
  set <Name> asyncSendItem text="First message line to post.\n You can also have a second message line. [users="<User>"]
  set <Name> asyncSendItem text="https://www.synology.com" [users="<User>"]
  set <Name> asyncSendItem text="Check this! <https://www.synology.com|Click here> for details!" [users="<User1>,<User2>"]
  set <name> asyncSendItem text="a funny picture" fileUrl="http://imgur.com/xxxxx" [users="<User1>,<User2>"]
  set <Name> asyncSendItem text="<Message text>" attachments="[{ "callback_id": "<Text for Reading recCallbackId>", "text": "<Heading of the button>", "actions":[{"type": "button", "name": "<text>", "value": "<value>", "text": "<text>", "style": "<color>"}] }]"
  
  
  Plot outputs from SVG devices can be sent directly:
  
  
  set <Name> asyncSendItem text="current plot file" svg="<SVG-Device>[,<Zoom>][,<Offset>]" [users="<User1>,<User2>"]
  
  
  Further information is available in the Wiki.


• botToken <Token>
  Saves the token for access to the chat as a bot.


• listSendqueue
  Shows the messages still to be transmitted to the chat.
  All messages to be sent are first stored in a queue and transmitted asynchronously to the chat server.


• purgeSendqueue <-all- | -permError- | index>
  Deletes entries from the send queue.
  
  
  • -all- : Deletes all entries of the send queue.
  • -permError- : Deletes all entries of the send queue with "permanent Error" status.
  • index : Deletes selected entry with "index".
    The entries in the send queue can be viewed beforehand with "set listSendqueue" to find the desired index.


• restartSendqueue [force]
  Restarts the processing of the send queue manually.
  Any entries in the send queue marked forbidSend are not sent again.
  If the call is made with the option force, entries marked forbidSend are also taken into account.


Get


• apiInfo
  Retrieves the API information of the Synology Chat Server and open a popup window with its data.
  


• chatChannellist
  Creates a list of channels visible to the bot.


• chatUserlist
  Creates a list of users visible to the bot.
  If no users are listed, the users on Synology must have permission to use the chat application can be assigned.


• storedToken
  Displays the stored token.


• versionNotes
  Lists significant changes in the version history of the module.


Attributes


• allowedUserForCode
  Names the chat users who are allowed to trigger Perl code in FHEM when the slash command /code is received.
  (default: all users allowed)


• allowedUserForGet
  Names the chat users who may trigger Get commands in FHEM when the slash command /get is received.
  (default: all users allowed)


• allowedUserForOwn
  Names the chat users who are allowed to trigger the commands defined in the attribute "ownCommand" in FHEM.
  (default: all users allowed)


• allowedUserForSet
  Names the chat users who are allowed to trigger set commands in FHEM when the slash command /set is received.
  (default: all users allowed)


• defaultPeer
  One or more (default) recipients for messages. Can be specified with the users= tag in the command asyncSendItem can be overridden.


• httptimeout <seconds>
  Sets the connection timeout to the chat server.
  (default 20 seconds)


• ownCommandx <Slash command> <Command>
  Defines a <Slash command> <Command> pair. The slash command and the command are separated by a Separate spaces.
  The command is executed when the SSChatBot receives the slash command. The command can be an FHEM command or Perl code. Perl code must be enclosed in { }.
  
  
  Examples:
  attr <Name> ownCommand1 /Wozi_Temp {ReadingsVal("eg.wz.wallthermostat","measured-temp",0)}
  attr <Name> ownCommand2 /Wetter get MyWetter wind_speed
  


• showTokenInLog
  If set, the transmitted bot token is displayed in the log with verbose 4/5.
  (default: 0)


• spareHost
  Replaces the automatically determined hostname in the internal OUTDEF with a user-specific hostname or IP address.
  The URL of the internal OUTDEF is the target for outgoing messages (chat -> FHEM) and is evaluated when sending of SVG plot files.
  


• sparePort
  Replaces the automatically determined port in the internal OUTDEF with a user-specific value.
  The URL of the internal OUTDEF is the target for outgoing messages (chat -> FHEM) and is evaluated when sending of SVG plot files.
  

SSFile

[EN DE]

This module is used to integrate the Synology File Station into FHEM. The SSFile module is based on functions of the Synology File Station API.

The connection to the Synology server is done via a session ID after successful login. Requests/queries of the server are stored internally in a queue and processed sequentially. If the server is temporarily unavailable, the stored queries are processed as soon as the connection to the server is available again.

Preparation


As a basic requirement, the Synology File Station Package must be installed on the disk station.
The credentials of the used user are later assigned to the created device via a set credentials command. created.


Definition

The definition is made with:


define <Name> SSFile <ServerAddr> [<Port>] [<Protocol>]


The parameters describe in detail:



Name	the name of the new device in FHEM
ServerAddr	the IP address of the Synology DS. Note: If the DNS name is used instead of IP address, the attribute dnsServer should be set in the global Device !
Port	optional - port of Synology DS (default: 5000).
Protocol	optional - protocol to communicate with the DS, http or https (default: http).



Examples:

      define SynBackup SSFile 192.168.2.10 
      define SynBackup SSFile 192.168.2.10 5001 https 
      # creates a SSFile device with default port (5000/http) or https with port 5001.
     

After defining a device, only the set command credentials is available. This command first makes the access parameters known to the Device.


Set


• credentials <user> <password>
  Saves the credentials.
  


• deleteUploadsDone
  Deletes the history of all successfully executed uploads to Synology Diskstation.
  


• deleteRemoteObject "<File>[,<File>,...]" | "<Folder>[,<Folder>,...]" [<args>]
  Deletes the specified files or directories on Synology Diskstation. Multiple objects are to be separated by commas. Directories are to be entered without "/" at the end. All specified objects are to be enclosed in " altogether.
  
  Optionally can be specified as <args>:
  

  recursive=	true: Delete files within a folder recursively. (default)
  	false: Delete only first level file/folder. If a folder to be deleted contains a file, an error will occur because the folder cannot be deleted directly.

  
  Examples:
  set <Name> deleteRemoteObject "/backup/Carport-20200625-1147065130.jpg"
  set <Name> deleteRemoteObject "/backup/log,/backup/cookie - old.txt"
  set <Name> deleteRemoteObject "/backup/log/archive" recursive=false
  


• Download "<File>[,<File>,...]" | "<Folder>[,<Folder>,...]" [<args>]
  Transfers the specified file(s) or folder(s) from Synology Diskstation to the destination. If a folder is specified, it or the contents will be saved compressed in zip format to a file. Without further specification the source object will be stored in the FHEM root directory (usually /opt/fhem), depending on the setting of the global attribute modpath, stored with identical name.
  
  Optionally specify:
  

  dest=	<filename>: the object will be saved with new name in default path
  	<path/filename>: the object will be saved with new name in the given path
  	<path/>: the object will be saved with original name in the specified path. Important: the path must end with a "/".

  
  All specified objects must be enclosed in " altogether.
  
  Examples:
  set <Name> Download "/backup/Carport-20200625-1147065130.jpg"
  set <Name> Download "/backup/Carport-20200625-1147065130.jpg" dest=carport.jpg
  set <Name> Download "/backup/Carport-20200625-1147065130.jpg" dest=./log/carport.jpg
  set <Name> Download "/backup/Carport-20200625-1147065130.jpg" dest=./log/
  set <Name> Download "/temp/applications 2020,/backup/Carport-20200625-1147065130.jpg"
  set <Name> Download "/backup/Carport-20200625-1147065130.jpg,/Temp/card.txt" dest=/opt/
  


• listQueue
  Shows all entries in the send queue. The queue is normally only filled for a short time, but in case of a problem it can contain contain entries permanently. This allows an error that occurred during a polling task to be determined and assigned be assigned.
  


• listUploadsDone
  Displays a table with date/time, source file and destination object of all successfully executed uploads to Synology Diskstation.
  


• logout
  The user is logged out and the session is ended with .
  


• prepareDownload "<File>[,<File>,...]" | "<Folder>[,<Folder>,...]" [<args>]
  Identical to the "Download" command. The download of the files/folders from the Synology Diskstation is however not immediately but the entries are only put into the send queue. To start the transfer, the command
  
  .
  set <Name> startQueue
  
  must be executed.


• prepareUpload "<File>[,<File>,...]" | "<Folder>[,<Folder>,...]" <args>
  Identical to the "Upload" command. However, the transfer of the files to the Synology Diskstation is not immediately but the entries are only put into the send queue. Finally, to start the transfer, the command
  
  .
  set <Name> startQueue
  
  must be executed.


• purgeQueue
  Purges entries in the send queue. Several options are available depending on the situation:
  
  .

  -all-	deletes all entries present in the send queue
  -permError-	deletes all entries that are excluded from further processing due to a permanent error
  <Index>	deletes a unique entry from the send queue



• startQueue
  The processing of the entries in the send queue is started. For most commands, the processing of the send queue is started is started implicitly.
  


• Upload "<File>[,<File>,...]" | "<Folder>[,<Folder>,...]" <args>
  Transfers the specified local file(s)/folder(s) to Synology Diskstation. In the dest argument, specify the destination directory on the Synology DiskStation. The path of the local file(s)/folder(s) to be transferred can be specified as an absolute or relative path to the FHEM global modpath can be specified.
  Files and folder contents are read out in the standard including Subordner and transferred to the Destination structure receiving. Files can contain wildcards (*.) to upload only certain files.
  Subdirectories are created by default in the destination if they do not exist.
  All specified objects are to be enclosed in " altogether.
  
  Mandatory arguments:
  

  dest=	<Folder>: destination path to store the files in the Synology filesystem (the path starts with a shared folder and ends without "/")
  	POSIX % wildcards can be specified.

  
  Optional arguments:
  

  ow=	true: the file will be overwritten if present in the destination path (default), false: the file will not be overwritten
  cdir=	true: create parent folder(s) if not present. (default), false: do not create parent folder(s)
  mode=	full: all objects except those specified in the excludeFromUpload attribute will be included (default)
  	inc: only new objects and objects that have changed after the last upload will be considered
  	nth:<days>: only objects newer than <days> are considered (fractional numbers are allowed, e.g. 3.6)
  struc=	true: all objects including their directory structure will be stored in the destination path (default)
  	false: all objects will be saved without their original directory structure in the destination path

  
  Examples:
  set <Name> Upload "./text.txt" dest=/home/upload
  set <Name> Upload "/opt/fhem/old data.txt" dest=/home/upload ow=false
  set <Name> Upload "./archive new 2020.txt" dest=/home/upload
  set <Name> Upload "./log" dest=/home/upload mode=inc struc=false
  set <Name> Upload "./log/*.txt,./log/archive/fhem-2019-12*.*" dest=/home/upload mode=full
  set <Name> Upload "./log" dest=/home/upload/%Y_%m_%d_%H_%M_%S mode=full struc=false
  set <Name> Upload "./" dest=/home/upload mode=inc
  set <Name> Upload "/opt/fhem/fhem.pl,./www/images/PlotToChat.png,./log/fhem-2020-10-41.log" dest=/home/upload
  


Get


• apiInfo
  Gets the API information of Synology File Station and opens a popup with this information.


• remoteFileInfo "<File>[,<File>,...]"
  Lists information from one or more files on Synology Diskstation separated by a comma ",". All objects must be enclosed in " altogether.
  
  Example:
  get <Name> remoteFileInfo "/ApplicationBackup/export.csv,/ApplicationBackup/export_2020_09_25.csv"
  



• remoteFolderList [<args>]
  Lists all shared folders or files in a specified folder on Synology Diskstation and creates detailed file information. Without argument, all shared root folders are listed. A folder path and additional options can be specified.
  
  

  sort_direction=	asc: sort ascending, desc: sort descending
  onlywritable=	true: list writable shared folders, false: list writable and read-only shared folders
  limit=	integer: number of files requested. 0 - show all files in a given folder (default).
  pattern=	Pattern to filter files to display or file extensions. Multiple patterns can be specified separated by ",".
  filetype=	file: list files only, dir: list folders only, all: list files and folders

  
  Objects with spaces in their names should be enclosed in ".
  
  Examples:
  get <name> remoteFolderList /home
  get <Name> remoteFolderList "/home/30_house & construction"
  get <Name> remoteFolderList "/home/30_house & construction" filetype=file limit=2
  get <Name> remoteFolderList "/home/30_house & construction" sort_direction=desc
  get <Name> remoteFolderList /home/lyrics pattern=doc,txt



• storedCredentials
  Shows the stored user/password combination.



• versionNotes
  Shows information and help about the module.



Attributes


• additionalInfo
  Sets the additional properties to display when retrieving file or directory information.


• excludeFromUpload
  The entered files or directories will be excluded from upload (transfer to Synology Diskstation). The entries are evaluated as regex. Multiple objects must be separated by commas.
  Note: Files/directories with "@" in the name are excluded from upload by default.
  
  Example:
  attr <name> excludeFromUpload ./FHEM/FhemUtils/cacheSSCam.*,./www/SVGcache.*


• interval <seconds>
  Automatically start the internal queue every X seconds. All entries contained in the queue at the start time. (e.g. inserted with prepareUpload) are processed. If "0" is specified, no automatic start is executed. (default)


• loginRetries
  Number of attempts for the initial user login.
  (default: 3)


• noAsyncFillQueue
  Filling the upload queue can be very time consuming depending on the number of files/folders to upload and can potentially block FHEM potentially block. For this reason, the queue is filled in a concurrent process.
  If only few entries are to be processed or with very fast systems can be renounced by setting this attribute the use of the additional process. Use of the additional process can be waived.
  (default: 0)


• showPassInLog
  If "1", the password or SID will be shown in the log.
  (default: 0)


• timeout <seconds>
  Timeout for communication with the File Station API in seconds.
  (default: 20)

STACKABLE

[EN DE]

This module is a more generic version of the STACKABLE_CC module, and is used for stacked IO devices like the Busware SCC. It works by adding/removing a prefix (default is *) to the command, and redirecting the output to the module, which is using it. Define
define <name> STACKABLE <baseDevice>

<baseDevice> is the name of the unterlying device.
Example:
define CUL_1 CUL /dev/ttyAMA0@38400
attr CUL_1 rfmode SlowRF

define CUL_1_SCC STACKABLE CUL1
define CUL_2 CUL FHEM:DEVIO:CUL_1_SCC:9600 0000
attr CUL_2 rfmode HomeMatic

define CUL_2_SCC STACKABLE CUL2
define CUL_3 ZWCUL FHEM:DEVIO:CUL_2_SCC:9600 12345678 01

Note:If you rename the base CUL or a STACKABLE, which is a base for another one, the definition of the next one has to be adjusted, and FHEM has to be restarted.
Set
N/A

Get
N/A

Attributes
• writePrefix
  The prefix used when writing data, default is *. "readPrefix" is hardcoded to *.


• binary
  If set to true, read data is converted to binary from hex before offering it to the client IO device (e.g. TCM). Default is 0 (off).

STACKABLE_CC

[EN DE]

This module handles the stackable CC1101 devices for the Raspberry PI from busware.de. You can attach a lot of CUL-Type devices to a single RPi this way. The first device is defined as a CUL, the rest of them as STACKABLE_CC.

Define
define <name> STACKABLE_CC <Base-Device-Name>

<Base-Device-Name> is the name of the device, which this device is attached on, the first one has to be defined as a CUL device
Example:
define SCC0 CUL /dev/ttyAMA0@38400
attr SCC0 rfmode SlowRF
define SCC1 STACKABLE_CC SCC0
attr SCC1 rfmode HomeMatic
define SCC2 STACKABLE_CC SCC1
attr SCC2 rfmode Max

Important:
• The rfmode has to be specified explicitely (valid for the STACKABLE_CC types only, not for the first, which is defined as a CUL).
• In case of SlowRF, the FHTID has to be specified explicitely with the command "set SCCX raw T01HHHH". Again, this is valid for the STACKABLE_CC types only.
• If you rename the base CUL or a STACKABLE_CC, which is a base for another one, the define of the next one has to be adjusted, and FHEM has to be restarted.
Set
Same as for the CUL.

Get
Same as for the CUL.

Attributes
• IODev


• ignore

The rest of the attributes is the same as for the CUL.

STV

[EN DE]

This module supports Samsung TV devices.
LEXXBXX (B Series) use port 52235
LEXXCXX (C|D Series) use port 55000


Define
define <name> STV <host>]


Example:
define Television1 STV 192.168.178.20
or define Television2 STV 192.168.178.20 52235
define Television2 STV 192.168.178.20 55000


Set
set <name> <value> <nummber>
where value is one of:


• mute
• volume
• call
• sms
• date

Example:
set <name> mute
set <name> volume 20
set <name> call Peter 012345678 Phone 87654321

Get

N/A

SUNRISE_EL

[EN DE]

This module is used to define the functions

sunrise, sunset,
sunrise_rel, sunset_rel
sunrise_abs, sunset_abs
isday

perl functions, to be used in at or FS20 on-till commands.
First you should set the longitude and latitude global attributes to the exact longitude and latitude values (see e.g. maps.google.com for the exact values, which should be in the form of a floating point value). The default value is Frankfurt am Main, Germany.

The default altitude ($defaultaltit in SUNRISE_EL.pm) defines the sunrise/sunset for Civil twilight (i.e. one can no longer read outside without artificial illumination), which differs from sunrise/sunset times found on different websites. See perldoc "DateTime::Event::Sunrise" for alternatives.

sunrise() and sunset() return the absolute time of the next sunrise/sunset, adding 24 hours if the next event is tomorrow
sunrise_rel() and sunset_rel() return the relative time to the next sunrise/sunset.
sunrise_abs() and sunset_abs() return the absolute time of the corresponding event today (no 24 hours added).
sunrise_abs_dat() and sunset_abs_dat() return the absolute time of the corresponding event to a given date.
Note: use sunrise/sunset in the timespec of an at device or on-till command as the _rel and _abs variants do not work correctly there.

All functions take up to four arguments:

• altitude (optional) altitude defines a horizon value which then is used instead of the $defaultaltit in SUNRISE_EL.pm.
  Possible values are: "REAL", "CIVIL", "NAUTIC", "ASTRONOMIC" or a positive or negative number prefixed with "HORIZON="
  REAL is 0, CIVIL is -6, NAUTIC is -12, ASTRONOMIC is -18 degrees above horizon.
  
• time-offset in seconds, which will be added to the event.
• min and max values (format: "HH:MM"). If min < max, than the day starts not before min, and ends not after max. If min > max, than the day starts not after max, and ends not before min.

isday() can be used in some notify or at commands to check if the sun is up or down. isday() ignores the time-offset parameter, but respects min and max.

Examples:


    # When sun is 6 degrees below horizon - same as sunrise();
    sunrise("CIVIL");

    # When sun is 3 degrees below horizon (between real and civil sunset)
    sunset("HORIZON=-3");

    # When sun is 1 degree above horizon
    sunset("HORIZON=1");

    # Switch lamp1 on at real sunset, not before 18:00 and not after 21:00
    define a15 at *{sunset("REAL",0,"18:00","21:00")} set lamp1 on
  

The functions sunrise_abs_dat()/sunset_abs_dat() need as a very first parameter the date(format epoch: time()) for which the events should be calculated.

Examples:


    # to calculate the sunrise of today + 7 days
    my $date = time() + 7*86400;
    sunrise_abs_dat($date);
    
    # to calculate the sunrise of today + 7 days 6 degrees below horizon 
    my $date = time() + 7*86400;
    sunrise_abs_dat($date, "CIVIL");    
  

Define
N/A

Set
N/A

Get
N/A

Attributes

• latitude
• longitude

SVDRP

SVDRP implements SVDRP to control VDR via (W)Lan.

Define
define <name> SVDRP <IP_Address> [<port>]

70_SVDRP.pm provides basic control of your VDR.
Only a reasonable subset of SVDRP commands in implemented, since it e.g. does not make sense to set timers via fhem - vdradmin is a much more convenient GUI for that.


• IP_Address - the IP Address of your VDR
• port - ... guess? Yes, the port. If not given, VDR standard port 6419 is used.
• Example: define VDRcontrol SVDRP 10.10.0.1 6419

Set


Available set commands are taken from http://www.vdr-wiki.de/wiki/index.php/SVDRP.
For the predefined "raw" commands, "nice" names will be shown for the readings, e.g. DiskStatus instead of STAT disk.
Default set commands are


• Channel
  set value can be "+" or "-" or any channel number you want to switch to.
  set <name> Channel will get you the channel VDR is currently tuned to.


• DeleteTimer
  set <name> DeleteTimer <number> will delete ... hm, guess?
  (you can get the timer numbers via ListTimers)


• DiskStatus
  no value or get will display the current disk usage in DiskStatus
  Additionally, the reading DiskUsed will be set to the disk fill level.


• GetAll
  no value or get will query several SVDRP settings:
  "LSTT", "NEXT", "CHAN", "VOLU", "STAT"
  (i.e. ListTimers, NextTimer, Channel, Volume, DiskStatus)


• Help
  gets the avaialble SVDRP commands from VDR and stores them in reading "HelpInfo"
• HitKey
  Enables you to send any Key defined by http://www.vdr-wiki.de/wiki/index.php/SVDRP
  E.g.set <name> HitKey Power will cleanly power off VDR.


• ListRecording
  set value should be an existing recording ID. Depending on the attribute RecordingInfo either all available info will be shown, or a reasonable subset.
  If no value is given, all available recordings will be read and shown.
  Attention: Depending on the number of number of recordings, this might take a while! fhem might show "timeout", and a screen refresh might be necessary. Use with care...


• ListTimers
  no value or get will query all timers from VDR.
  raw answer from VDR will be parsed into a little bit nicer format.


• NextTimer
  no value or get will exactly get what it says.
  (to get the timer name, ListTimers will be called before)


• Plugin
  calls SVDRP with PLUG - you can enter any Plugin's SVDRP commands here to control the plugin
  calling without parameter gets the list of avaialble plugins and stroes them in reading "HelpInfo"
  I cannot test this with any plugin, but the Plugin's answer should go to the reading "PluginInfo" or "InfoError" (if Plugin gives an error message)


• PowerOff
  A shortcut to cleanly power off VDR, same as set <name> HitKey Power


• SatIP
  send control commands to your SatIP plugin


• StreamdevServer
  sends the corresponding SVDRP command to the streamdev-Plugin (LSTC,DISC)


• UpdateRecordings
  no value or get will trigger VDR to re-read the recordings.
  (No output to fhem - no sense to show all recordings here)


• Volume
  set value can be "+" or "-" or mute or any Volume (0-255) you want to set.
  set <name> Volume will get you VDR's current Volume setting.


• connect
  just connects to VDR, no further action.
  Reading "info" will be updated.
  Attention: As long as connection to VDR is open, no other SVDRP client can connect!
  You might want to use "cleanup" to be able to reconnect other clients.


• cleanUp
  closes connection to VDR, no further action.
  Reading "info" will be updated.


• closeDev
  subset of cleanup. Just closes DevIo connection.
  If you don't know what that means, you don't need it ;-)

Attributes

• AdditionalSettings
  cmd1:val_1,...,val_n cmd2:val_1,...,val_n
  You can specify own set commands here, they will be added to the set list.
  Multiple own sets can be specified, separated by a blank.
  command and values are separated by ":", values are separated by ",".
  Example: HITK:up,down,Power MESG


• RecordingInfo
  short|long
  defines the amount of information shown on ListRecording
  short will display recording iD, title, subtitle, Description
  long will show all available information of the requested Recording
  Default value is "short"


• connectionCheck
  off|(value in seconds)
  value defines the intervall in seconds to perform an connection check.
  Normally you won't need that. Use at your own risk...
  Default value is "off".


• statusCheckInterval
  off|(value in seconds)
  value defines the interval in seconds to perform an status check.
  Each interval the VDR is queried with the command defined by statusCheckCmd (default: DiskStatus).
  Default value is off.


• statusCheckCmd
  (any command(s) you set)
  Defines the command(s) used by statusCheckInterval.


• statusOfflineMsg
  (any message text you set)
  Defines the message to set in the Reading related to statusCheckCmd when the device goes offline.
  Status of device will be checked after each statusCheckInterval (default: off), querying the statusCheckCmd command (default: DiskStatus), and if STATE is disconnected the Reading of statusCheckCmd will be set to this message. Default: closed.


• delay
  delay time in seconds
  Depending on the answering speed of your VDR, it might be necessary to grant a certain delay beween opening the connection (and getting the initial answer shown in reading "info"), sending a command, receiving the result and closing the connection.
  Default: 1.

SVG

Define
define <name> SVG <logDevice>:<gplotfile>:<logfile>

This is the Plotting/Charting device of FHEMWEB Examples:
define MyPlot SVG inlog:temp4hum4:CURRENT


Notes:
• Normally you won't define an SVG device manually, as FHEMWEB makes it easy for you, just plot a logfile (see logtype) and click on "Create SVG instance". Specifying CURRENT as a logfilename will always access the current logfile, even if its name changes regularly.
• For historic reasons this module uses a Gnuplot file description to store different attributes. Some special commands (beginning with #FileLog or #DbLog) are used additionally, and not all gnuplot attribtues are implemented.
Set
• copyGplotFile
  Copy the currently specified gplot file to a new file, which is named after the SVG device, existing files will be overwritten. This operation is needed in order to use the plot editor (see below) without affecting other SVG instances using the same gplot file. Creating the SVG instance from the FileLog detail menu will also create a unique gplot file, in this case this operation is not needed.

Get
N/A

Attributes
• endPlotNow
  If this attribute is set to 1, then day and hour plots will end at current time. Else the whole day, the 6 hour period starting at 0, 6, 12 or 18 hour or the whole hour will be shown. This attribute is not used if the SVG has the attribute startDate defined.


• endPlotNowByHour
  If endPlotNow and this attribute are set to 1 and the zoom-level is "day", then the displayed hour ticks will be rounded to the complete hour.


• endPlotToday
  If this attribute is set to 1, then week and month plots will end today. Else the current week or the current month will be shown.


• captionLeft
  Show the legend on the left side (deprecated, will be autoconverted to captionPos)


• captionPos
  right - Show the legend on the right side (default)
  left - Show the legend on the left side
  auto - Show the legend labels on the left or on the right side depending on the axis it belongs to
  


• fixedrange [offset]
  Contains two time specs in the form YYYY-MM-DD separated by a space. In plotmode gnuplot-scroll(-svg) or SVG the given time-range will be used, and no scrolling for this SVG will be possible. Needed e.g. for looking at last-years data without scrolling.
  
  If the value is one of hour, <N>hours, day, <N>days, week, month, year, <N>years then set the zoom level for this SVG independently of the user specified zoom-level. This is useful for pages with multiple plots: one of the plots is best viewed in with the default (day) zoom, the other one with a week zoom.
  If given, the optional integer parameter offset refers to a different period (e.g. last year: fixedrange year -1, 2 days ago: fixedrange day -2).
  If the attribute value is enclosed in {}, then it is evaluated first as a perl expression.


• fixedoffset <offset>
  Set a fixed offset for the plot. The resolution is the currently chosen zoom-level.
  Is evaluated as a perl expression, if enclosed in {}. If the current resolution is day, fixedoffset with {$FW_pos{off}-1} will show the data from the day before the current selection.


• label
  Double-Colon separated list of values. The values will be used to replace <L#> type of strings in the .gplot file, with # beginning at 1 (<L1>, <L2>, etc.). Each value will be evaluated as a perl expression, so you have access e.g. to the Value functions.
  
  If the plotmode is gnuplot-scroll(-svg) or SVG, you can also use the min, max, mindate, maxdate, avg, cnt, sum, firstval, firstdate, currval (last value) and currdate (last date) values of the individual curves, by accessing the corresponding values from the data hash, see the example below:
  
  • Fixed text for the right and left axis:
    
    • Fhem config:
      attr wl_1 label "Temperature"::"Humidity"
    • .gplot file entry:
      set ylabel <L1>
      set y2label <L2>
  • Title with maximum and current values of the 1st curve (FileLog)
    • Fhem config:
      attr wl_1 label "Max $data{max1}, Current $data{currval1}"
    • .gplot file entry:
      set title <L1>
      
  The value minAll and maxAll (representing the minimum/maximum over all values) is also available from the data hash.
  Deprecated, see plotReplace.


• nrAxis
  the number of axis for which space should be reserved on the left and right sides of a plot and optionaly how many axes should realy be used on each side, separated by comma: left,right[,useLeft,useRight]. You can set individual numbers by setting the nrAxis of the SVG. Default is 1,1.


• plotAsPngFix [0|1]
  Affects only the plotAsPng function: Some LibRSVG versions cannot cope with complex CSS selectors, so the resulting PNG is black and white only. If this attribute is set to 1, the CSS selector complexity will be reduced.


• plotAsPngPort <portNum>
  Affects only the plotAsPng function: Use a specific FHEMWEB instance.


• plotfunction
  Space value separated list of values. The value will be used to replace <SPEC#> type of strings in the .gplot file, with # beginning at 1 (<SPEC1>, <SPEC2>, etc.) in the #FileLog or #DbLog directive. With this attribute you can use the same .gplot file for multiple devices with the same logdevice.
  Example:
  
  • #FileLog <SPEC1>
    with: attr <SVGdevice> plotfunction "4:IR\x3a:0:"
    instead of
    #FileLog 4:IR\x3a:0:
  • #DbLog <SPEC1>
    with: attr <SVGdevice> plotfunction "Garage_Raumtemp:temperature::"
    instead of
    #DbLog Garage_Raumtemp:temperature::
  Deprecated, see plotReplace.


• plotmode
  Specifies how to generate the plots:
  • SVG
    The plots are created with the SVG module. This is the default.
  • gnuplot-scroll
    The plots are created with the gnuplot program. The gnuplot output terminal PNG is assumed. Scrolling to historical values is also possible, just like with SVG.
  • gnuplot-scroll-svg
    Like gnuplot-scroll, but the output terminal SVG is assumed.


• plotReplace
  space separated list of key=value pairs. value may contain spaces if enclosed in "" or {}. value will be evaluated as a perl expression, if it is enclosed in {}.
  In the .gplot file <key> and %key% will be replaced with the corresponding value. The evaluation of <key> takes place after the input file is processed, so e.g. $data{min1} can be used in the title. %key% will be repaced before the input file is processed, this expression can be used to replace parameters for the input processing.


• plotsize
  the default size of the plot, in pixels, separated by comma: width,height. You can set individual sizes by setting the plotsize of the SVG. Default is 800,160 for desktop, and 480,160 for smallscreen.


• plotWeekStartDay
  Start the week-zoom of the SVG plots with this day. 0 is Sunday, 1 is Monday, etc.
  


• startDate
  Set the start date for the plot. Used for demo installations.


• title
  A special form of label (see above), which replaces the string <TL> in the .gplot file. It defaults to the filename of the logfile.
  Deprecated, see plotReplace.



Plot-Editor
This editor is visible on the detail screen of the SVG instance. Most features are obvious here, up to some exceptions:
• if you want to omit the title for a Diagram label, enter notitle in the input field.
• if you want to specify a fixed value (not taken from a column) if a string found (e.g. 1 if the FS20 switch is on and 0 if it is off), then you have to specify the Tics first, and write the .gplot file, before you can select this value from the dropdown.
  Example:
  Enter in the Tics field: ("On" 1, "Off" 0)
  Write .gplot file
  Select "1" from the column dropdown (note the double quote!) for the regexp switch.on, and "0" for the regexp switch.off.
  Write .gplot file again
  
• If the range is of the form {...}, then it will be evaluated with perl. The result is a string, and must have the form [min:max]
The visibility of the ploteditor can be configured with the FHEMWEB attribute ploteditor.

SWAP

[EN DE]

The SWAP protocoll is used by panStamps (panstamp.com).

This is a generic module that will handle all SWAP devices with known device description files via a panStick as the IODevice.

All communication is done on the SWAP register level. FHEM readings are created for all user registers and userReadings are created to map low level SWAP registers to 'human readable' format with the mapping from the device descriprion files.

For higher level features like "on,off,on-for-timer,..." specialized modules have to be used.

Messages for devices in power-down-state are queued and send when the device enters SYNC state. This typicaly happens during device startup after a reset.

Notes:
• This module requires XML::Simple.
• Devices with the default address FF will be changed to the first free address in the range F0-FE.
• For power-down devices the default transmit interval of FFFF will be changed to 0384 (900 seconds).


Define
define <name> SWAP <ID>

The ID is a 2 digit hex number to identify the moth in the panStamp network.

Set
• regGet <reg>
  request status message for register id <reg>. for system registers the register name can be used instead if the two digit register id in hex.


• regSet <reg> <data>
  write <data> to register id <reg>. for system registers the register name can be used instead if the twi digit register id in hex.


• regSet <reg>.<ep> <data>
  write <data> to endpoint <ep> of register <reg>. will not work if no reading for register <reg> is available as all nibbles that are not part of endpoint <ep> will be filled from this reading.


• statusRequest
  request transmision of all registers.


• readDeviceXML
  reload the device description xml file.


• clearUnconfirmed
  clears the list of unconfirmed messages.


• flash [<productCode>|<firmwareFile>]
  will initiate an ota firmware update. only possible for panStamp NRG devices.
  no params -> will use the SWAP_<current productCode>.hex file from the FHEM/firmware directory.
  <productCode> -> will use the SWAP_<productCode>.hex file from the FHEM/firmware directory.
  <firmwareFile> -> will use <firmwareFile> as the absolute file name of the hex file.
  


Get
• regList
  list all non-system registers of this device.


• regListAll
  list all registers of this device.


• listUnconfirmed
  list all unconfirmed messages.


• products
  dumps all known devices.


• deviceXML
  dumps the device xml data.


Attributes
• createUnknownReadings
  Create readings for unknown registers, i.e. registers not defined in the device xml file.


• ProductCode
  ProductCode of the device. used to read the register configuration from the device definition file. hast to be set manualy for devices that are in sleep mode during definition.

SWAP_0000002200000003

[EN DE]

Module for the justme version of the panstamp rgb driver board with ir (sketch product code 0000002200000003).

to learn an ir command the simplest way ist to use 'learnIR #'. the on board led will start to blink indicating ir learning mode. after an ir command is received the blinking will switch to slow and the boards waits for a fhem command (on/off/...) and will link the ir command to the fhem command.

received ir commands that will not trigger one of the 16 possible learned commands will be send as SWAP register 0C to fhem and can be used in notifys.

SWAP register 0E will configure the power on state of the board: off, configured color, last color before power down.

Define
define <name> SWAP_0000002200000003 <ID> 0000002200000003



Set all SWAP set commands and:
• on
  
• on-for-timer <time>
  
• off
  
• toggle
  


• rgb <RRGGBB>
  set the led color


• dimUP
  
• dimDown
  


• setIR # <code>
  
• learnIR #
  
• storeIR # <code> <command>
  


• getIR # | all
  read content of IR regisgter # or all IR registers


• setFade <RRGGBB> <time>
  stores color and time in fede register #


• startFade <#1> <#2>
  starts an endless fading loop over all fading registers [#1..#2]


• getFade # | all
  read content of fade regisgter # or all fade regisgters


• set extensions are supported.

Get all SWAP get commands and:
• rgb
  returns the current led color


• listIR
  list all IR registers of this device. use getIR first.


• listFade
  list all fade registers. use getFade first.



Attributes
• color-icon
  1 -> use lamp color as icon color and 100% shape as icon shape
  2 -> use lamp color scaled to full brightness as icon color and dim state as icon shape
• ProductCode
  must be 0000002200000003

SWAP_0000002200000008

[EN DE]

Module for the justme version of the panstamp indoor multi sensor board (sketch product code 0000002200000008).

Define
define <name> SWAP_0000002200000008 <ID> 0000002200000008



Set all SWAP set commands and:
• desired <value>
  sets the desired temperature to <value>
• text <text>
  displays text

Get all SWAP get commands and:

Attributes
• ProductCode
  must be 0000002200000008

SYSMON

[EN DE]

(en | de)

This module provides statistics about the system running FHEM server. Furthermore, remote systems can be accessed (Telnet). Only Linux-based systems are supported. Some informations are hardware specific and are not available on every platform. So far, this module has been tested on the following systems: Raspberry Pi (Debian Wheezy), BeagleBone Black, FritzBox 7390, WR703N under OpenWrt, CubieTruck and some others.

For more information on a FritzBox check other moduls: FRITZBOX and FB_CALLMONITOR.
The modul uses the Perl modul 'Net::Telnet' for remote access. Please make sure that this module is installed.

Define

define <name> SYSMON [MODE[:[USER@]HOST][:PORT]] [<M1>[ <M2>[ <M3>[ <M4>]]]]

This statement creates a new SYSMON instance. The parameters M1 to M4 define the refresh interval for various Readings (statistics). The parameters are to be understood as multipliers for the time defined by INTERVAL_BASE. Because this time is fixed at 60 seconds, the Mx-parameter can be considered as time intervals in minutes.
If one (or more) of the multiplier is set to zero, the corresponding readings is deactivated.

The parameters are responsible for updating the readings according to the following scheme:
• M1: (Default: 1)
  cpu_freq, cpu_temp, cpu_temp_avg, loadavg, stat_cpu, stat_cpu_diff, stat_cpu_percent, stat_cpu_text, power readings
  
  
• M2: (Default: M1)
  ram, swap
  
• M3: (Default: M1)
  eth0, eth0_diff, wlan0, wlan0_diff
  
  
• M4: (Default: 10*M1)
  Filesystem informations
  
  
• The following parameters are always updated with the base interval (regardless of the Mx-parameter):
  fhemuptime, fhemuptime_text, idletime, idletime_text, uptime, uptime_text, starttime, starttime_text
  
  
To query a remote system at least the address (HOST) must be specified. Accompanied by the port and / or user name, if necessary. The password (if needed) has to be defined once with the command 'set password <password>'. For MODE parameter are 'telnet', 'ssh' and 'local' only allowed. 'local' does not require any other parameters and can also be omitted.
For SSH login with password, 'sshpass' must be installed (note: not recommended! Use public key authentication instead). For SSH login to work, a manual SSH connection to the remote machine from the FHEM-Acount may need to be done once (under whose rights FHEM runs) the fingerprint must be confirmed.

Readings:


• cpu_core_count
  CPU core count
• cpu_model_name
  CPU model name
• cpu_bogomips
  CPU Speed: BogoMIPS
• cpu_freq (and cpu1_freq for dual core systems)
  CPU frequency


• cpu_temp
  CPU temperature


• cpu_temp_avg
  Average of the CPU temperature, formed over the last 4 values.


• fhemuptime
  Time (in seconds) since the start of FHEM server.


• fhemuptime_text
  Time since the start of the FHEM server: human-readable output (text representation).


• fhemstarttime
  Start time (in seconds since 1.1.1970 1:00:00) of FHEM server.


• fhemstarttime_text
  Start time of the FHEM server: human-readable output (text representation).


• idletime
  Time spent by the system since the start in the idle mode (period of inactivity).


• idletime_text
  The inactivity time of the system since system start in human readable form.


• loadavg
  System load (load average): 1 minute, 5 minutes and 15 minutes.


• ram
  memory usage.


• swap
  swap usage.


• uptime
  System uptime.


• uptime_text
  System uptime (human readable).


• starttime
  System starttime.


• starttime_text
  System starttime (human readable).


• Network statistics
  Statistics for the specified network interface about the data volumes transferred and the difference since the previous measurement.
  Examples:
  Amount of the transmitted data via interface eth0.
  eth0: RX: 940.58 MB, TX: 736.19 MB, Total: 1676.77 MB
  Change of the amount of the transferred data in relation to the previous call (for eth0).
  eth0_diff: RX: 0.66 MB, TX: 0.06 MB, Total: 0.72 MB
  IP and IP v6 adresses eth0_ip 192.168.0.15
eth0_ip6 fe85::49:4ff:fe85:f885/64
  


• Network Speed (if avialable)
  speed of the network connection.
  Examples:
  eth0_speed 100
  


• File system information
  Usage of the desired file systems.
  Example:
  fs_root: Total: 7340 MB, Used: 3573 MB, 52 %, Available: 3425 MB at /


• CPU utilization
  Information about the utilization of CPUs.
  Example:
  stat_cpu: 10145283 0 2187286 90586051 542691 69393 400342
stat_cpu_diff: 2151 0 1239 2522 10 3 761
stat_cpu_percent: 4.82 0.00 1.81 93.11 0.05 0.00 0.20
stat_cpu_text: user: 32.17 %, nice: 0.00 %, sys: 18.53 %, idle: 37.72 %, io: 0.15 %, irq: 0.04 %, sirq: 11.38 %


• user defined
  These readings provide output of commands, which are passed to the operating system or delivered by user defined functions.

FritzBox specific Readings
• wlan_state
  WLAN state: on/off


• wlan_guest_state
  GuestWLAN state: on/off


• internet_ip
  current IP-Adresse


• internet_state
  state of the Internet connection: connected/disconnected


• night_time_ctrl
  state night time control (do not disturb): on/off


• num_new_messages
  Number of new Voice Mail messages


• fw_version_info
  Information on the installed firmware version: <VersionNum> <creation date> <time>

DSL Informations (FritzBox)
• dsl_rate
  Information about the down und up stream rate


• dsl_synctime
  sync time with DSLAM


• dsl_crc_15
  number of uncorrectable errors (CRC) for the last 15 minutes


• dsl_fec_15
  number of correctable errors (FEC) for the last 15 minutes

Power Supply Readings
• power_ac_stat
  status information to the AC socket: online (0|1), present (0|1), voltage, current
  Example:
  power_ac_stat: 1 1 4.807 264
  


• power_ac_text
  human readable status information to the AC socket
  Example:
  power_ac_text ac: present / online, voltage: 4.807 V, current: 264 mA
  


• power_usb_stat
  status information to the USB socket


• power_usb_text
  human readable status information to the USB socket


• power_battery_stat
  status information to the battery (if installed): online (0|1), present (0|1), voltage, current, actual capacity
  Example:
  power_battery_stat: 1 1 4.807 264 100
  


• power_battery_text
  human readable status information to the battery (if installed)


• power_battery_info
  human readable additional information to the battery (if installed): technology, capacity, status, health, total capacity
  Example:
  power_battery_info: battery info: Li-Ion , capacity: 100 %, status: Full , health: Good , total capacity: 2100 mAh
  The capacity must be defined in script.bin (e.g. ct-hdmi.bin). Parameter name pmu_battery_cap. Convert with bin2fex (bin2fex -> script.fex -> edit -> fex2bin -> script.bin).
  


• cpuX_freq_stat
  Frequency statistics for CPU X: minimum, maximum and average values
  Example:
  cpu0_freq_stat: 100 1000 900
  


• cpuX_idle_stat
  Idle statistik for CPU X: minimum, maximum and average values
  Example:
  cpu0_freq_stat: 23.76 94.74 90.75
  


• cpu[X]_temp_stat
  Temperature statistik for CPU: minimum, maximum and average values
  Example:
  cpu_temp_stat: 41.00 42.50 42.00
  


• ram_used_stat
  RAM usage statistics: minimum, maximum and average values
  Example:
  ram_used_stat: 267.55 1267.75 855.00
  


• swap_used_stat
  SWAP usage statistics: minimum, maximum and average values
  Example:
  swap_used_stat: 0 1024.00 250.00
  




Get:


• interval_base
  Lists the specified polling intervalls.


• interval_multipliers
  Displays update intervals.


• list
  Lists all readings.


• update
  Refreshs all readings.


• version
  Displays the version of SYSMON module.


• list_lan_devices
  Displays known LAN Devices (FritzBox only).



Set:


• interval_multipliers
  Defines update intervals (as in the definition of the device).


• clean
  Clears user-definable Readings. After an update (manual or automatic) new readings are generated.
  


• clear <reading name>
  Deletes the Reading entry with the given name. After an update this entry is possibly re-created (if defined). This mechanism allows the selective deleting unnecessary custom entries.
  


• password <Passwort>
  Specify the password for remote access (usually only necessary once).



Attributes:


• filesystems <reading name>[:<mountpoint>[:<comment>]],...
  Specifies the file system to be monitored (a comma-separated list).
  Reading-name is used in the display and logging, the mount point is the basis of the evaluation, comment is relevant to the HTML display (see SYSMON_ShowValuesHTML)
  Examples:
  /boot,/,/media/usb1
fs_boot:/boot,fs_root:/:Root,fs_usb1:/media/usb1:USB-Stick
  


• network-interfaces <name>[:<interface>[:<comment>]],...
  Comma-separated list of network interfaces that are to be monitored. Each entry consists of the Reading-name, the name of the Netwerk adapter and a comment for the HTML output (see SYSMON_ShowValuesHTML). If no colon is used, the value is used simultaneously as a Reading-name and interface name.
  Example ethernet:eth0:Ethernet,wlan:wlan0:WiFi
  


• user-defined <readingsName>:<Interval_Minutes>:<Comment>:<Cmd>,...
  This comma-separated list defines user defined Readings with the following data: Reading name, refresh interval (in minutes), a Comment, and operating system command.
  The os commands are executed according to the specified Intervals and are noted as Readings with the specified name. Comments are used for the HTML output (see SYSMON_ShowValuesHTML)..
  All parameter parts are required!
  It is important that the specified commands are executed quickly, because at this time the entire FHEM server is blocked!
  If results of the long-running operations required, these should be set up as a CRON job and store results as a text file.
  
  Example: Display of package updates for the operating system:
  cron-Job:
  sudo apt-get update 2>/dev/null >/dev/null apt-get upgrade --dry-run| perl -ne '/(\d*)\s[upgraded|aktualisiert]\D*(\d*)\D*install|^ \S+.*/ and print "$1 aktualisierte, $2 neue Pakete"' 2>/dev/null > /opt/fhem/data/updatestatus.txt
uder-defined attribute
  sys_updates:1440:System Aktualisierungen:cat /opt/fhem/data/updatestatus.txt
  the number of available updates is daily recorded as 'sys_updates'.


• user-fn <fn_name>:<interval_minutes>:<reading_name1>:<reading_name2>...[:<reading_nameX>], ...
  List of perl user subroutines.
  As <fn_name> can be used either the name of a Perl subroutine or a Perl expression. The perl function gets the device hash as parameter and must provide an array of values. These values are taken according to the parameter <reading_nameX> in Readings.
  A Perl expression must be enclosed in curly braces and can use the following parameters: $ HASH (device hash) and $ NAME (device name). Return is expected analogous to a Perl subroutine.
  Important! The separation between multiple user functions must be done with a comma AND a space! Within the function definition commas may not be followed by spaces.


• disable
  Possible values: 0 and 1. '1' means that the update is stopped.


• telnet-prompt-regx, telnet-login-prompt-regx
  RegExp to detect login and command line prompt. (Only for access via Telnet.)


• exclude
  Allows to suppress reading certain information.
  supported values: user-defined (s. user-defined und user-fn), cpucount, uptime, fhemuptime, loadavg, cputemp, cpufreq, cpuinfo, diskstat, cpustat, ramswap, filesystem, network, fbwlan, fbnightctrl, fbnewmessages, fbdecttemp, fbversion, fbdsl, powerinfo


• ssh-param
  Adds additional parameters to the SSH call as specified.



Plots:


predefined gplot files:

FileLog versions:
SM_RAM.gplot
SM_CPUTemp.gplot
SM_FS_root.gplot
SM_FS_usb1.gplot
SM_Load.gplot
SM_Network_eth0.gplot
SM_Network_eth0t.gplot
SM_Network_wlan0.gplot
SM_CPUStat.gplot
SM_CPUStatSum.gplot
SM_CPUStatTotal.gplot
SM_power_ac.gplot
SM_power_usb.gplot
SM_power_battery.gplot
DbLog versions:
SM_DB_all.gplot
SM_DB_CPUFreq.gplot
SM_DB_CPUTemp.gplot
SM_DB_Load.gplot
SM_DB_Network_eth0.gplot
SM_DB_RAM.gplot


HTML output method (see Weblink): SYSMON_ShowValuesHTML(<SYSMON-Instance>[,<Liste>])


The module provides a function that returns selected Readings as HTML.
As a parameter the name of the defined SYSMON device is expected.
It can also Reading Group, Clone dummy or other modules be used. Their readings are simple used for display.
The second parameter is optional and specifies a list of readings to be displayed in the format <ReadingName>[:<Comment>[:<Postfix>[:<FormatString>]]].
ReadingName is the Name of desired Reading, Comment is used as the display name and postfix is displayed after the value (such as units or as MHz can be displayed). If FormatString is specified, the output is formatted with sprintf (s. sprintf in Perl documentation).
If no Comment is specified, an internally predefined description is used.
If no list specified, a predefined selection is used (all values are displayed).

define sysv1 weblink htmlCode {SYSMON_ShowValuesHTML('sysmon')}
define sysv2 weblink htmlCode {SYSMON_ShowValuesHTML('sysmon', ('date:Datum', 'cpu_temp:CPU Temperatur: °C:%.1f'', 'cpu_freq:CPU Frequenz: MHz'))}

Text output method (see Weblink): SYSMON_ShowValuesHTMLTitled(<SYSMON-Instance>[,<Title>,<Liste>])


According to SYSMON_ShowValuesHTML, but with a Title text above. If no title provided, device alias will be used (if any)


Text output method (see Weblink): SYSMON_ShowValuesText(<SYSMON-Instance>[,<Liste>])


According to SYSMON_ShowValuesHTML, but formatted as plain text.


Text output method (see Weblink): SYSMON_ShowValuesTextTitled(<SYSMON-Instance>[,<Title>,<Liste>])


According to SYSMON_ShowValuesHTMLTitled, but formatted as plain text.


Reading values with perl: SYSMON_getValues(<name>[, <array of desired keys>])


Returns a hash ref with desired values. If no array is passed, all values are returned.
{(SYSMON_getValues("sysmon"))->{'cpu_temp'}}
{(SYSMON_getValues("sysmon",("cpu_freq","cpu_temp")))->{"cpu_temp"}}
{join(" ", values (SYSMON_getValues("sysmon")))}
{join(" ", values (SYSMON_getValues("sysmon",("cpu_freq","cpu_temp"))))}


Examples:


# Modul-Definition
define sysmon SYSMON 1 1 1 10
#attr sysmon event-on-update-reading cpu_temp,cpu_temp_avg,cpu_freq,eth0_diff,loadavg,ram,^~ /.*usb.*,~ /$
attr sysmon event-on-update-reading cpu_temp,cpu_temp_avg,cpu_freq,eth0_diff,loadavg,ram,fs_.*,stat_cpu_percent
attr sysmon filesystems fs_boot:/boot,fs_root:/:Root,fs_usb1:/media/usb1:USB-Stick
attr sysmon network-interfaces eth0:eth0:Ethernet,wlan0:wlan0:WiFi
attr sysmon group RPi
attr sysmon room 9.03_Tech

# Log
define FileLog_sysmon FileLog ./log/sysmon-%Y-%m.log sysmon
attr FileLog_sysmon group RPi
attr FileLog_sysmon logtype SM_CPUTemp:Plot,text
attr FileLog_sysmon room 9.03_Tech

# Visualisierung: CPU-Temperatur
define wl_sysmon_temp SVG FileLog_sysmon:SM_CPUTemp:CURRENT
attr wl_sysmon_temp group RPi
attr wl_sysmon_temp label "CPU Temperatur: Min $data{min2}, Max $data{max2}, Last $data{currval2}"
attr wl_sysmon_temp room 9.03_Tech

# Visualisierung: Netzwerk-Datenübertragung für eth0
define wl_sysmon_eth0 SVG FileLog_sysmon:SM_Network_eth0:CURRENT
attr wl_sysmon_eth0 group RPi
attr wl_sysmon_eth0 label "Netzwerk-Traffic eth0: $data{min1}, Max: $data{max1}, Aktuell: $data{currval1}"
attr wl_sysmon_eth0 room 9.03_Tech

# Visualisierung: Netzwerk-Datenübertragung für wlan0
define wl_sysmon_wlan0 SVG FileLog_sysmon:SM_Network_wlan0:CURRENT
attr wl_sysmon_wlan0 group RPi
attr wl_sysmon_wlan0 label "Netzwerk-Traffic wlan0: $data{min1}, Max: $data{max1}, Aktuell: $data{currval1}"
attr wl_sysmon_wlan0 room 9.03_Tech

# Visualisierung: CPU-Auslastung (load average)
define wl_sysmon_load SVG FileLog_sysmon:SM_Load:CURRENT
attr wl_sysmon_load group RPi
attr wl_sysmon_load label "Load Min: $data{min1}, Max: $data{max1}, Aktuell: $data{currval1}"
attr wl_sysmon_load room 9.03_Tech

# Visualisierung: RAM-Nutzung
define wl_sysmon_ram SVG FileLog_sysmon:SM_RAM:CURRENT
attr wl_sysmon_ram group RPi
attr wl_sysmon_ram label "RAM-Nutzung Total: $data{max1}, Min: $data{min2}, Max: $data{max2}, Aktuell: $data{currval2}"
attr wl_sysmon_ram room 9.03_Tech

# Visualisierung: Dateisystem: Root-Partition
define wl_sysmon_fs_root SVG FileLog_sysmon:SM_FS_root:CURRENT
attr wl_sysmon_fs_root group RPi
attr wl_sysmon_fs_root label "Root Partition Total: $data{max1}, Min: $data{min2}, Max: $data{max2}, Aktuell: $data{currval2}"
attr wl_sysmon_fs_root room 9.03_Tech

# Visualisierung: Dateisystem: USB-Stick
define wl_sysmon_fs_usb1 SVG FileLog_sysmon:SM_FS_usb1:CURRENT
attr wl_sysmon_fs_usb1 group RPi
attr wl_sysmon_fs_usb1 label "USB1 Total: $data{max1}, Min: $data{min2}, Max: $data{max2}, Aktuell: $data{currval2}"
attr wl_sysmon_fs_usb1 room 9.03_Tech

# Anzeige der Readings zum Einbinden in ein 'Raum'.
define SysValues weblink htmlCode {SYSMON_ShowValuesHTML('sysmon')}
attr SysValues group RPi
attr SysValues room 9.03_Tech

# Anzeige CPU Auslasung
define wl_sysmon_cpustat SVG FileLog_sysmon:SM_CPUStat:CURRENT
attr wl_sysmon_cpustat label "CPU(min/max): user:$data{min1}/$data{max1} nice:$data{min2}/$data{max2} sys:$data{min3}/$data{max3} idle:$data{min4}/$data{max4} io:$data{min5}/$data{max5} irq:$data{min6}/$data{max6} sirq:$data{min7}/$data{max7}"
attr wl_sysmon_cpustat group RPi
attr wl_sysmon_cpustat room 9.99_Test
attr wl_sysmon_cpustat plotsize 840,420
define wl_sysmon_cpustat_s SVG FileLog_sysmon:SM_CPUStatSum:CURRENT
attr wl_sysmon_cpustat_s label "CPU(min/max): user:$data{min1}/$data{max1} nice:$data{min2}/$data{max2} sys:$data{min3}/$data{max3} idle:$data{min4}/$data{max4} io:$data{min5}/$data{max5} irq:$data{min6}/$data{max6} sirq:$data{min7}/$data{max7}"
attr wl_sysmon_cpustat_s group RPi
attr wl_sysmon_cpustat_s room 9.99_Test
attr wl_sysmon_cpustat_s plotsize 840,420
define wl_sysmon_cpustatT SVG FileLog_sysmon:SM_CPUStatTotal:CURRENT
attr wl_sysmon_cpustatT label "CPU-Auslastung"
attr wl_sysmon_cpustatT group RPi
attr wl_sysmon_cpustatT plotsize 840,420
attr wl_sysmon_cpustatT room 9.99_Test

# Anzeige Stromversorgung AC
define wl_sysmon_power_ac SVG FileLog_sysmon:SM_power_ac:CURRENT
attr wl_sysmon_power_ac label "Stromversorgung (ac) Spannung: $data{min1} - $data{max1} V, Strom: $data{min2} - $data{max2} mA"
attr wl_sysmon_power_ac room Technik
attr wl_sysmon_power_ac group system
# Anzeige Stromversorgung Battery
define wl_sysmon_power_bat SVG FileLog_sysmon:SM_power_battery:CURRENT
attr wl_sysmon_power_bat label "Stromversorgung (bat) Spannung: $data{min1} - $data{max1} V, Strom: $data{min2} - $data{max2} mA"
attr wl_sysmon_power_bat room Technik
attr wl_sysmon_power_bat group system


SYSSTAT

[EN DE]

Provides system statistics for the host FHEM runs on or a remote Linux system that is reachable by preconfigured passwordless ssh access.

Notes:
• To monitor a target by snmp Net::SNMP hast to be installed.
  
• To plot the load values the following code can be used:

    define sysstatlog FileLog /usr/local/FHEM/var/log/sysstat-%Y-%m.log sysstat
    attr sysstatlog nrarchive 1
    define svg_sysstat SVG sysstatlog:sysstat:CURRENT
    attr wl_sysstat label "Load Min: $data{min1}, Max: $data{max1}, Aktuell: $data{currval1}"
    attr wl_sysstat room System
    

• to match the root filesystem (mount point '/') in diskusage plots use '#FileLog 4:/\x3a:0:' or '#FileLog 4:\s..\s:0:' and not '#FileLog 4:/:0:' as the later will match all mount points
.
Define
define <name> SYSSTAT [<interval> [<interval_fs>] [<host>]]

Defines a SYSSTAT device.

The load is updated every <interval> seconds. The default and minimum is 60.

The diskusage is updated every <interval_fs> seconds. The default is <interval>*60 and the minimum is 60. <interval_fs> is only aproximated and works best if <interval_fs> is an integral multiple of <interval>.

If <host> is given it has to be accessible by ssh without the need for a password. Examples:
define sysstat SYSSTAT
define sysstat SYSSTAT 300
define sysstat SYSSTAT 60 600


Readings
• load
  the 1 minute load average (for windows targets monitored by snmp aproximated value
• state
  the 1, 5 and 15 minute load averages (or windows targets monitored by snmp the per cpu utilization)
• user,system,idle,iowait
  respective percentage of systemutilization (linux targets only)
• <mountpoint>
  free bytes for <mountpoint>

Set
set <name> <value>

where value is one of


• raw <command>
  Sends <command> to the remote system by ssh.
  set <name> raw shutdown -h now

Get
get <name> <value>

where value is one of


• filesystems
  Lists the filesystems that can be monitored.

Attributes
• noSSH
  
• disable
  keep timers running but disable collection of statistics.
• filesystems
  List of comma separated filesystems (not mountpoints) that should be monitored.
  Examples:
  attr sysstat filesystems /dev/md0,/dev/md2
attr sysstat filesystems /dev/.*
attr sysstat filesystems 1,3,5
  
• disabledForIntervals HH:MM-HH:MM HH:MM-HH-MM...
• mibs
  space separated list of <mib>:<reding> pairs that sould be polled.
• readings
  Newline separated liste aus <reading>:<command> pairs should be executed.
  

  attr  readings processes:ps ax | wc -l\
                          temperature:snmpwalk -c public -v 1 10.0.1.21 .1.3.6.1.4.1.6574.1.2.0 | grep -oE ..$
  

• readingsFormat
  

  attr  readings temperature:cat /sys/class/thermal/thermal*/temp\
                          temperatures:cat /sys/class/thermal/thermal*/temp\
                          frequency:cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_cur_freq
  
  attr  readingsFormat { frequency => '{ $VALUE = [map {int($_ / 1000)} split("\n", $VALUE)] }',\
                          temperature => '{ $VALUE = [map {$_ / 1000} split("\n", $VALUE)] }',\
                          temperatures => '{ $VALUE =~ s/\n/ /g }' }
  

• showpercent
  If set the usage is shown in percent. If not set the remaining free space in bytes is shown.
• snmp
  1 -> use snmp to monitor load, uptime and filesystems (including physical and virtual memory)
• stat
  1 -> monitor user,system,idle and iowait percentage of system utilization (available only for linux targets)
• raspberrytemperature
  If set and > 0 the raspberry pi on chip termal sensor is read.
  If set to 2 a geometric average over the last 4 values is created.
• synologytemperature
  If set and > 0 the main temperaure of a synology diskstation is read. requires snmp.
  If set to 2 a geometric average over the last 4 values is created.
• raspberrycpufreq
  If set and > 0 the raspberry pi on chip termal sensor is read.
• uptime
  If set and > 0 the system uptime is read.
  If set to 2 the uptime is displayed in seconds.
• load
  If set and = 0 the system load is not read.
• useregex
  If set the entries of the filesystems list are treated as regex.
• ssh_user
  The username for ssh remote access.
• snmpVersion
• snmpCommunity
• readingFnAttributes

SamsungAV

[EN DE]

This module supports Samsung devices like TV or BD players.


Define
define <name> SamsungAV <host> <port> [DLNA]


(B|C|D Series) use port 52235 for screen messages: call, sms, date and volume change
(C|D|E|F Series) use port 55000 for RC commands
(H|J Series) use port 8000 for RC commands
(newest Series) use port 8001 for RC commands
(all Series)The device name of optional DLNA client might be defined to send full screen messages(OSD)
Example:
define Television SamsungAV 192.168.178.20 52235
define Television SamsungAV 192.168.178.20 55000
define Television SamsungAV 192.168.178.20 55000 DLNA_Client


Set
Port 52235 functionality: set <name> <command> [arguments]
where command is one of:

• mute
• volume
• call
• sms
• date
Example:
set Television mute on
set Television volume 20
set Television call Peter 012345678 Phone 87654321

RC functionality:
set <name> <RC command> [arguments]
Example:
set Television channelDown

Special commands:
caller/screen
send message(URI defined by attr callerURI/screenURI) via DLNA to device
Example:
set Television caller

sayText
TTS-function, if optional DLNA-device is defined
Example:
set Television sayText das ist ein test
see commandref of DLNA-device for further information.

0_macro
macro function
send several comma separated RC commands to device(each command will cause a pause of delayMacro microsec.)
set <name> 0_macro <RC command1> [,RC command2,RC command3....]
Example:
set Television 0_macro contents,right,right,,down,enter
some TVs need different delays between RC commands in a macro. You may solve this with usage of multiple commas.

0_text_line
sent text to device(migh be helpful to submit data used by interactive apps)
set <name> 0_text_line <TEXT>
Example:
set Television 0_text_line http://192.168.178.1:8083/fhem/btip/info.html

0_App_start Netflix/YouTube (0_App_status Netflix/YouTube)
start app on TV (get status of app)

Get

N/A


Attributes

• callerURI: path to an URI of a media(jpg,mp3...)to be displayed on screen main purpose: URI to be displayed on screen if a phone call comes in


• screenURI: path to an URI of a media(jpg,mp3...)to be displayed on screen every other purpose than a phone call as event


• delayRC: delay in microsec. default=0 some TV's need a delay before transmition of a RC command. be careful: attribute causes system freezes


• delayMacro: delay in microsec. default=300000 most TV's need a delay between each RC command in macro function. be careful: attribute causes system freezes


• disable: 0/1: enables/disables device

Schellenberg

[EN DE]

Schellenberg USB RF Dongle.

Define
define <name> Schellenberg </dev/serial/by-id/usb-schellenberg_ENAS_000000000000-if00>

defines the device and set the port

Set
• pair
  set <name> pair <seconds>
  
  enable pair mode for seconds

SchellenbergHandle

[EN DE]

Schellenberg RF Alarm Door Handle.

Define
define <name> SchellenbergHandle <ID>

The device should be installed via autocreate.
• Install a Schellenberg USB dongle and the associated device (Schellenberg)
• Activate pair seconds there
• Pair the door handle as described in the manual (handle up, left switch)

Get
• readingFnAttributes

ShareMaster

[EN DE]

(en | de)

Display of share values in a depot
Define
define Depot ShareMaster


Notes:
• The <Symbol> for a particular share depends very much on the source!
• This module uses the global attribute language to determine its output data
  (default: EN=english). For German output set attr global language DE.
Set
• set <name> clearReadings
  Clear all readings.
  
  
• set <name> update
  Refresh all readings.
  
  
Attributes
• depotCurrency
  The total depot value will be shown in this currency, also the buy values in the stocks attribute are given in this currency
  Default: EUR
  
  
• categories
  Comma separated list of categories in this depot, e.g. type of share or industrial segment
• pollInterval
  Refresh interval in seconds.
  Standard: 300, valid values: Number
  
  

Shares

[EN DE]

(en | de)

Acquire and display share values
Define
define Depot Shares


Notes:
• This FHEM module uses the Perl module Finance::Quote, which acquires share data from different sources (see attribute sources). Since the suppliers of data change their policies from time to time, it may occur that from one day to the next no data is available. Therefore this FHEM module implements a flexible approach that allows to change the default data source for all shares with a single attribute altSymbol.
• The <Symbol> for a particular share depends very much on the source! Therefore, each share can be represented by a '|'-separated list of symbols, example: The well known NASDAQ ETF is represented by NADQ.DE|LU2197908721|..., where the first symbol is used by Yahoo, the second symbol is the ISIN used by Deutsche Börse etc. See attributes defaultSource, altSymbol, stocks.
• This module uses the global attribute language to determine its output data
  (default: EN=english). For German output set attr global language DE.
• This module needs the package Finance::Quote. Install with cpan Finance::Quote or sudo apt-get install libfinance-quote-perl
  
  
Set
• set <name> buy <Symbol> <Count> <Value in depotCurrency>
  Buy some shares. If this particular share already exists, new values will be added to old values.
  
  
• set <name> sell <Symbol> <Count> <Value in depotCurrency>
  Sell some shares
  
  
• set <name> add <Symbol>
  Watch this share
  
  
• set <name> remove <Symbol>
  Remove share from watch list
  
  
• set <name> clearReadings
  Clear all readings.
  
  
• set <name> update
  Refresh all readings.
  
  
Get
• get <name> sources
  Lists all avaialble data sources.
  
  
• get <name> currencies
  Lists all available currencies.
  
  
Attributes
• shareCurrency
  Individual shares will be shown in this currency.
  Format: [:]
  Default: EUR:€
  
  
• depotCurrency
  The total depot value will be shown in this currency, also the buy values in the stocks attribute are given in this currency
  Format: [:]
  Default: EUR:€
  
  
• queryTimeout
  Fetching timeout in seconds.
  Standard: 120, valid values: Number
  
  
• pollInterval
  Refresh interval in seconds.
  Standard: 300, valid values: Number
  
  
• defaultSource
  '|'-separated list of default sources for share values. See altSymbol attribute
  Default: yahoo_json (single source), valid values: from get <name> sources
  
  
• sources
  An individual data source can be set for every single symbol.
  Data sources can be fetched with: get <name> sources.
  Format: <Symbol>:<Source>[,<Symbol>:<Source>...]
  Shares not listed in sources will be updated from defaultSource.
  
  
• sourcesLinks
  An individual link to obtain details and graphical data can be set for every source.
  The string $SYMBOL in each link will be replaced by the symbol for a share.
  Format: <Source>:<Link>[,<Source>:<Link>...]
  Example: yahoo_json:de.finance.yahoo.com/quote/$SYMBOL
  
  
• arroWs
  Comma-separated list of arrow symbols (in HTML-Format) for denoting change in stock value, boundary values are >1%,1%,0%,-1%,<-1% Default: "🢁,🢅,🢂,🢆,🢃"
• colors
  Comma-separated list of color specs (in HTML-Format) for coloring change in stock value, boundary values are >1%,1%,0%,-1%,<-1% Default: "green,seagreen,black,orangered,red"
• headercolor
  color spec (in HTML-Format) for coloring the header line in a depot table. Default #aaaaff;
• altSymbol
  Numerical value, the index for the list of symbols representing each share in the stocks attribute. The default value for the altSymbol is 0, which means that the first symbol is used for querying Finance::Quote. A value of 1 means to use the second symbol, etc.
• stocks
  Will be created/modified via buy/sell/add/remove
  Contains share informations in the format: <Symbol0[|Symbol1|...]>:<Number>:<Buy value in depotCurrency>:<Category>
  
  

Shelly

[EN DE]

FHEM module to communicate with a Shelly switch/roller actuator/dimmer/RGBW controller or energy meter

Define

define <name> Shelly <IP address>[:port] [[user:]password]
Defines the Shelly device.

Notes:
• This module needs the packages JSON and HttpUtils
• In Shelly button, switch, roller or dimmer devices one may set URL values that are "hit" when the input or output status changes. This is useful to transmit status changes arising from locally pressed buttons directly to FHEM by setting
  • Button switched ON url: http://<FHEM IP address>:<Port>/fhem?cmd=get%20<Devicename>%20status
  If one wants to detach the button from the output, one may generate an additional reading button by setting in the Shelly
  • For Button switched ON url: http://<FHEM IP address>:<Port>/fhem?cmd=set%20<Devicename>%20button_on%20[<channel>]
  • For Button switched OFF url: http://<FHEM IP address>:<Port>/fhem?cmd=set%20<Devicename>%20button_off%20[<channel>]
  Attention: Of course, a csrfToken must be included as well - or a proper allowed device declared.
• The attribute model is set automatically. For shelly devices that are not supported by the device, the attribute is set to generic. If the model attribute is set to generic, the device does not contain any actors, it is just a placeholder for arbitrary sensors

Set

For all Shelly devices
• set <name> name <ShellyName>
  name of the Shelly device. If the Shelly is not named, its name will set to the name of the Fhem-device. ShellyName may contain space characters.
Note: Empty strings are not accepted, deletion of Shellies name on its website will result in remaining it to the modules name
• Gen1: set <name> config <registername> <value> [<channel>]
  set the value of a configuration register (Gen1 devices only)
  Gen2: set <name> config <command>
  ap_enable|ap_disable change the access point
• set <name> interval <integer>
  Temporarely set the update interval. Will be overwritten by the attribute on restart. A value of -1 set the interval to the default given by attribute, a value of 0 disables the automatic update.
• set <name> password <password>
  This is the only way to set the password for the Shelly web interface.
For Shelly devices first gen, the attribute 'shellyuser' must be defined To remove a password, use: set <name> password
• set <name> reboot
  Reboot the Shelly
• set <name> clear <reading>
  Clearing the reading
• set <name> update
  Update the Shelly to the latest stable version

For Shelly switching devices (model=shelly1|shelly1pm|shellyuni|shelly4|shellypro4pm|shellyplug|shellyem|shelly3em or (model=shelly2/2.5/plus2/pro2 and mode=relay))
• set <name> on|off|toggle [<channel>]
  switches channel <channel> on or off. Channel numbers are 0 and 1 for model=shelly2/2.5/plus2/pro2, 0..3 for model=shelly4. If the channel parameter is omitted, the module will switch the channel defined in the defchannel attribute.
• set <name> on-for-timer|off-for-timer <time> [<channel>]
  switches <channel> on or off for <time> seconds. Channel numbers are 0 and 1 for model=shelly2/2.5/plus2/pro2 or model=shellyuni, and 0..3 model=shelly4/pro4. If the channel parameter is omitted, the module will switch the channel defined in the defchannel attribute.
• set <name> xtrachannels
  create readingsProxy devices for switching devices with more than one channel

For Shelly roller blind devices (model=shelly2/2.5/plus2/pro2 and mode=roller)
• set <name> open|closed|stop [<duration>]
  drives the roller blind open, closed or to a stop. The commands open and closed take an optional parameter that determines the drive time in seconds
• set <name> pos <integer percent value>
  drives the roller blind to a partially closed position (normally 100=open, 0=closed, see attribute pct100). If the integer percent value carries a sign + or - the following number will be added to the current value of the position to acquire the target value.
  set <name> pct <integer percent value>
  same as set <name> pos <integer percent value>
• set <name> delta +|-<percentage>
  drives the roller blind a given percentage down or up. The moving direction depends on the attribute 'pct100'.
• set <name> zero
  calibration of roller device
• set <name> predefAttr
  sets predefined attributes: devStateIcon, cmdIcon, webCmd and eventMap
  Attribute 'pct100' must be set earlier
  Attributes are set only when not defined yet

For Shelly dimmer devices model=shellydimmer or (model=shellyrgbw and mode=white)
• set <name> on|off|toggle [<channel>]
  switches channel <channel> on or off. Channel numbers are 0..3 for model=shellyrgbw. If the channel parameter is omitted, the module will switch the channel defined in the defchannel attribute.
• set <name> on-for-timer|off-for-timer <time> [<channel>]
  switches <channel> on or off for <time> seconds. Channel numbers 0..3 for model=shellyrgbw. If the channel parameter is omitted, the module will switch the channel defined in the defchannel attribute.
• set <name> pct <0..100> [<channel>]
  percent value to set brightness value. Channel numbers 0..3 for model=shellyrgbw. If the channel parameter is omitted, the module will dim the channel defined in the defchannel attribute.

For Shelly RGBW devices (model=shellyrgbw and mode=color)
• set <name> on|off|toggle
  switches device <channel> on or off
• set <name> on-for-timer|off-for-timer <time>
  switches device on or off for <time> seconds.
• set <name> hsv <hue value 0..360>,<saturation value 0..1>,<brightness value 0..1>
  comma separated list of hue, saturation and value to set the color. Note, that 360° is the same hue as 0° = red. Hue values smaller than 1 will be treated as fraction of the full circle, e.g. 0.5 will give the same hue as 180°.
• set <name> gain <integer>
  number 0..100 to set the gain of the color channels
• set <name> effect <Off|0|1|2|3>
  activies an effect: 1=Meteor Shower 2=Gradual Change 3=Flash
• set <name> rgb <rrggbb>
  6-digit hex string to set the color
• set <name> rgbw <rrggbbww>
  8-digit hex string to set the color and white value
• set <name> white <integer>
  number 0..100 to set the white value

Get

• get <name> actions
  prints a list of the actions on the screen

Note: due to better readability, %20 will be represented by the blank symbol ␣
• get <name> config [<registername>] [<channel>]
  get the value of a configuration register and writes it in reading config. If the register name is omitted, only general data like e.g. the SHELLYID are fetched.
• get <name> registers
  displays the names of the configuration registers for this device
• get <name> status
  returns the current status of the device.
• get <name> settings
  returns the current settings of the device.
• get <name> model
  get the type of the Shelly
• get <name> readingsGroup Device|Firmware|Network|Status
  create a readingsGroup device to get a thematic summary of all Shellies
• get <name> version
  display the version of the module

Attributes

• attr <name> name <ShellyName>
  name of the Shelly device. If the Shelly is not named, its name will set to the name of the Fhem-device. ShellyName may contain space characters.
Note: Empty strings are not accepted, deletion of Shellies name on its website will result in remaining it to the modules name
• attr <name> shellyuser <shellyuser>
  username for addressing the Shelly web interface. Set the password with the set command.
Applicable only for Shellies first gen.
• attr <name> model <model>
  type of the Shelly device. If the model attribute is set to generic, the device does not contain any actors, it is just a placeholder for arbitrary sensors. Note: this attribute is determined automatically.
• attr <name> mode relay|roller (only for model=shelly2/2.5/plus2/pro2)
  attr <name> mode white|color (only for model=shellyrgbw)
  type of the Shelly device
• attr <name> interval <interval>
  Update interval for reading in seconds. The default is 60 seconds, a value of 0 disables the automatic update.
  
  Note: The ShellyPro3EM energy meter is working with a set of two intervals: The power values are read at the main interval (as set by the attribute value), the energy values and calculated power values are read at a multiple of 60 seconds. When setting the main interval, the value is adjusted to match an integer divider of 60.
• attr <name> maxAge <seconds>
  Maximum age of readings in seconds. The default is 2160000 seconds = 600 hours, minimum value is 'interval'.
  
• attr <name> showinputs show|hide
  Add the state of the input buttons and their mode to the readings. The default value is show. Most comfortable when triggered by actions/webhooks from the device.
• attr <name> showunits none|original|normal|normal2|ISO
  Add the units to the readings. The default value is none (no units). The energy unit can be selected between Wh, kWh, kJ.
  • none: recommended to get results consistend with ShellyMonitor
  • original: the units are as given by the shelly device (eg Wm (Watt-Minutes) for most of first generation devices)
  • normal: energy will be calculated to Wh (Watt-Hours)
  • normal2: energy will be calculated to kWh (Kilo-Watt-Hours)
  • ISO: energy will be calculated to kJ (Kilo-Joule)
• attr <name> maxpower <maxpower>
  Max power protection in watts. The default value and its range is predetermined by the shelly device.
• attr <name> timeout <timeout>
  Timeout in seconds for HttpUtils_NonblockingGet. The default is 4 seconds. Careful: Use this attribute only if you get 'connect to ... timed out' errors in your log.
• attr <name> webhook none|<FHEMWEB-device> (default:none)
  create a set of webhooks on the shelly device which send a status request to fhem (only 2nd gen devices).
  If a csrf token is set on the FHEMWEB device, this is taken into account. The tokens are checked regulary and will be updated on the shelly.
  The names of the webhooks in the shelly device are based on the names of shellies events, with an preceding and trailing underscore (eg _COVER.STOPPED_).
  If the attribute is set to none, these webhooks (with a trailing underscore) will be deleted.
Webhooks that point to another IP address are ignored by this mechanism.
Note: When deleting a fhem device, remove associated webhooks on the Shelly before with attr <name> webhook none or deleteattr <name> webhook

For Shelly switching devices (mode=relay for model=shelly2/2.5/plus2/pro2, standard for all other switching models)
• attr <name> defchannel <integer>
  only for multi-channel switches eg model=shelly2|shelly2.5|shelly4 or shellyrgbw in white mode: Which channel will be switched, if a command is received without channel number

For Shelly roller blind devices (mode=roller for model=shelly2/2.5/plus2/pro2)
• attr <name> maxtime <int|float>
  time needed (in seconds) for a complete drive upward or downward
• attr <name> maxtime_close <int> Gen1
  attr <name> maxtime_close <float> Gen2
  time needed (in seconds) for a complete drive downward
• attr <name> maxtime_open <int> Gen1
  attr <name> maxtime_open <float> Gen2
  time needed (in seconds) for a complete drive upward
• attr <name> pct100 open|closed (default:open)
  roller or blind devices only: is pct=100 open or closed ?

For energy meter ShellyPro3EM
• attr <name> Energymeter_P <float>
  calibrate to the suppliers meter-device for meters with backstop functionality or for the purchase meter if two meters or a bidirectional meter are installed
  value(s) added to Shellies value(s) to represent the suppliers meter value(s), in Wh (Watthours).
  Note: the stored attribute value is reduced by the actual value
• attr <name> Energymeter_R <float>
  calibrate returned energy to the second suppliers meter-device (Bidirectional meters only)
  value(s) added to Shellies value(s) to represent the suppliers meter value(s), in Wh (Watthours).
  Note: the stored attribute value is reduced by the actual value
• attr <name> Energymeter_F <float>
  calibrate to the suppliers meter-device for Ferraris-type meters
  value(s) added to Shellies value(s) to represent the suppliers meter value(s), in Wh (Watthours).
  Note: the stored attribute value is reduced by the actual value
• attr <name> EMchannels ABC_|L123_|_ABC|_L123 (default: _ABC)
  used to attach prefixes or postfixes to the names of the power and energy readings
  Caution: deleting or change of this attribute will remove relevant readings!
• attr <name> Periods <periodes>
  comma separated list of periodes to calculate energy differences
  hourQ: a quarter of an hour
  hourT: a twelth of an hour (5 minutes)
  dayQ: a quarter of a day
  dayT: a third of a day (8 hours), starting at 06:00
  Caution: when removing an entry from this list or when deleting this attribute, all relevant readings are deleted!
• attr <name> PeriodsCorr-F <0.90 ... 1.10>
  a float number as correction factor for the energy differences for the periods given by the attribute "Periods"

Standard attributes
• alias, comment, event-on-update-reading, event-on-change-reading, room, eventMap, verbose, webCmd

Readings/Generated events

(selection)

Webhooks (2nd gen devices only)

• webhook_cnt active / controlled / total
  number of webhooks stored in the shelly
• webhook_ver
  latest revision number of shellies webhooks

ShellyPlus and ShellyPro devices

• indicating the configuration of Shellies hardware inputs
  input_<channel>_mode
  ShellyPlus/Pro2PM in relay mode:
  button|switch straight|inverted follow|detached
  ShellyPlus/Pro2PM in roller mode:
  button|switch straight|inverted single|dual|detached normal|swapped
  ShellyPlusI4:
  button|switch straight|inverted
  • button input type: button attached to the Shelly
  • switch input type: switch attached to the Shelly
  • straight the input is not inverted
  • inverted the input is inverted
  • single control button mode: the roller is controlled by one input *
  • dual control button mode: the roller is controlled by two inputs *
  • follow control button mode: the relay is controlled by the input **
  • detached control button mode: the input is detached from the relay|roller
  • normal the inputs are not swapped *
  • swapped the inputs are swapped *
  
  * roller mode only ** relay mode only
  
• indicating the reason for start or stop of the roller
  start_reason, stop_reason
  • button button or switch attached to the Shelly
  • http HTTP/URL eg Fhem
  • HTTP Shelly-App
  • loopback Shelly-App timer
  • limit_switch roller reaches upper or lower end
  • timeout after given drive time (eg fhem)
  • WS_in Websocket
  • obstruction Obstruction detection
  • overpower
  • overvoltage
  • overcurrent

ShellyPlusI4

an input in mode 'button' has usually the state 'unknown'. When activated, the input state is set to 'ON' for a short periode, independent from activation time. The activation time and sequence is reprensented by the readings input_<ch>_action and input_<ch>_actionS, which will act simultanously with following values:
• S single_push
• SS double_push
• SSS triple_push
• L long_push
NOTE: the readings of an input in mode 'button' cannot actualized by polling. It is necessary to set actions/webhooks on the Shelly!

Webhooks on ShellyPlusI4
Webhooks generated by Fhem are named as follows:
Input mode 'switch'
• _INPUT.TOGGLE_ON_
• _INPUT.TOGGLE_OFF_

Input mode 'button'
• _INPUT.BUTTON_PUSH_
• _INPUT.BUTTON_DOUBLEPUSH_
• _INPUT.BUTTON_TRIPLEPUSH_
• _INPUT.BUTTON_LONGPUSH_

ShellyPro3EM

Power

Power, Voltage, Current and Power-Factor are updated at the main interval, unless otherwise specified
• Active Power
  Active_Power_<A|B|C|T>
  float values of the actual active power
• Calculated Active Power
  Active_Power_calculated
  float value, calculated from the difference of Shellies Total_Energy reading (updated each minute, or multiple)
• Integrated Active Power
  Active_Power_integrated
  float value, calculated from the integration of Shellies power readings (updated each minute, or multiple)
• Pushed Power
  Active_Power_pushed_<A|B|C|T>
  float values of the actual power pushed by the Shelly when the value of a phase differs at least 10% to the previous sent value (update interval depends on load, possible minimum is 1 second) Action on power-events on the Shelly must be enabled.
• Apparent Power
  Apparent_Power_<A|B|C|T>
  float values of the actual apparent power
• Voltage, Current and Power-Factor
  Voltage_<A|B|C>
Current_<A|B|C|T>
Power_Factor_<A|B|C>
  float values of the actual voltage, current and power factor

Energy

Energy readings are updated each minute, or multiple.
When the showunits attribute is set, the associated units (Wh, kWh, kJ) are appended to the values
• Active Energy
  Purchased_Energy_<A|B|C|T>
Returned_Energy_<A|B|C|T>
  float values of the purchased or returned energy per phase and total
• Total Active Energy
  Total_Energy
  float value of total purchased energy minus total returned energy
  A minus sign is indicating returned energy.
  The timestamp of the reading is set to the full minute, as this is Shellies time base. Day and Week are based on GMT.
• Energymeter
  Total_Energymeter_<F|P|R>
  float values of the purchased (P) or returned (R) energy displayed by the suppliers meter. For Ferraris type meters (F), the returned energy is subtracted from the purchased energy
• Energy differences in a period of time
  [measuredEnergy]_<Min|QHour|Hour|Qday|TDay|Day|Week>
  float value of energy in a period of time (updated at the defined time interval).
  QDay is a period of 6 hours, starting at 00:00.
  TDay is a period of 8 hours, starting at 06:00.
  Week is a period of 7 days, starting mondays at 00:00.

ShellyMonitor

[EN DE]

This module is for Shelly-devices, that report their data in the CoIoT-"standard" (based on COAP). Defined devices are updated in their readings, non-defined devices found are displayed in FHEMWEB in a table, where they might be created with a click.



Requirements

ShellyMonitor needs two additional Perl modules:
• JSON
  For Raspian Buster by sudo apt-get install libjson-perl installable, or by sudo cpan install JSON
• IO::Socket::Multicast
  For Raspian Buster by sudo apt-get install libio-socket-multicast-perl installable, or with sudo cpan install IO::Socket::Multicast

Define

define <name> ShellyMonitor [interface]

<interface> is necessary if the computers primary interface is not the one with the multicast messages. E.g., it might be "wlan0".


Set

• set <name> autocreate [<ip regexp>]
  Setting this command triggers the creation of all discovered, but not yet defined devices that have an IP address matching to pattern. Without a pattern, all devices are created.
  Creation implies:
  • a define via the autocreate module mechanism with the systematic name displayed in the WEB table
  • setting the model attribute for the device
  • setting the mode attribute if applicable
  • setting the webCmd attribute if applicable
• set <name> create <ip address> [<device name>]
  The device specified by its IP address is created with the optionally given device name. Unlike autocreate, a direct define is executed, and the features of the autocreate module (FileLog-device, room-attribute) are not assigned.
  The other attributes described for the autocreate-set command are assigned.

Attributes

• ignoreDevices
  Regular expression for Shelly device (names) that shall be ignored. E.g., setting this to ".*" will not update any devices

Signalbot

For German documentation see Wiki

provides an interface to the Signal Messenger, via signal_cli running as dbus daemon
The signal_cli package needs to be installed. See github for installation details on signal-cli
An install script is available in the FHEM forum


Supported functionality:

• Send messages to individuals and/or groups with or without attachments
• Work with contacts and groups using real names instead of internal codes and numbers
• Group and contact names can contain space - surround them with quotes to use them in set commands
• Creaet, join and leave and administrate groups
• Register and link multiple devices and switch between them

Define

define <name> Signalbot [phonenumber]
The optional argument phonenumber will try to use an existing registration for this number if already present.
Note: To use multiple accounts (numbers) the signal-cli daemon needs to be started without the -u argument.

Set

• set send [@<Recipient1> ... @<RecipientN>] [#<GroupId1> ... #<GroupIdN>] [&<Attachment1> ... &<AttachmentN>] [<Text>]
  Send a message to a Signal recipient using @Name or @+49xxx as well as groups with #Group or #@Group along with an attachment with & and a message.
• Use round brackets to let FHEM execute the content (e.g &({plotAsPng('SVG_Temperatures')}
• If a recipient, group or attachment contains white spaces, the whole expression (including @ # or &) needs to be put in double quotes. Escape quotes within with \"
• If the round brackets contain curly brackets to execute Perl commands, two semi-colons (;;) need to be used to seperate multiple commands and at the end. The return value will be used e.g. as recipient
• For compatibility reasons @# can also be used to mark group names
• Messages to multiple recipients will be sent as one message
• Messages to multiple groups or mixed with individual recipients will be sent in multiple messages
• Attachments need to be file names readable for the fhem user with absolute path or relative to fhem user home
• Recipients can be either contact names or phone numbers (starting with +). Since signal-cli only understand phone numbers, Signalbot tries to translate known contact names from its cache and might fail to send the message if unable to decode the contact


• To send multi line messages, use "\\n" in the message text

Example:
set Signalbot send "@({my $var=\"Joerg\";; return $var;;})" #FHEM "&( {plotAsPng('SVG_Temperatures')} )" Here come the current temperature plot


• set reply ....
  Send message to previous sender. For detailed syntax, see "set send"
  If no recipient is given, sends the message back to the sender of the last received message. If the message came from a group (reading "msgGroupName" is set), the reply will go to the group, else the individual sender (reading "msgSender") is used.
  Note: You should only use this from a NOTIFY or DOIF that was triggered by an incoming message otherwise you risk using the wrong recipient.
  
• set setContact <number> <name>
  Define a nickname for a phone number to be used with the send command and in readings
  
• set block #<groupname>|<contact>
  Put a group or contact on the blocked list (at the server) so you won't receive messages anymore. While the attribute "allowedPeer" is handled on FHEM level and messages are still received (but ignored), FHEM will not receive messages anymore for blocked communication partners
  
• set unblock #<groupname>|<contact>
  Reverses the effect of "block", re-enabling the communication.
  
• set createGroup <groupname> [&<group picture>]
  Define a new Signal group with the specified name.
  Note: Pictures >2MB are known to cause issues and are blocked.
  
• set updateGroup <groupname> #[<new groupname>] [&<group picture>]
  Update the name and/or group picture for an existing group.
  Note: Pictures >2MB are known to cause issues and are blocked.
  
• set invite <groupname> <contact>
  Invite new members to an existing group. You can add multiple contacts separated by space.
  
• set joinGroup <group link>
  Join a group via an invitation group like (starting with https://signal.group/....). This link can be sent from the group properties with the "group link" function.
  Easiest way is to share via Signal and set the "autoJoin" attribute which be recognized by Signalbot to automatically join.
  
• set quitGroup <groupname>
  Quit from a joined group. This only sets the membership to inactive, but does not delete the group (see "get groups")"
  
• set updateProfile <new name> [&<avatar picture>]
  Set the name of the FHEM Signal user as well as an optional avatar picture.
  
• set signalAccount <number>
  Switch to a different already existing and registered account. When signal-cli runs in multi mode, the available numbers will be pre-filled as dropdown or can be updated by doing a "reinit".
  
• set register <number>
  Start the registration wizard which will guide you through the registration of a new account including Captcha and Verification Code - just follow the instructions on the screen.
  Remember to set the attribute registerMethod to "Voice" if you want to receive a voice call with the verification code instead of a SMS.
  
• set captcha signalcaptcha://<captcha string>
  Typically registration requires you to solve a captcha to protect spam to phone numbers. The registration wizard will typically guide you through the process.
  If the captcha is accepted use "set verify" to enter the verification code and finish registration.
  
• set verify <verification code>
  Last step in the registration process. Use this command to provide the verifcation code you got via SMS or voice call.
  If this step is finished successfully, Signalbot is ready to be used.
  
• set link <my name>
  Alternative to registration: Link your Signal Messenger used with your smartphone to FHEM. A qr-code will be displayed that you can scan with your phone under settings->linked devices.
  Use the optional name to identify your instance - if empty "FHEM" is used.
  Note: This is not the preferred method, since FHEM will receive all the messages you get on your phone which can cause unexpected results.
  
• set reinit
  Re-Initialize the module. For testing purposes when module stops receiving, has other issues or has been updated. Should not be necessary.
  
• set addDevice <device URI>
  Add another Signal instance as linked device. Typically the URI is presented as QR-Code though other Signalbot instances will display them as text when using the "set link" function. It starts with "sgnl://linkdevice..."
  
• set removeDevice <deviceID>
  Remove a linked device that was added to this instance with "addDevice". The deviceID can be retrieved with "get devices". If only one device is linked the id would typically be "2" as "1" is the main device.
  You can only remove a device from the main device, otherwise you will get an authorization failed error.
  
• set group <group command> <groupname> <argument>
  Combined command for group related functions:
  • addMembers,removeMembers,addAdmins,removeAdmins <groupname> <contact(s)> : Modify the member or admin list for the group
  • invite <groupname> <contact(s)> : Same as addMembers
  • create <groupname> [<contact(s)>]: create a new group and optionally define members
  • block/unblock <groupname> : block/unblock receiving messages from a specific group
  • quit <groupname> : Leave a group
  • join <group link> : Join a group with a group link.
  • delete <groupname> : Delete a group from local repository (you should first leave it)
  • update <groupname> <new groupname> [&<avatar picture>] : Set a new name and/or picture for the group
• set contact <contact command> <contact> <argument>
  Combined command for contact related functions:
  • add <contact> <nickname> : Define a local name for a contact
  • delete <contact> : Remove contact from local repository
  • block/unblock <contact> : block/unblock receiving messages from contact
• set trust <number|all>
  Set the unverified trust for a number. Specifying all will set it for all known contacts
  
• set trustVerified <number> <safetynumber>
  Set the verified trust for a number. You can get the safetynumber via "get identityDetails" though the safest way is to ask your contact to send you the number via a safe channel and use that one.
  

Get

• get contacts all|nonblocked
  Shows an overview of all known numbers and contacts along with their blocked status. If "nonblocked" is chosen the list will not containt blocked contacts.
  
• get groups all|active|nonblocked
  Shows an overview of all known groups along with their active and blocked status as well as the list of group members.
  Using the "active" option, all non-active groups (those you quit) are hidden, with "nonblocked" additionally the blocked ones get hidden.
  
• get accounts
  Lists all accounts (phone numbers) registered on this computer.
  Use register or link to create new accounts.
  
• get favorites
  Lists the defined favorites in the attribute "favorites" in a readable format
  
• get devices
  Lists the defined devices linked to this devices. The ID "1" typically is this device and if no devices are linked this will be the only entry shown.
  
• get helpUnicode
  Opens a cheat sheet for all supported replacements to format text or add emoticons using html-like tags or markdown.
  Note: This functionality needs to be enabled using the "formatting" attribute.
  
• get groupProperties <group>
  Shows all known properties of the given group, like members, admins and permissions.
• get identityDetails <contact>
  Shows all known details of a contacts identity.
  This includes the safetynumber for verification purposes.

Attributes

• registerMethod
  The number of seconds after which a user authentificated for command access stays authentifcated.
  Default: 300, valid values: decimal number
  
• authDev
  Name of GoogleAuth device. Will normally be automatically filled when setting an authTimeout or cmdKeyword if a GoogleAuth device is already existing.
  
• authTrusted yes|no
  Do not require GoogleAuth for TRUSTED_VERIFIED contacts (see "set trustedVerified") if set to "yes".
  
• autoJoin no|yes
  If set to yes, Signalbot will automatically inspect incoming messages for group invite links and join that group.
  Default: no, valid values: no|yes
  
• allowedPeer
  Comma separated list of recipient(s) and/or groupId(s), allowed to update the msg.* readings and trigger new events when receiving a new message.
  If the attribute is not defined, everyone is able to trigger new events!!
• babblePeer
  Comma separated list of recipient(s) and/or groupId(s) that will trigger that messages are forwarded to a Babble module defined by "babbleDev". This can be used to interpret real language interpretation of messages as a chatbot or to trigger FHEM events.
  If the attribute is not defined, nothing is sent to Babble
• babbleDev
  Name of Babble Device to be used. This will typically be automatically filled when bubblePeer is set.
  If the attribute is not defined, nothing is sent to Babble
• babbleExclude
  RegExp pattern that, when matched, will exclude messages to be processed by the Babble connection
  
• cmdKeyword
  One or more characters that mark a message as GoogleAuth protected command which is directly forwarded to FHEM for processing. Example: for "="
  =123456 set lamp off
  where "123456" is a GoogleAuth token. The command after the token is optional. After the authentification the user stay for "authTimeout" seconds authentificated and can execute command without token (e.g. "=set lamp on").
  If the attribute is not defined, no commands can be issued
• cmdFavorite
  One or more characters that mark a message as favorite in GoogleAuth mode.
  The favorite is either followed by a number or an alias as defined in the "favorite" attribute.
  Assuming cmdKeyword "=" and cmdFavorite "fav", "=fav 1" will execute the first favorite.
  Just sending "=fav" will list the available favorites.
  Note: The cmdFavorite will be checked before an actual command is interpreted. So "set" will be a bad idea since you won't be able to use any "set" command anymore.
• favorites
  Semicolon separated list of favorite definitions (see "cmdFavorite"). Favorites are identified either by their ID (defined by their order) or an optional alias in square brackets, preceding the command definition.
  
• Example: set lamp on;set lamp off;[lamp]set lamp on
  This defines 3 favorites numbered 1 to 3 where the third one can also be accessed with the alias "lamp".
  Using favorites you can define specific commands that can be executed without GoogleAuth by preceeding the command with a minus "-" sign.
  Example: -set lamp off;[lamp]-set lamp on;set door open
  Both favorites 1 and 2 (or "lamp") can be executed without authentification while facorite 3 requires to be authentificated.
  You should use "get favorites" to validate your list and identify the correct IDs since no syntax checking is done when setting the attribute.
  Multiple commands in one favorite need to be separeted by two semicolons ";;". For better readability you can add new lines anywhere - they are ignored (but spaces are not).
  Special commands:
  You can also embed Perl code with curly brackets: {my $var=ReadingsVal("sensor","temperature",0);; return $var;;}
  To just return a text and evaluate readings, you can use: print Temperature is [sensor:temperature]
  
• defaultPeer
  If send is used without a recipient, the message will send to this account or group(with #)
  
• formatting
  The "formatting" attribute has the following four options that allow highlighting in Unicode:
  • none - no replacements
  • html - replacements are enabled here with HTML-type tags (e.g. for bold <b> is bold </b>)
  • markdown - replacements are enabled by markdown-like tags (e.g. __for italic__) as well as emotics
  • both - both methods are possible here
  To learn about the syntax how to use tags and markdown, use the get helpUnicode method. You can still also simply copy&paste Unicode text from other sources.

Readings

• account
The currently active account (phone number) - "none" if current not registered to a number.

• (prev)msgAttachment
Attachment(s) of the last received (or for history reasons the previous before). The path points to the storage in signal-cli and can be used to retrieve the attachment.

• (prev)msgGroupName
Group of the last message (or for history reasons the previous before). Empty if last message was a private message

• (prev)msgSender
Sender that sent the last message (or previous before)

• (prev)msgText
Content of the last message

• (prev)msgTimestamp
Time the last message was sent (a bit redundant, since all readings have a timestamp anyway

• msgAuth
Set to 1 if the user was authentificated via GoogleAuth by the time the message arrived, 0 otherwise.

• sentMsg
Content of the last message that was sent from this module

• sentRecipient
Recipient of the last message that was sent
This is taken from the actual reply and will contain the last recipient that confirmed getting the message in case multiple recipients or group members got it

• sentMsgTimestamp
Timestamp the message was received by the recipient. Will show pending of not confirmed (likely only if even the Signal server did not get it)

• joinedGroups
Comma separated list of groups the registered number has joined. Inactive groups will be skipped, blocked groups appear in brackets.

SingleFileLog

[EN DE]

Define
define <name> SingleFileLog <filename> <regexp>

For each event or devicename:event matching the <regexp> create a new file <filename>
<filename> may contain %-wildcards of the POSIX strftime function of the underlying OS (see your strftime manual), additionally %Q is replaced with a sequential number unique to the SingleFileLog device. The file content is based on the template attribute, see below.
If the filename is enclosed in {} then it is evaluated as a perl expression, which can be used to use a global path different from %L.

Set
N/A

Get
N/A

Attributes
• addStateEvent


• disable
• disabledForIntervals


• dosLineEnding
  Create the file with the line-terminator used on Windows systems (\r\n).


• numberFormat
  If a word in the event looks like a number, then it is reformatted using the numberFormat, and $EVTNUMx is set (analogue to $EVTPARx). Default is %1.6E, see the printf manual for details.


• readySuffix
  The file specified in the definition will be created with the suffix .tmp and after the file is closed, will be renamed to the value of this attribute. Default is .rdy, specify none to remove the suffix completely.


• syncAfterWrite
  Force the operating system to write the contents to the disc if set to 1. Note: this can slow down the writing, and may shorten the life of SSDs. Defalt is 0 (off)


• template
  This attribute specifies the content of the file. Following variables are replaced before writing the file:
  • $EVENT - the complete event
  • $EVTPART0 $EVTPART1 ... - the event broken into single words
  • $EVTNUM0 $EVTNUM1 ... - reformatted as numbers, see numberFormat above
  • $NAME - the name of the device generating the event
  • $time - the current time, formatted as YYYY-MM-DD HH:MM:SS
  • $time14 - the current time, formatted as YYYYMMDDHHMMSS
  • $time16 - the current time, formatted as YYYYMMDDHHMMSSCC, where CC is the hundredth second
  If the template is enclosed in {} than it will be evaluated as a perl expression, and its result is written to the file.
  Default is $time $NAME $EVENT\n


• writeInBackground
  if set (to 1), the writing will occur in a background process to avoid blocking FHEM. Default is 0.

SmartMeterP1

[EN DE]

The SmartMeterP1 is a module which can interpret the data received from a Smart Meter used to keep track of electricity and gas usage. Currently it can proces P1 protocol DSMR 4.0. Probably also others but not tested. Tested with a Landys+Gyr E350 and a Iskra - ME382. Note: This module may require the Device::SerialPort or Win32::SerialPort module if you attach the device via USB and the OS sets strange default parameters for serial devices.

Define
define <name> SmartMeterP1 <device>

USB-connected device (P1 USB-Serial cable):

<device> specifies the serial port to read the incoming data from. The name of the serial-device depends on your distribution, under linux the ftdi-sio kernel module is responsible, and usually a /dev/ttyUSB0 device will be created.

You can specify a baudrate of 115200, e.g.: /dev/ttyUSB0@115200

For the Landys+Gyr E350 use: define SmartMeterP1 SmartMeterP1 /dev/ttyUSB0@115200
For the Iskra - ME382 use: define SmartMeterP1 SmartMeterP1 /dev/p1usb@9600,7,E,1



If the device is called none, then no device will be opened, so you can experiment without hardware attached.


Attributes
• write2db
  If you would like to store your read data into a mysql database you can activate it with this setting. Allowed values are:
  0 - Do not write to datbase (default)
  1 - Write to database
  
  If you want to write to a database you need to specify also the following attributes:
  
  dbHost
dbName
dbPassword
dbPort
dbUpdateInterval
dbUser
  
  And create a table in your database called 'smartmeter with the following syntax:
  CREATE TABLE `smartmeter` ( `date` datetime NOT NULL, `obis_ref` varchar(45) COLLATE utf8_bin NOT NULL, `value` float DEFAULT NULL, `unit` varchar(45) COLLATE utf8_bin DEFAULT NULL, PRIMARY KEY (`date`,`obis_ref`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_bin


• dbHost
  The hostname or ip address of the MySQL server.


• dbPort
  The TCP port the MySQL server is listening on. Default is 3306.


• dbName
  The name of the dabase to use.


• dbUsername
  The name of the MySQL use which has read and write access to the database and table 'smartmeter'.


• dbPassword
  Password of the MySQL user.


• dbUpdateInterval
  How often should the measured value be written to the database.
  This value is in minutes.
  
  So when a new value is read from the smartmeter the time will be checked to the time of the last value written to the database. If the difference is bigger than this interval the value will be written to the database.
  
  With this value you can control how much and how fast data is written into your database.


• removeUnitSeparator
  When set to true it will replace the unit asterisk separator by a space character. So 00900.701*m3 becomes 00900.701 m3


• removeLeadingZero
  When set to true it will remove all leading zeros in a value. So 00900.701 m3 becomes 900.701 m3 and
  0000.123 kWh becomes 0.123 kWh

SmartPi

[EN DE]

Define

define <name> SmartPi <HOST>

Beispiel:

define Gardena_Bridge SmartPi 192.168.1.34

Readings
• phaseX_Current - Current [A] (available for phase 1,2,3, neutral conductor)
• phaseX_Voltage - Voltage [V] (available for phase 1,2,3)
• phaseX_Power - Power [W] (available for phase 1,2,3)
• phaseX_Cosphi - cos φ (available for phase 1,2,3 – it is important to measure the voltage)
• phaseX_Frequency - Frequency [Hz] (available for phase 1,2,3)
get
• phaseX Y - get new Y (Voltage or Current or so)data about phaseX
Attribute
• disable - disables the device
• disabledForIntervals - disable device for interval time (13:00-18:30 or 13:00-18:30 22:00-23:00)
• interval - interval in seconds for statusRequest
• decimalPlace - set decimal Place

Snapcast

[EN DE]

Snapcast is a module to control a Snapcast Server. Snapcast is a little project to achieve multiroom audio and is a leightweight alternative to such solutions using Pulseaudio. Find all information about Snapcast, how to install and configure on the Snapcast GIT. To use this module, the minimum is to define a snapcast server module which defines the connection to the actual snapcast server. See the define section for how to do this. On top of that, it is possible to define virtual client modules, so that each snapcast client that is connected to the Snapcast Server is represented by its own FHEM module. The purpose of that is to provide an interface to the user that enables to integrate Snapcast Clients into existing visualization solutions and to use other FHEM capabilities around it, e.g. Notifies, etc. The server module includes all readings of all snapcast clients, and it allows to control all functions of all snapcast clients. Each virtual client module just gets the reading for the specific client. The client modules is encouraged and also makes it possible to do per-client Attribute settings, e.g. volume step size and volume constraints.



Define

define Snapcast [<ip> <port>]

Example: define MySnap Snapcast 127.0.0.1 1705

This way a snapcast server module is defined. IP defaults to localhost, and Port to 1705, in case you run Snapcast in the default configuration on the same server as FHEM, you dont need to give those parameters.


define Snapcast client <server> <clientid>

Example: define MySnapClient Snapcast client MySnap aabbccddeeff

This way a snapcast client module is defined. The keyword client does this. The next argument links the client module to the associated server module. The final argument is the client ID. In Snapcast each client gets a unique ID, which is normally made out of the MAC address. Once the server module is initialized it will have all the client IDs in the readings, so you want to use those for the definition of the client modules



Set

For a Server module: set <name> <function> <client> <value>

For a Client module: set <name> <function> <value>

Options:
• update
  Perform a full update of the Snapcast Status including streams and servers. Only needed if something is not working. Server module only
• volume
  Set the volume of a client. For this and all the following 4 options, give target as second parameter (only for the server module) and the desired value as third parameter. target can be given as
  • client either as name, IP or MAC
  • all to change volume of all clients at once (only for server module)
  • group id to change volume of all clients belonging to that group at once
  volume can be given in 3 ways: Range between 0 and 100 to set volume directly. Increment or Decrement given between -100 and +100. Keywords up and down to increase or decrease with a predifined step size. The step size can be defined in the attribute volumeStepSize
  The step size can be defined smaller for the lower volume range, so that finetuning is possible in this area. See the description of the attributes volumeStepSizeSmall and volumeStepThreshold Setting a volume bigger than 0 also unmutes the client, if muted.
• mute
  Mute or unmute by giving "true" or "false" as value. If no argument given, toggle between muted and unmuted.
• latency
  Change the Latency Setting of the client
• name
  Change the Name of the client
• stream
  Change the stream that the client is listening to. Snapcast uses one or more streams which can be unterstood as virtual audio channels. Each client/room can subscribe to one of them. By using next as value, you can cycle through the avaialble streams
• group
  For client type devices, you may use a single group id as argument to add the client to the given group or the keyword remove to singularize that client. Options for server type devices:
  • <group id> name <new name>
  • <group id> add <client> add that client to the given group
  • <group id> remove <client>




Attributes

All attributes can be set to the master module and the client modules. Using them for client modules enable the setting of different attribute values per client.
• streamnext
  Can be set to all or playing. If set to all, the next function cycles through all streams, if set to playing, the next function cycles only through streams in the playing state.
• volumeStepSize
  Default: 5. Set this to define, how far the volume is changed when using up/down volume commands.
• volumeStepThreshold
  Default: 7. When the volume is below this threshold, then the volumeStepSizeSmall setting is used for volume steps, rather than the normal volumeStepSize.
• volumeStepSizeSmall
  Default: 1. This typically smaller step size is used when using "volume up" or "volume down" and the current volume is smaller than the threshold.
• constraintDummy
  Links the Snapcast module to a dummy. The value of the dummy is then used as a selector for different sets of volumeConstraints. See the description of the volumeConstraint command.
• constraints
  Defines a set of volume Constraints for each client and, optionally, based on the value of the dummy as defined with constraintDummy. This way there can be different volume profiles for e.g. weekdays or weekends. volumeConstraints mean, that the maximum volume of snapcast clients can be limited or even set to 0 during certain times, e.g. at night for the childrens room, etc. the constraint argument is given in the folling format: |hh:mm vol hh:mm vol ... [|hh:mm vol ... etc. The chain off pairs defines a volume profile for 24 hours. It is equivalent to the temeratore setting of the homematic thermostates supported by FHEM.
  Example: standard|08:00 0 18:00 100 22:00 30 24:00 0,weekend|10:00 0 20:00 100 24:00 30

In this example, there are two profiles defined. If the value of the associated dummy is "standard", then the standard profile is used. It mutes the client between midnight and 8 am, then allows full volume until 18:00, then limites the volume to 30 until 22:00 and then mutes the client for the rest of the day. The snapcast module does not increase the volume when a limited time is over, it only allows for increasing it manually again.

The module reads data from Grünbeck Cloud for Softliq (SD series) water softeners. It also allows setting parameters and controlling the water softener to a certain extent

Define
define the module with define SoftliqCloud where login name is the login name for the softliq cloud. After that, set your password set password
Get
• authenticate: usually not needed, but in rare cases it might be required to re-authenticate
• query: reads the data from the cloud
• realtime: starts the data streaming (similar to the refresh button in the app)
• salt/water: display salt/water history
• paramList: shows a list of available parameters (readings) with current values. If the meaning is known there's a short explanation for it.
Set
• param: Allows to set parameters (see paramList) set meineSoftliq
• regenerate: Immediately starts a regeneration (without warning)
• refill: execute after you refilled (25kg) salt. Allows tracking of remaining salt
• password: usually only needed initially (or if you change your password in the cloud)
Attributes
• sq_duplex: set to 1, if you own a duplex machine
• sq_interval: polling interval in seconds (defaults to 3600)

SolarEdgeAPI

[EN DE]

This module retrieves data from a SolarEdge PV system via the SolarEdge Server Monitoring API.

Data is retrieved from the server periodically. The interval during day time is typically higher
compared to night time. According to the API documentation the total number of server queries per
day is limited to 300.
The intervals as well as the start of day time and night time can be controlled by attributes.
In each interval each enabled group of readings is generated once. You can reduce the number of
server queries by disabling groups of readings and by increasing the interval time.

Note: Features marked as "deprecated" or "debug only" may change or disappear in future versions.

Define
define <name> SolarEdgeAPI <API Key> <Site ID>
The <API Key> and the <Site ID> can be retrieved from the SolarEdge
Monitoring Portal. The <API Key> has to be enabled in the "Admin" Secion
of the web portal.


Readings
All reading names start with the name of the group of readings followed by "-".
All readings that belong to the same group have the same timing: Some groups of readings are generated
periodically. The period is defined by attributes intervalAtDayTime, intervalAtNighttime, dayTimeStartHour and
nightTimeStartHour. Other readings are generated once per day only. Reading groups which are updated
once per day have a name starting with "daily". Each update of a group of readings requires on http
request to the SolarEdge server. The number of queries is limited to 300 per day, according to API
documentation.

Groups of readings:


• overview - readings generated from "overview" API response
  • overview-power [W]
  • overview-energyLifetime [MWh]
  • overview-energyYear [kWh]
  • overview-energyMonth [kWh]
  • overview-energyDay [Wh]
• dailyOverview - readings generated from "overview" API response once per day
  • dailyOverview-energyDay [Wh] - This reading is derived. It depends on the latest dailyOverview-energyMonth reading.
  • dailyOverview-energyMonth [kWh]
  • dailyOverview-energyYear [kWh]
  • dailyOverview-energyLifetime [MWh]
  • dailyOverview-energyMonthOnce [kWh] generated on the last day of the month only
  • dailyOverview-energyYearOnce [kWh] generated on the last day of the year only
• aggregates - readings generated from "energyDetails" API response
  
  • aggregates-<meterType>-cumToday [Wh]
  • aggregates-<meterType>-recent15min [Wh](deprecated)
• dailyAggregates - readings generated from "energyDetails" API response once per day
  
  • dailyAggregates-<meterType>-cumDayOnce [Wh]
  • dailyAggregates-<meterType>-cumMonthDaily [kWh]
  • dailyAggregates-<meterType>-cumYearDaily [kWh]
  • dailyAggregates-<meterType>-cumMonthOnce [kWh] generated on the last day of the month only
  • dailyAggregates-<meterType>-cumYearOnce [kWh] generated on the last day of the year only
• storage - readings generated from "storageData" API response
  
  • storage-<serial>-power [W]
  • storage-<serial>-batteryState
  • storage-<serial>-batteryStateDecoded [text]
  • storage-<serial>-lifetimeEnergyCharged
  • storage-<serial>-lifetimeEnergyDischarged
  • storage-<serial>-internalTemp [degrees C]
  • storage-<serial>-batteryPercentageState [percent]
• dailyStorage - readings generated from "storageData" API response once per day
  
  • dailyStorage-<serial>-lifetimeEnergyCharged [MWh]
  • dailyStorage-<serial>-lifetimeEnergyDischarged [MWh]
  • dailyStorage-<serial>-fullPackEnergyAvailable [kWh]
• dailyDetails - readings generated from "details" API response once per day
  
  • dailyDetails-peakPower [W]
  • dailyDetails-status [text]
• status - readings generated from "currentPowerFlow" API response. This API is not supported by all sites.
  
  • status-grid_status [?]
  • status-grid_power [W]
  • status-load_status [?]
  • status-load_power [W]
  • status-pv_status [?]
  • status-pv_power [W]
  • status-storage_status [?]
  • status-storage_power [W]
  • status-storage_level [?]
  • status-storage_critical [?]
• debug - debug data about successful and failing http requests (for debug only)
• actionQueue - information about the entries in the action queue (for debug only)

Get
• numberOfRequests - get the expected number of requests per day with current attribute settings (for debug only)
• status - fetch corresponding group of readings (for debug only)
• aggregates - fetch corresponding group of readings (for debug only)
• overview - fetch corresponding group of readings (for debug only)
• storage - fetch corresponding group of readings (for debug only)
• dailyDetails - fetch corresponding group of readings (for debug only)
• dailyStorage - fetch corresponding group of readings (for debug only)
• dailyAggregates - fetch corresponding group of readings (for debug only)
• dailyOverview - fetch corresponding group of readings (for debug only)

Set
• restartTimer - restart periodic http requests (for debug only)
• resetDebugCounters - reset debug counters (internals and optional debug* readings) (for debug only)

Attributes
• intervalAtDayTime - interval of http requests during day time (default: 215 (seconds))
• intervalAtNightTime - interval of http requests during night time (default: 1200 (seconds))
• dayTimeStartHour - start of daytime, default 6 (= 6:00am)
• nightTimeStartHour - start of night time, default 22 (= 10:00pm)
• enableStatusReadings - enable the corresponding group of readings, default: 0
• enableAggregatesReadings - enable the corresponding group of readings, default: 0
• enableOverviewReadings - enable the corresponding group of readings, default: 1
• enableStorageReadings - enable the corresponding group of readings, default: 0
• enableDailyDetailsReadings - enable the corresponding group of readings, default: 1
• enableDailyStorageReadings - enable the corresponding group of readings, default: 0
• enableDailyAggregatesReadings - enable the corresponding group of readings, default: 0
• enableDailyOverviewReadings - enable the corresponding group of readings, default: 1
• enableDebugReadings Enable the debug* readings. These debug readings do not cause additional http requests. Default: 0

SolarForecast

[EN DE]

The SolarForecast module generates a forecast for the solar yield on the basis of the values from generic sources and integrates further information as a basis for control systems based on this forecast.
To create the solar forecast, the SolarForecast module can use different services and sources:

DWD	solar forecast based on MOSMIX data of the German Weather Service
SolCast-API	uses forecast data of the SolCast API
ForecastSolar-API	uses forecast data of the Forecast.Solar API
OpenMeteoDWD-API	ICON weather models of the German Weather Service (DWD) via Open-Meteo
OpenMeteoDWDEnsemble-API	Access to the global ensemble forecast system (EPS) of the DWD
OpenMeteoWorld-API	Seamlessly combines weather models from organizations such as NOAA, DWD, CMCC and ECMWF via Open-Meteo
VictronKI-API	Victron Energy API of the VRM Portal

The use of the mentioned API's is limited to the respective free version of the selected service.
AI support can be activated depending on the model used.

In addition to the PV generation forecast, consumption values or grid reference values are recorded and used for a consumption forecast.
The module calculates a future energy surplus from the forecast values, which is used to plan the operation of consumers. Furthermore, the module offers Consumer Integration for integrated planning and control of PV surplus dependent consumer circuits. Support for optimum battery SoC management is also part of the range of functions.

At the first definition of the module the user is supported by a Guided Procedure to make all initial entries.
At the end of the process and after relevant changes to the system or device configuration, it is essential to perform a set <name> plantConfiguration ceck to ensure that the system configuration is correct.

Define


A SolarForecast Device is created with:


define <name> SolarForecast

After the definition of the device, depending on the forecast sources used, it is mandatory to store additional plant-specific information.
The following set commands and attributes are used to store information that is relevant for the function of the module:



setupWeatherDevX	DWD_OpenData Device which provides meteorological data (e.g. cloud cover)
setupRadiationAPI	DWD_OpenData Device or API for the delivery of radiation data.
setupInverterDevXX	Device which provides PV performance data
setupMeterDev	Device which supplies network I/O data
setupBatteryDev	Device which provides battery performance data (if available)
setupInverterStrings	Identifier of the existing plant strings
setupStringAzimuth	Azimuth of the plant strings
setupStringPeak	the DC peak power of the plant strings
roofIdentPair	the identification data (when using the SolCast API)
setupRoofTops	the Rooftop parameters (when using the SolCast API)
setupStringDeclination	the angle of inclination of the plant modules


In order to enable an adjustment to the personal system, correction factors can be manually fixed or automatically applied dynamically.


Consumer Integration


The user can register consumers (e.g. switchable sockets) directly in the module and let the SolarForecast module take over the planning of the on/off times as well as their execution. Registration is done using the ConsumerXX attributes. In addition to the FHEM consumer device, a number of mandatory or optional keys are specified in the attributes that influence the scheduling and switching behavior of the consumer.
The keys are described in detail in the ConsumerXX help. In order to learn how to use the consumer control, it is advisable to first create one or more dummies and register these devices as consumers.

A dummy device according to this pattern is suitable for this purpose:


define SolCastDummy dummy
attr SolCastDummy userattr nomPower
attr SolCastDummy alias SolarForecast Consumer Dummy
attr SolCastDummy cmdIcon on:remotecontrol/black_btn_GREEN off:remotecontrol/black_btn_RED
attr SolCastDummy devStateIcon off:light_light_dim_100@grey on:light_light_dim_100@darkorange
attr SolCastDummy group Solarforecast
attr SolCastDummy icon solar_icon
attr SolCastDummy nomPower 1000
attr SolCastDummy readingList BatIn BatOut BatVal BatInTot BatOutTot bezW einW Batcharge Temp automatic
attr SolCastDummy room Energy,Testroom
attr SolCastDummy setList BatIn BatOut BatVal BatInTot BatOutTot bezW einW Batcharge on off Temp
attr SolCastDummy userReadings actpow {ReadingsVal ($name, 'state', 'off') eq 'on' ? AttrVal ($name, 'nomPower', 100) : 0}




Set
• aiDecTree
  
  If AI support is enabled in the SolarForecast Device, various AI actions can be performed manually. The manual execution of the AI actions is generally not necessary, since the processing of all necessary steps is already performed automatically in the module.
  
  

  addInstances	- The AI is enriched with the currently available PV, radiation and environmental data.
  addRawData	- Relevant PV, radiation and environmental data are extracted and stored for later use.
  train	- The AI is trained with the available data.
  	Successfully generated decision data is stored in the file system.



• batteryTrigger <1on>=<Value> <1off>=<Value> [<2on>=<Value> <2off>=<Value> ...]
  
  Generates triggers when the battery charge exceeds or falls below certain values (SoC in %).
  If the last three SoC measurements exceed a defined Xon-Bedingung, the reading batteryTrigger_X = on is created/set.
  If the last three SoC measurements fall below a defined Xoff-Bedingung, the reading batteryTrigger_X = off is created/set.
  Any number of trigger conditions can be specified. Xon/Xoff conditions do not necessarily have to be defined in pairs.
  
  
  Example:
  set <name> batteryTrigger 1on=30 1off=10 2on=70 2off=20 3on=15 4off=90
  


• consumerNewPlanning <Consumer number>
  
  The existing planning of the specified consumer is deleted.
  The new planning is carried out immediately, taking into account the parameters set in the consumerXX attribute.
  
  
  Beispiel:
  set <name> consumerNewPlanning 01
  


• consumerImmediatePlanning <Consumer number>
  
  Immediate switching on of the consumer at the current time is scheduled. Any keys notbefore, notafter respectively mode set in the consumerXX attribute are ignored
  
  
  Example:
  set <name> consumerImmediatePlanning 01
  


• energyH4Trigger <1on>=<Value> <1off>=<Value> [<2on>=<Value> <2off>=<Value> ...]
  
  Generates triggers on exceeding or falling below the 4-hour PV forecast (NextHours_Sum04_PVforecast).
  Überschreiten die letzten drei Messungen der 4-Stunden PV Vorhersagen eine definierte Xon-Bedingung, wird das Reading energyH4Trigger_X = on erstellt/gesetzt. If the last three measurements of the 4-hour PV predictions exceed a defined Xon condition, the Reading energyH4Trigger_X = off is created/set.
  Any number of trigger conditions can be specified. Xon/Xoff conditions do not necessarily have to be defined in pairs.
  
  
  Example:
  set <name> energyH4Trigger 1on=2000 1off=1700 2on=2500 2off=2000 3off=1500
  


• setupStringAzimuth <Stringname1>=<dir> [<Stringname2>=<dir> <Stringname3>=<dir> ...]
  (only model DWD, OpenMeteo*, ForecastSolarAPI)
  
  Alignment <dir> of the solar modules in the string "StringnameX". The string name is a key value of the setupInverterStrings attribute.
  The direction specification <dir> can be specified as an azimuth identifier or as an azimuth value:
  
  

  Identifier	Azimuth
  N	-180	North orientation
  NE	-135	North-East orientation
  E	-90	East orientation
  SE	-45	South-east orientation
  S	0	South orientation
  SW	45	South-west orientation
  W	90	West orientation
  NW	135	North-West orientation

  
  Azimuth values are integers in the range -180 to 180. Although the specified identifiers can be used, it is recommended to specify the exact azimuth value in the attribute. This allows any intermediate values such as 83, 48 etc. to be specified.
  
  
  Example:
  set <name> setupStringAzimuth Ostdach=-85 Südgarage=S S3=132
  


• setupStringDeclination <Stringname1>=<Angle> [<Stringname2>=<Angle> <Stringname3>=<Angle> ...]
  (only model DWD, ForecastSolarAPI)
  
  Tilt angle of the solar modules. The string name is a key value of the attribute setupInverterStrings.
  Possible angles of inclination are: 0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90 (0 = horizontal, 90 = vertical).
  
  
  Example:
  set <name> setupStringDeclination eastroof=40 southgarage=60 S3=30
  


• operatingMemory backup | save | recover-<File>
  
  The pvHistory (PVH) and pvCircular (PVC) components of the internal cache database are stored in the file system.
  The target directory is "../FHEM/FhemUtils". This process is carried out regularly by the module in the background.
  
  

  backup	Saves the active in-memory structures with the current timestamp.
  	ctrlBackupFilesKeep generations of the files are saved. Older versions are deleted.
  	Files: PVH_SolarForecast_<name>_<Timestamp>, PVC_SolarForecast_<name>_<Timestamp>
  save	The active in-memory structures are saved.
  	Files: PVH_SolarForecast_<name>, PVC_SolarForecast_<name>
  recover-<File>	Restores the data of the selected backup file as an active in-memory structure.
  	To avoid inconsistencies, the PVH.* and PVC.* files should be restored in pairs
  	with the same time stamp.

  
  


• operationMode
  
  The SolarForecast device is deactivated with inactive. The active option reactivates the device. The behavior corresponds to the "disable" attribute, but is particularly suitable for use in Perl scripts as compared to the "disable" attribute, it is not necessary to save the device configuration.


• plantConfiguration
  
  Depending on the selected command option, the following operations are performed:
  
  

  check	Checks the current plant configuration. A plausibility check
  	is performed and the result and any notes or errors are output.
  save	Secures important parameters of the plant configuration.
  	The operation is performed automatically every day shortly after 00:00.
  restore	Restores a saved plant configuration



• powerTrigger <1on>=<Value> <1off>=<Value> [<2on>=<Value> <2off>=<Value> ...]
  
  Generates triggers when certain PV generation values (Current_PV) are exceeded or not reached.
  If the last three measurements of PV generation exceed a defined Xon condition, the Reading powerTrigger_X = on is created/set. If the last three measurements of the PV generation fall below a defined Xoff-Bedingung, the Reading powerTrigger_X = off is created/set.
  Any number of trigger conditions can be specified. Xon/Xoff conditions do not necessarily have to be defined in pairs.
  
  
  Example:
  set <name> powerTrigger 1on=1000 1off=500 2on=2000 2off=1000 3on=1600 4off=1100
  


• pvCorrectionFactor_Auto
  
  Switches the automatic prediction correction on/off. The mode of operation differs depending on the selected method.
  (default: off)
  
  on_simple(_ai):
  In this method, the hourly predicted amount of energy is compared with the real amount of energy generated and a correction factor used for the future for the respective hour. The forecast data provided by the selected API is not additionally related to other conditions such as cloud cover or temperatures.
  If the AI support is switched on (on_simple_ai) and a PV forecast value is supplied by the AI, this value is used instead of the API value.
  
  on_complex(_ai):
  In this method, the hourly predicted amount of energy is compared with the real amount of energy generated and a correction factor used for the future for the respective hour. The forecast data provided by the selected API is also additionally linked to other conditions such as cloud cover or temperatures.
  If AI support is switched on (on_complex_ai) and a PV forecast value is provided by the AI, this value is used instead of the API value.
  
  Note: The automatic prediction correction is learning and needs time to optimise the correction values. After activation, optimal predictions cannot be expected immediately!
  
  Below are some API-specific tips that are merely best practice recommendations.
  
  Model OpenMeteo...API:
  The recommended autocorrection method is on_complex or on_complex_ai.
  
  Model SolCastAPI:
  The recommended autocorrection method is on_complex.
  Before turning on autocorrection, optimise the forecast with the following steps:
  
  
  • In the RoofTop editor of the SolCast API, define the efficiency factor according to the age of the plant.
    With an 8-year-old plant, it would be 84 (100 - (8 x 2%)).
    
  • after sunset, the Reading Today_PVdeviation is created, which shows the deviation between the forecast and the real PV generation in percent.
  • according to the deviation, adjust the efficiency factor in steps until an optimum is found, i.e. the smallest daily deviation is found
  • If you think you have found the optimal setting, you can set pvCorrectionFactor_Auto on*.
  
  Ideally, this process is carried out in a phase of stable meteorological conditions (uniform sun or cloud cover). cloud cover).
  
  Model VictronKiAPI:
  This model is based on Victron Energy's AI-supported API. The recommended autocorrect method is on_complex.
  
  Model DWD:
  The recommended autocorrect method is on_complex or on_complex_ai.
  
  Model ForecastSolarAPI:
  The recommended autocorrect method is on_complex.


• pvCorrectionFactor_XX <Zahl>
  
  Manual correction factor for hour XX of the day.
  (default: 1.0)
  
  Depending on the setting pvCorrectionFactor_Auto ('off' or 'on_.*'), a static or dynamic default setting is made:
  
  

  off	The set correction factor is not overwritten by the auto-correction.
  	In the pvCorrectionFactor_XX reading, the status is signaled by the addition 'manual fix'.
  on_.*	The set correction factor is overwritten by the auto-correction or AI
  	if a calculated correction value is available in the system.
  	In the pvCorrectionFactor_XX reading, the status is signaled by the addition 'manual flex'.



• reset
  
  Deletes the data source selected from the drop-down list, readings belonging to the function or other internal data structures.
  
  

  aiData	deletes an existing AI instance including all training data and reinitialises it
  batteryTriggerSet	deletes the trigger points of the battery storage
  consumerPlanning	deletes the planning data of all registered consumers
  	To delete the planning data of only one consumer, use:
  	set <name> reset consumerPlanning <Consumer number>
  	The module carries out an automatic rescheduling of the consumer circuit.
  consumerMaster	deletes the current and historical data of all registered consumers from the memory
  	The defined consumer attributes remain and the data is collected again.
  	To delete the data of only one consumer use:
  	set <name> reset consumerMaster <Consumer number>
  consumption	deletes the stored consumption values of the house
  	To delete the consumption values of a specific day:
  	set <name> reset consumption <Day> (e.g. set <name> reset consumption 08)
  	To delete the consumption values of a specific hour of a day:
  	set <name> reset consumption <Day> <Hour> (e.g. set <name> reset consumption 08 10)
  energyH4TriggerSet	deletes the 4-hour energy trigger points
  powerTriggerSet	deletes the trigger points for PV generation values
  pvCorrection	deletes the readings pvCorrectionFactor*
  	To delete all previously stored PV correction factors from the caches:
  	set <name> reset pvCorrection cached
  	To delete stored PV correction factors of a certain hour from the caches:
  	set <name> reset pvCorrection cached <Hour>
  	(e.g. set <name> reset pvCorrection cached 10)
  pvHistory	deletes the memory of all historical days (01 ... 31)
  	To delete a specific historical day:
  	set <name> reset pvHistory <Day> (e.g. set <name> reset pvHistory 08)
  	To delete a specific hour of a historical day:
  	set <name> reset pvHistory <Day> <Hour> (e.g. set <name> reset pvHistory 08 10)
  roofIdentPair	deletes all saved SolCast API Rooftop ID / API Key pairs.
  	To delete a specific pair, specify its key <pk>:
  	set <name> reset roofIdentPair <pk> (e.g. set <name> reset roofIdentPair p1)



• roofIdentPair <pk> rtid=<Rooftop-ID> apikey=<SolCast API Key>
  (only when using Model SolCastAPI)
  
  The retrieval of each rooftop created in SolCast Rooftop Sites is to be identified by specifying a pair Rooftop-ID and API-Key.
  The key <pk> uniquely identifies a linked Rooftop ID / API key pair. Any number of pairs can be created one after the other. In that case, a new name for "<pk>" is to be used in each case.
  
  The key <pk> is assigned in the atribute setupRoofTops to the Rooftops (=Strings) to be retrieved.
  
  
  Examples:
  set <name> roofIdentPair p1 rtid=92fc-6796-f574-ae5f apikey=oNHDbkKuC_eGEvZe7ECLl6-T1jLyfOgC
  set <name> roofIdentPair p2 rtid=f574-ae5f-92fc-6796 apikey=eGEvZe7ECLl6_T1jLyfOgC_oNHDbkKuC
  
  
  


• vrmCredentials user=<Benutzer> pwd=<Paßwort> idsite=<idSite>
  (only when using Model VictronKiAPI)
  
  If the Victron VRM API is used, the required access data must be stored with this set command.
  
  

  user	Username for the Victron VRM Portal
  pwd	Password for access to the Victron VRM Portal
  idsite	idSite is the identifier "XXXXXX" in the Victron VRM Portal Dashboard URL.
  	URL of the Victron VRM Dashboard:
  	https://vrm.victronenergy.com/installation/XXXXXX/dashboard

  
  To delete the stored credentials, only the argument delete must be passed to the command.
  
  
  Examples:
  set <name> vrmCredentials user=john@example.com pwd=somepassword idsite=212008
  set <name> vrmCredentials delete
  



Get
• data
  
  Starts data collection to determine the solar forecast and other values.


• dwdCatalog
  
  The German Weather Service (DWD) provides a catalog of MOSMIX stations.
  The stations provide data whose meaning is explained in this Overview. The DWD distinguishes between MOSMIX_L and MOSMIX_S stations, which differ in terms of update frequency and data volume.
  This command reads the catalog into SolarForecast and saves it in the file ./FHEM/FhemUtils/DWDcat_SolarForecast.
  The catalog can be extensively filtered and saved in GPS Exchange Format (GPX). The latitude and logitude coordinates are displayed in decimal degrees.
  Regex expressions in the corresponding keys are used for filtering. The Regex is enclosed in ^...$ for evaluation.
  The following parameters can be specified. Without parameters, the entire catalog is output:
  
  

  byID	The output is sorted by station ID. (default)
  byName	The output is sorted by station name.
  force	The latest version of the DWD station catalog is loaded into the system.
  exportgpx	The (filtered) stations are saved in the file ./FHEM/FhemUtils/DWDcat_SolarForecast.gpx.
  	This file can be displayed in the GPX viewer, for example.
  id=<Regex>	Filtering is carried out according to station ID.
  name=<Regex>	Filtering is carried out according to station name.
  lat=<Regex>	Filtering is carried out according to latitude.
  lon=<Regex>	Filtering is carried out according to longitude.

  
  
  Example:
  get <name> dwdCatalog byName name=ST.* exportgpx lat=(48|49|50|51|52)\..* lon=([5-9]|10|11|12|13|14|15)\..*
  # filters the stations largely to German locations beginning with "ST" and exports the data in GPS Exchange format


• forecastQualities
  
  Shows the correction factors currently used to determine the PV forecast with the respective start time and the average forecast quality achieved so far for this period.


• ftuiFramefiles
  
  SolarForecast provides widgets for FHEM Tablet UI v2 (FTUI2).
  If FTUI2 is installed on the system, the files for the framework can be loaded into the FTUI directory structure with this command.
  The setup and use of the widgets is described in Wiki SolarForecast FTUI Widget.


• html
  
  The SolarForecast graphic is retrieved and displayed as HTML code.
  Note: By the attribute graphicHeaderOwnspec generated set or attribute commands in the user-specific area of the header are generally hidden for technical reasons.
  One of the following selections can be given as an argument to the command:
  
  

  both	displays the header, consumer legend, energy flow graph and forecast graph (default)
  both_noHead	displays the consumer legend, energy flow graph and forecast graph
  both_noCons	displays the header, energy flow and prediction graphic
  both_noHead_noCons	displays energy flow and prediction graphs
  flow	displays the header, the consumer legend and energy flow graphic
  flow_noHead	displays the consumer legend and the energy flow graph
  flow_noCons	displays the header and the energy flow graph
  flow_noHead_noCons	displays the energy flow graph
  forecast	displays the header, the consumer legend and the forecast graphic
  forecast_noHead	displays the consumer legend and the forecast graph
  forecast_noCons	displays the header and the forecast graphic
  forecast_noHead_noCons	displays the forecast graph
  none	displays only the header and the consumer legend

  
  The graphic can be retrieved and embedded in your own code. This can be done in a simple way by defining a weblink device:
  
  
  define wl.SolCast5 weblink htmlCode { FHEM::SolarForecast::pageAsHtml ('SolCast5', '-', '<argument>') }
  
  'SolCast5' is the name of the SolarForecast device to be included. <argument> is one of the above described selection options.


• nextHours
  
  Lists the expected values for the coming hours.
  
  

  aihit	delivery status of the AI for the PV forecast (0-no delivery, 1-delivery)
  confc	expected energy consumption including the shares of registered consumers
  confcEx	expected energy consumption without consumer shares with set key exconfc=1
  crange	calculated cloud area
  correff	correction factor/quality used
  	<factor>/- -> no quality defined
  	<factor>/0..1 - quality of the PV forecast (1 = best quality)
  DoN	sunrise and sunset status (0 - night, 1 - day)
  hourofday	current hour of the day
  pvapifc	expected PV generation (Wh) of the used API incl. a possible correction
  pvaifc	expected PV generation of the AI (Wh)
  pvfc	PV generation forecast used (Wh)
  rad1h	predicted global radiation
  starttime	start time of the record
  sunaz	Azimuth of the sun (in decimal degrees)
  sunalt	Altitude of the sun (in decimal degrees)
  temp	predicted outdoor temperature
  today	has value '1' if start date on current day
  rr1c	Total precipitation during the last hour kg/m2
  rrange	range of total rain
  wid	ID of the predicted weather
  wcc	predicted degree of cloudiness



• pvHistory
  
  Displays or exports the contents of the pvHistory data memory sorted by date and hour.
  The selection list can be used to jump to a specific day. The drop-down list contains the days currently available in the memory. Without an argument, the entire data storage is listed. The 'exportToCsv' specification exports the entire content of the pvHistory to a CSV file.
  The hour specifications refer to the respective hour of the day, e.g. the hour 09 refers to the time from 08 o'clock to 09 o'clock.
  
  

  batintotal	total battery charge (Wh) at the beginning of the hour
  batin	Hour battery charge (Wh)
  batouttotal	total battery discharge (Wh) at the beginning of the hour
  batout	Battery discharge of the hour (Wh)
  batmaxsoc	maximum SOC (%) of the day
  batsetsoc	optimum SOC setpoint (%) for the day
  confc	expected energy consumption (Wh)
  con	real energy consumption (Wh) of the house
  conprice	Price for the purchase of one kWh. The currency of the price is defined in the setupMeterDev.
  csmtXX	total energy consumption of ConsumerXX
  csmeXX	Energy consumption of ConsumerXX in the hour of the day (hour 99 = daily energy consumption)
  cyclescsmXX	Number of active cycles of ConsumerXX of the day
  DoN	Sunrise and sunset status (0 - night, 1 - day)
  etotaliXX	PV meter reading “Total energy yield” (Wh) of inverter XX at the beginning of the hour
  etotalpXX	Meter reading “Total energy yield” (Wh) of producer XX at the beginning of the hour
  gcons	real power consumption (Wh) from the electricity grid
  gfeedin	real feed-in (Wh) into the electricity grid
  feedprice	Remuneration for the feed-in of one kWh. The currency of the price is defined in the setupMeterDev.
  hourscsmeXX	total active hours of the day from ConsumerXX
  minutescsmXX	total active minutes in the hour of ConsumerXX
  pprlXX	Energy generation of producer XX (see attribute setupOtherProducerXX) in the hour (Wh)
  pvfc	the predicted PV yield (Wh)
  pvrlXX	real PV generation (Wh) of inverter XX
  pvrl	Sum real PV generation (Wh) of all inverters
  pvrlvd	1-'pvrl' is valid and is taken into account in the learning process, 0-'pvrl' is assessed as abnormal
  pvcorrf	Autocorrection factor used / forecast quality achieved
  rad1h	global radiation (kJ/m2)
  rr1c	Total precipitation during the last hour kg/m2
  sunalt	Altitude of the sun (in decimal degrees)
  sunaz	Azimuth of the sun (in decimal degrees)
  wid	Weather identification number
  wcc	effective cloud cover



• pvCircular
  
  Lists the existing values in the ring buffer. The hours 01 - 24 refer to the hour of the day, e.g. the hour 09 refers to the time from 08 - 09 o'clock.
  Hour 99 has a special function.
  The values of the keys pvcorrf, quality, pvrlsum, pvfcsum and dnumsum are coded in the form <range sun elevation>.<cloud cover range>.
  Explanation of the values:
  
  

  aihit	Delivery status of the AI for the PV forecast (0-no delivery, 1-delivery)
  attrInvChangedTs	Timestamp of the last change to the inverter device definition
  batin	Battery charge (Wh)
  batout	Battery discharge (Wh)
  batouttot	total energy drawn from the battery (Wh)
  batintot	total energy charged into the battery (Wh)
  confc	expected energy consumption (Wh)
  days2care	remaining days until the battery maintenance SoC (default 95%) is reached
  dnumsum	Number of days per cloudy area over the entire term
  feedintotal	total PV energy fed into the public grid (Wh)
  gcon	real power drawn from the electricity grid
  gfeedin	real power feed-in to the electricity grid
  gridcontotal	total energy drawn from the public grid (Wh)
  initdayfeedin	initial PV feed-in value at the beginning of the current day (Wh)
  initdaygcon	initial grid reference value at the beginning of the current day (Wh)
  initdaybatintot	initial value of the total energy charged into the battery at the beginning of the current day. (Wh)
  initdaybatouttot	initial value of the total energy drawn from the battery at the beginning of the current day. (Wh)
  lastTsMaxSocRchd	Timestamp of last achievement of battery SoC >= maxSoC (default 95%)
  nextTsMaxSocChge	Timestamp by which the battery should reach maxSoC at least once
  pvapifc	expected PV generation (Wh) of the API used
  pvaifc	PV forecast (Wh) of the AI for the next 24h from the current hour of the day
  pvfc	PV forecast used for the next 24h from the current hour of the day
  pvcorrf	Autocorrection factors for the hour of the day, where 'simple' is the simple correction factor.
  pvfcsum	summary PV forecast per cloud area over the entire term
  pvrl	real PV generation of the last 24h (Attention: pvforecast and pvreal do not refer to the same period!)
  pvrlsum	summary real PV generation per cloud area over the entire term
  pprlXX	Energy generation of producer XX (see attribute setupOtherProducerXX) in the last 24 hours (Wh)
  quality	Quality of the autocorrection factors (0..1), where 'simple' is the quality of the simple correction factor.
  runTimeTrainAI	Duration of the last AI training
  aitrainLastFinishTs	Timestamp of the last successful AI training
  aiRulesNumber	Number of rules in the trained AI instance
  tdayDvtn	Today's deviation PV forecast/generation in %
  temp	Outdoor temperature
  wcc	Degree of cloud cover
  rr1c	Total precipitation during the last hour kg/m2
  wid	ID of the predicted weather
  wtxt	Description of the predicted weather
  ydayDvtn	Deviation PV forecast/generation in % on the previous day



• rooftopData
  
  The expected solar radiation data or PV generation data are retrieved from the selected API.


• solApiData
  
  Lists the data stored in the context of the API call. Administrative records are marked with a leading '? The predicted global irradiation and PV yield (Wh) data provided by the API is consolidated to one hour. The available characteristic values differ depending on the API used.
  
  

  currentAPIinterval	the currently used API retrieval interval in seconds
  lastretrieval_time	Time of the last API call
  lastretrieval_timestamp	Unix timestamp of the last API call
  Rad1h	if available, expected Global Irradiation (GI) or Global tilted Irradiation (GTI) in kJ/m2
  pv_estimate	expected PV generation (Wh)
  KI-based_co	expected Energy consumption (Wh)
  todayDoneAPIrequests	Number of executed API requests on the current day
  todayRemainingAPIrequests	Number of remaining SolCast API requests on the current day
  todayDoneAPIcalls	Number of executed API calls on the current day
  todayRemainingAPIcalls	Number of SolCast API calls still possible on the current day
  	(one call can execute several SolCast API requests)
  todayMaxAPIcalls	Maximum number of SolCast API calls per day



• valConsumerMaster
  
  Shows the data of the consumers currently registered in the SolarForecast Device.
  The drop-down list can be used to jump to a specific consumer. The drop-down list contains the consumers or consumer numbers currently available in the data memory. Without an argument, the entire data memory is listed.


• valCurrent
  
  Lists current operating data, key figures and status.


• valDecTree
  
  If AI support is activated in the SolarForecast Device, various AI-relevant data can be displayed :
  
  

  aiRawData	The PV, radiation and environmental data currently stored for the AI.
  aiRuleStrings	Returns a list that describes the AI's decision tree in the form of rules.
  	Note: While the order of the rules is not predictable, the
  	order of criteria within each rule, however, reflects the order
  	in which the criteria are considered in the decision-making process.



• valInverter
  
  Shows the operating values determined for the selected inverter or all defined inverters.
  
  

  ietotal	total energy generated by the inverter to date (Wh)
  ifeed	Energy supply characteristics
  igeneration	current PV generation (W)
  iicon	any icons defined for displaying the device in the graphic
  ialias	Alias of the device
  iname	Name of the device
  invertercap	the nominal power (W) of the inverter (if defined)
  istrings	List of strings assigned to the inverter (if defined)



• valProducer
  
  Shows the operating values determined for the selected non-PV generator or all defined non-PV generators.
  
  

  petotal	total energy generated by the producer to date (Wh)
  pfeed	Energy supply characteristics
  pgeneration	current power (W)
  picon	any icons defined for displaying the device in the graphic
  palias	Alias of the device
  pname	Name of the device



• valStrings
  
  Lists the parameters of the selected or all defined strings.



Attribute


• affectBatteryPreferredCharge
  Consumers with the can mode are only switched on when the specified battery charge (%) is reached.
  Consumers with the must mode do not observe the priority charging of the battery.
  (default: 0)


• affectConsForecastInPlanning
  If set, the consumption forecast is also taken into account in addition to the PV forecast when scheduling the consumer.
  Standard consumer planning is based on the PV forecast only.
  (default: 0)


• affectConsForecastIdentWeekdays
  If set, only the same weekdays (Mon..Sun) are included in the calculation of the consumption forecast.
  Otherwise, all weekdays are used equally for calculation.
  Any additional attribute affectConsForecastLastDays is also taken into account.
  (default: 0)


• affectConsForecastLastDays
  The specified past days (1..31) are included in the calculation of the consumption forecast.
  For example, with the attribute value “1” only the previous day is taken into account, with the value “14” the previous 14 days.
  Any additional attribute affectConsForecastIdentWeekdays is also taken into account.
  (default: all days available in pvHistory)


• affectSolCastPercentile <10 | 50 | 90>
  (only when using Model SolCastAPI)
  
  Selection of the probability range of the delivered SolCast data. SolCast provides the 10 and 90 percent probability around the forecast mean (50).
  (default: 50)


• alias
  In connection with "ctrlShowLink" any display name.


• consumerAdviceIcon
  Defines the type of information about the planned switching times of a consumer in the consumer legend.
  
  

  <Icon>@<Colour>	Activation recommendation is represented by icon and colour (optional) (default: light_light_dim_100@gold)
  	(the planning data is displayed as mouse-over text)
  times	the planning status and the planned switching times are displayed as text
  none	no display of the planning data



• consumerLegend
  Defines the position or display mode of the load legend if loads are registered in the SolarForecast Device.
  (default: icon_top)


• consumerLink
  If set, you can click on the respective consumer in the consumer list (consumerLegend) and get directly to the detailed view of the respective device on a new browser page.
  (default: 1)


• consumerXX <Device Name> type=<type> power=<power> [switchdev=<device>]
  [mode=<mode>] [icon=<Icon>[@<Color>]] [mintime=<minutes> | SunPath[:<Offset_Sunrise>:<Offset_Sunset>]]
  [on=<command>] [off=<command>] [swstate=<Readingname>:<on-Regex>:<off-Regex>] [asynchron=<Option>]
  [notbefore=<Expression>] [notafter=<Expression>] [locktime=<offlt>[:<onlt>]]
  [auto=<Readingname>] [pcurr=<Readingname>:<Unit>[:<Threshold>]] [etotal=<Readingname>:<Einheit>[:<Threshold>]]
  [swoncond=<Device>:<Reading>:<Regex>] [swoffcond=<Device>:<Reading>:<Regex>] [spignorecond=<Device>:<Reading>:<Regex>]
  [interruptable=<Option>] [noshow=<Option>] [exconfc=<Option>]
  
  Registers a consumer <Device Name> with the SolarForecast Device. In this case, <Device Name> is a consumer device already created in FHEM, e.g. a switchable socket. Most of the keys are optional, but are a prerequisite for certain functionalities and are filled with default values.
  If the dish is defined "auto", the automatic mode in the integrated consumer graphic can be switched with the corresponding push-buttons. If necessary, the specified reading is created in the consumer device if it is not available.
  
  With the optional key swoncond, an additional external condition can be defined to enable the switch-on process of the consumer. If the condition (Regex) is not fulfilled, the load is not switched on, even if the other conditions such as other conditions such as scheduling, on key, auto mode and current PV power are fulfilled. Thus, there is an AND-link of the key swoncond with the further switch-on conditions.
  
  The optional key swoffcond defines a priority switch-off condition (Regex). As soon as this condition is fulfilled, the consumer is switched off even if the planned end time (consumerXX_planned_stop) has not yet been reached (OR link). Further conditions such as off key and auto mode must be be fulfilled for automatic switch-off.
  
  With the optional interruptable key, an automatic interruption and reconnection of the consumer during the planned switch-on time. The load is temporarily switched off (interrupted) and switched on again (continued) when the interrupt condition is no longer present. The remaining runtime is not affected by an interrupt!
  
  The power key indicates the nominal power consumption of the consumer according to its data sheet. This value is used to schedule the switching times of the load and to control the switching depending on the actual PV surplus at the time of scheduling. This value is used to schedule the switching times of the load and to control the switching depending on the actual PV surplus at the time of scheduling.
  
  
  .

  type	Type of consumer. The following types are allowed:
  	dishwasher - Consumer is a dishwasher
  	dryer - Consumer is a tumble dryer
  	washingmachine - Consumer is a washing machine
  	heater - Consumer is a heating rod
  	charger - Consumer is a charging device (battery, car, bicycle, etc.)
  	other - Consumer is none of the above types
  	noSchedule - there is no scheduling or automatic switching for the consumer.
  	Display functions or manual switching are available.
  power	nominal power consumption of the consumer (see data sheet) in W
  	(can be set to "0")
  switchdev	The specified <device> is assigned to the consumer as a switch device (optional). Switching operations are performed with this device.
  	The key is useful for consumers where energy measurement and switching is carried out with different devices
  	e.g. Homematic or readingsProxy. If switchdev is specified, the keys on, off, swstate, auto, asynchronous refer to this device.
  mode	Consumer planning mode (optional). Allowed are:
  	can - Scheduling takes place at the time when there is probably enough PV surplus available (default).
  	The consumer is not started at the time of planning if the PV surplus is insufficient.
  	must - The consumer is optimally planned, even if there will probably not be enough PV surplus.
  	The load is started even if there is insufficient PV surplus, provided that a set "swoncond" condition is met and "swoffcond" is not met.
  icon	Icon and, if applicable, its color for displaying the consumer in the overview graphic (optional)
  mintime	Scheduling duration (minutes or "SunPath") of the consumer. (optional)
  	By specifying SunPath, planning is done according to sunrise and sunset.
  	SunPath[:<Offset_Sunrise>:<Offset_Sunset>] - scheduling takes place from sunrise to sunset.
  	Optionally, a positive / negative shift (minutes) of the planning time regarding sunrise or sunset can be specified.
  	If mintime is not specified, a standard scheduling duration according to the following table is used.
  	Default mintime by consumer type:
  	- dishwasher: 180 minutes
  	- dryer: 90 minutes
  	- washingmachine: 120 minutes
  	- heater: 240 minutes
  	- charger: 120 minutes
  	- other: 60 minutes
  on	Set command for switching on the consumer (optional)
  off	Set command for switching off the consumer (optional)
  swstate	Reading which indicates the switching status of the consumer (default: 'state').
  	on-Regex - regular expression for the state 'on' (default: 'on')
  	off-Regex - regular expression for the state 'off' (default: 'off')
  asynchron	the type of switching status determination in the consumer device. The status of the consumer is only determined after a switching command
  	by polling within a data collection interval (synchronous) or additionally by event processing (asynchronous).
  	0 - only synchronous processing of switching states (default)
  	1 - additional asynchronous processing of switching states through event processing
  notbefore	Schedule start time consumer not before specified time 'hour[:minute]' (optional)
  	The <Expression> has the format hh[:mm] or is Perl code enclosed in {...} that returns hh[:mm].
  notafter	Schedule start time consumer not after specified time 'hour[:minute]' (optional)
  	The <Expression> has the format hh[:mm] or is Perl code enclosed in {...} that returns hh[:mm].
  auto	Reading in the consumer device which enables or blocks the switching of the consumer (optional)
  	If the key switchdev is given, the reading is set and evaluated in this device.
  	Reading value = 1 - switching enabled (default), 0: switching blocked
  pcurr	Reading:Unit (W/kW) which provides the current energy consumption (optional)
  	:<Threshold> (W) - From this power reference on, the consumer is considered active. The specification is optional (default: 0)
  etotal	Reading:Unit (Wh/kWh) of the consumer device that supplies the sum of the consumed energy (optional)
  	:<Threshold> (Wh) - From this energy consumption per hour, the consumption is considered valid. Optional specification (default: 0)
  swoncond	Condition that must also be fulfilled in order to switch on the consumer (optional). The scheduled cycle is started.
  	Device - Device to supply the additional switch-on condition
  	Reading - Reading for delivery of the additional switch-on condition
  	Regex - regular expression that must be satisfied for a 'true' condition to be true
  swoffcond	priority condition to switch off the consumer (optional). The scheduled cycle is stopped.
  	Device - Device to supply the priority switch-off condition
  	Reading - Reading for the delivery of the priority switch-off condition
  	Regex - regular expression that must be satisfied for a 'true' condition to be true
  spignorecond	Condition to ignore a missing PV surplus (optional). If the condition is fulfilled, the load is switched on according to
  	the planning even if there is no PV surplus at the time.
  	CAUTION: Using both keys spignorecond and interruptable can lead to undesired behaviour!
  	Device - Device to deliver the condition
  	Reading - Reading which contains the condition
  	Regex - regular expression that must be satisfied for a 'true' condition to be true
  interruptable	defines the possible interruption options for the consumer after it has been started (optional)
  	0 - Load is not temporarily switched off even if the PV surplus falls below the required energy (default)
  	1 - Load is temporarily switched off if the PV surplus falls below the required energy
  	Device:Reading:Regex[:Hysteresis] - Load is temporarily interrupted if the value of the specified
  	Device:Readings match on the regex or if is insufficient PV surplus (if power not equal to 0).
  	If the value no longer matches, the interrupted load is switched on again if there is sufficient
  	PV surplus provided (if power is not 0).
  	If the optional hysteresis is specified, the hysteresis value is subtracted from the reading value and the regex is then applied.
  	If this and the original reading value match, the consumer is temporarily interrupted.
  	The consumer is continued if both the original and the subtracted readings value do not (or no longer) match.
  locktime	Blocking times in seconds for switching the consumer (optional).
  	offlt - Blocking time in seconds after the consumer has been switched off or interrupted
  	onlt - Blocking time in seconds after the consumer has been switched on or continued
  	The consumer is only switched again when the corresponding blocking time has elapsed.
  	Note: The 'locktime' switch is only effective in automatic mode.
  noshow	Hide or show consumers in graphic (optional).
  	0 - the consumer is displayed (default)
  	1 - the consumer is hidden
  	2 - the consumer is hidden in the consumer legend
  	3 - the consumer is hidden in the flow chart
  	[Device:]Reading - Reading in the consumer or optionally an alternative device.
  	If the reading has the value 0 or is not present, the consumer is displayed.
  	The effect of the possible reading values 1, 2 and 3 is as described.
  exconfc	Use of the consumer's recorded energy consumption to create the consumption forecast (optional).
  	0 - the consumer's historical energy consumption is used to create the consumption forecast (default)
  	1 - the consumer's historical energy consumption is excluded from the consumption forecast.

  
  
  Examples:
  attr <name> consumer01 wallplug icon=scene_dishwasher@orange type=dishwasher mode=can power=2500 on=on off=off notafter=20 etotal=total:kWh:5
  attr <name> consumer02 WPxw type=heater mode=can power=3000 mintime=180 on="on-for-timer 3600" notafter=12 auto=automatic
  attr <name> consumer03 Shelly.shellyplug2 type=other power=300 mode=must icon=it_ups_on_battery mintime=120 on=on off=off swstate=state:on:off auto=automatic pcurr=relay_0_power:W etotal:relay_0_energy_Wh:Wh swoncond=EcoFlow:data_data_socSum:-?([1-7][0-9]|[0-9]) swoffcond:EcoFlow:data_data_socSum:100
  attr <name> consumer04 Shelly.shellyplug3 icon=scene_microwave_oven@ed type=heater power=2000 mode=must notbefore=07 mintime=600 on=on off=off etotal=relay_0_energy_Wh:Wh pcurr=relay_0_power:W auto=automatic interruptable=eg.wz.wandthermostat:diff-temp:(22)(\.[2-9])|([2-9][3-9])(\.[0-9]):0.2
  attr <name> consumer05 Shelly.shellyplug4 icon=sani_buffer_electric_heater_side type=heater mode=must power=1000 notbefore=7 notafter=20:10 auto=automatic pcurr=actpow:W on=on off=off mintime=SunPath interruptable=1
  attr <name> consumer06 Shelly.shellyplug5 icon=sani_buffer_electric_heater_side type=heater mode=must power=1000 notbefore=07:05 notafter={return'20:05'} auto=automatic pcurr=actpow:W on=on off=off mintime=SunPath:60:-120 interruptable=1
  attr <name> consumer07 SolCastDummy icon=sani_buffer_electric_heater_side type=heater mode=can power=600 auto=automatic pcurr=actpow:W on=on off=off mintime=15 asynchron=1 locktime=300:1200 interruptable=1 noshow=noShow
  


• ctrlAIdataStorageDuration <Tage>
  If the corresponding prerequisites are met, training data is collected and stored for the module-internal AI.
  The data is deleted when it has exceeded the specified holding period (days).
  (default: 1825)


• ctrlAIshiftTrainStart <1...23>
  Daily training takes place when using the internal AI.
  Training begins approx. 15 minutes after the hour specified in the attribute.
  For example, with a set value of '3', training would start at around 03:15.
  (default: 2)


• ctrlAreaFactorUsage
  (DWD model only, experimental)
  
  When using the DWD model, an area factor of the solar modules is taken into account to calculate the expected generation. This experimental attribute determines the method for determining the area factor.
  
  

  fix	a uniquely determined area factor is used (default)
  trackFull	the area factor is calculated continuously depending on the position of the sun and applied to the total global radiation
  trackShared	the area factor is calculated continuously depending on the position of the sun and applied to an approximated
  	proportion of the direct radiation in the global radiation
  trackFlex	combines the 'trackFull' and 'trackShared' methods. The system switches from 'trackFull' to 'trackShared'
  	at a cloud cover of >=80%.



• ctrlBackupFilesKeep <Integer>
  Defines the number of generations of backup files (see also set <name> operatingMemory backup).
  (default: 3)


• ctrlBatSocManagement lowSoc=<Value> upSoC=<Value> [maxSoC=<Value>] [careCycle=<Value>]
  
  If a battery device (setupBatteryDev) is installed, this attribute activates the battery SoC management.
  The Battery_OptimumTargetSoC reading contains the optimum minimum SoC calculated by the module.
  The Battery_ChargeRequest reading is set to '1' if the current SoC has fallen below the minimum SoC.
  In this case, the battery should be forcibly charged, possibly with mains power.
  The readings can be used to control the SoC (State of Charge) and to control the charging current used for the battery.
  The module itself does not control the battery.
  
  

  lowSoc	lower minimum SoC, the battery is not discharged lower than this value (> 0)
  upSoC	upper minimum SoC, the usual value of the optimum SoC is between 'lowSoC'
  	and this value.
  maxSoC	Maximum minimum SoC, SoC value that must be reached at least every 'careCycle' days
  	in order to balance the charge in the storage network.
  	The specification is optional (<= 100, default: 95)
  careCycle	Maximum interval in days that may occur between two states of charge
  	of at least 'maxSoC'. The specification is optional (default: 20)

  
  All values are whole numbers in %. The following applies: 'lowSoc' < 'upSoC' < 'maxSoC'.
  The optimum SoC is determined according to the following scheme:
  
  

  1.	Starting from 'lowSoc', the minimum SoC is increased by 5% on the following day but not higher than
  	'upSoC', if 'maxSoC' has not been reached on the current day.
  2.	If 'maxSoC' is reached (again) on the current day, the minimum SoC is reduced by 5%, but not lower than 'lowSoc'.
  3.	Minimum SoC is reduced so that the predicted PV energy of the current or following day
  	can be absorbed by the battery. Minimum SoC is not reduced lower than 'lowSoc'.
  4.	The module records the last point in time at the 'maxSoC' level in order to ensure a charge to 'maxSoC'
  	at least every 'careCycle' days. For this purpose, the optimized SoC is changed depending on the remaining days
  	until the next 'careCycle' point in such a way that 'maxSoC' is mathematically achieved by a daily 5% SoC increase
  	at the 'careCycle' time point. If 'maxSoC' is reached in the meantime, the 'careCycle' period starts again.

  
  
  Example:
  attr <name> ctrlBatSocManagement lowSoc=10 upSoC=50 maxSoC=99 careCycle=25
  


• ctrlConsRecommendReadings
  Readings of the form consumerXX_ConsumptionRecommended are created for the selected consumers (number).
  These readings indicate whether it is recommended to switch on this consumer depending on its consumption data and the current PV generation or the current energy surplus. The value of the reading created correlates with the calculated planning data of the consumer, but may deviate from the planning period.
  


• ctrlDebug
  Enables/disables various debug modules. If only "none" is selected, there is no DEBUG output. For the output of debug messages the verbose level of the device must be at least "1".
  The debug level can be combined with each other:
  
  

  aiProcess	Data enrichment and training process for AI support
  aiData	Data use AI in the forecasting process
  apiCall	Retrieval API interface without data output
  apiProcess	API data retrieval and processing
  batteryManagement	Battery management control values (SoC)
  collectData	detailed data collection
  consumerPlanning	Consumer scheduling processes
  consumerSwitchingXX	Operations of the internal consumer switching module of consumer XX
  consumption	Consumption calculation, consumption forecasting and utilization
  consumption_long	extended output of the consumption forecast Determination
  dwdComm	Communication with the website or server of the German Weather Service (DWD)
  epiecesCalc	Calculation of specific energy consumption per operating hour and consumer
  graphic	Module graphic information
  notifyHandling	Sequence of event processing in the module
  pvCorrectionRead	Application of PV correction factors
  pvCorrectionWrite	Calculation of PV correction factors
  radiationProcess	Collection and processing of solar radiation data
  saveData2Cache	Data storage in internal memory structures



• ctrlGenPVdeviation
  Specifies the method for calculating the deviation between predicted and real PV generation. The Reading Today_PVdeviation is created depending on this setting.
  
  

  daily	Calculation and creation of Today_PVdeviation is done after sunset (default)
  continuously	Calculation and creation of Today_PVdeviation is done continuously



• ctrlInterval <Sekunden>
  Repetition interval of the data collection.
  Regardless of the set interval, data is collected automatically a few seconds before the end and after the start of a full hour.
  If ctrlInterval is explicitly set to "0", no automatic data collection takes place and must be carried out externally with "get <name> data".
  (default: 70)


• ctrlLanguage <DE | EN>
  Defines the used language of the device. The language definition has an effect on the module graphics and various reading contents.
  If the attribute is not set, the language is defined by setting the global attribute "language".
  (default: EN)


• ctrlNextDayForecastReadings <01,02,..,24>
  If set, readings of the form Tomorrow_Hour<hour>_PVforecast are created.
  These readings contain the expected PV generation of the coming day. Here <hour> is the hour of the day.
  
  
  Example:
  attr <name> ctrlNextDayForecastReadings 09,11
  # creates readings for hour 09 (08:00-09:00) and 11 (10:00-11:00) of the coming day


• ctrlShowLink
  Display of the link to the detailed view of the device above the graphic area.
  (default: 1)


• ctrlSolCastAPImaxReq
  (only when using Model SolCastAPI)
  
  The setting of the maximum possible daily requests to the SolCast API.
  This value is specified by SolCast and may change according to the SolCast license model.
  (default: 50)


• ctrlSolCastAPIoptimizeReq
  (only when using Model SolCastAPI)
  
  The default retrieval interval of the SolCast API is 1 hour. If this attribute is set, the interval is dynamically adjustment of the interval with the goal to use the maximum possible fetches within sunrise and sunset.
  (default: 0)


• ctrlStatisticReadings
  Readings are created for the selected key figures and indicators with the naming scheme 'statistic_<indicator>'. Selectable key figures / indicators are:
  
  

  allStringsFullfilled	Fulfillment status of error-free generation of all strings
  conForecastTillNextSunrise	Consumption forecast from current hour to the coming sunrise
  currentAPIinterval	the current call interval of the SolCast API (only model SolCastAPI) in seconds
  currentRunMtsConsumer_XX	the running time (minutes) of the consumer "XX" since the last switch-on. (last running cycle)
  dayAfterTomorrowPVforecast	provides the forecast of PV generation for the day after tomorrow (if available) without autocorrection (raw data)
  daysUntilBatteryCare	Days until the next battery maintenance (reaching the charge 'maxSoC' from attribute ctrlBatSocManagement)
  lastretrieval_time	the last call time of the API (only Model SolCastAPI, ForecastSolarAPI)
  lastretrieval_timestamp	the timestamp of the last call time of the API (only Model SolCastAPI, ForecastSolarAPI)
  response_message	the last status message of the API (only Model SolCastAPI, ForecastSolarAPI)
  runTimeAvgDayConsumer_XX	the average running time (minutes) of consumer "XX" on one day
  runTimeCentralTask	the runtime of the last SolarForecast interval (total process) in seconds
  runTimeTrainAI	the runtime of the last AI training cycle in seconds
  runTimeLastAPIAnswer	the last response time of the API call to a request in seconds (only model SolCastAPI, ForecastSolarAPI)
  runTimeLastAPIProc	the last process time for processing the received API data (only model SolCastAPI, ForecastSolarAPI)
  SunMinutes_Remain	the remaining minutes until sunset of the current day
  SunHours_Remain	the remaining hours until sunset of the current day
  todayConsumptionForecast	Consumption forecast per hour of the current day (01-24)
  todayConForecastTillSunset	Consumption forecast from current hour to hour before sunset
  todayDoneAPIcalls	the number of API calls executed on the current day (only model SolCastAPI, ForecastSolarAPI)
  todayDoneAPIrequests	the number of API requests executed on the current day (only model SolCastAPI, ForecastSolarAPI)
  todayGridConsumption	the energy drawn from the public grid on the current day
  todayGridFeedIn	PV energy fed into the public grid on the current day
  todayMaxAPIcalls	the maximum possible number of SolCast API calls (SolCastAPI model only).
  	A call can contain multiple API requests.
  todayRemainingAPIcalls	the number of SolCast API calls still possible on the current day (only model SolCastAPI)
  todayRemainingAPIrequests	the number of SolCast API requests still possible on the current day (only model SolCastAPI)
  todayBatIn	the energy charged into the battery on the current day
  todayBatOut	the energy taken from the battery on the current day

  
  


• ctrlUserExitFn {<Code>}
  After each cycle (see the ctrlInterval attribute), the code given in this attribute is executed. The code is to be enclosed in curly brackets {...}.
  The code is passed the variables $name and $hash, which contain the name of the SolarForecast device and its hash.
  In the SolarForecast Device, readings can be created and modified using the storeReading function.
  
  
  Beispiel:
  {
  my $batdev = (split " ", AttrVal ($name, 'setupBatteryDev', ''))[0];
  my $pvfc = ReadingsNum ($name, 'RestOfDayPVforecast', 0);
  my $cofc = ReadingsNum ($name, 'RestOfDayConsumptionForecast', 0);
  my $diff = $pvfc - $cofc;
  
  storeReading ('userFn_Battery_device', $batdev);
  storeReading ('userFn_estimated_surplus', $diff);
  }


• flowGraphicControl <Key1=Value1> <Key2=Value2> ...
  By optionally specifying the key=value pairs listed below, various display properties of the energy flow graph can be influenced.
  The entry can be made in several lines.
  
  

  animate	Animates the energy flow graphic if displayed. (graphicSelect)
  	0 - Animation off, 1 - Animation on, default: 1
  consumerdist	Controls the distance between the consumer icons.
  	Value: 80 ... 500, default: 130
  h2consumerdist	Extension of the vertical distance between the house and the consumer icons.
  	Value: 0 ... 999, default: 0
  shift	Horizontal shift of the energy flow graph.
  	Value: -80 ... 80, default: 0
  showconsumer	Display of consumers in the energy flow chart.
  	0 - Display off, 1 - Display on, default: 1
  showconsumerdummy	Controls the display of the dummy consumer. The dummy consumer is assigned the
  	energy consumption that cannot be assigned to other consumers.
  	0 - Display off, 1 - Display on, default: 1
  showconsumerpower	Controls the display of the consumers' energy consumption.
  	0 - Display off, 1 - Display on, default: 1
  showconsumerremaintime	Controls the display of the remaining running time (minutes) of the loads.
  	0 - Display off, 1 - Display on, default: 1
  size	Size of the energy flow graphic in pixels if displayed. (graphicSelect)
  	Value: Integer, default: 400
  strokecolina	Color of an inactive line
  	Value: Hex (e.g. #cc3300) or designation (e.g. red, blue), default: gray
  strokecolsig	Color of an active signal line
  	Value: Hex (e.g. #cc3300) or designation (e.g. red, blue), default: red
  strokecolstd	Color of an active standard line
  	Value: Hex (e.g. #cc3300) or designation (e.g. red, blue), default: darkorange
  strokewidth	Width of the lines
  	Value: Integer, default: 25

  Example:
  attr <name> flowGraphicControl size=300 animate=0 consumerdist=100 showconsumer=1 showconsumerdummy=0 shift=-20 strokewidth=15 strokecolstd=#99cc00


• graphicBeam1Color
  Color selection of the primary bar of the first level.
  (default: FFAC63)


• graphicBeam1FontColor
  Selection of the font color of the primary bar of the first level.
  (default: 0D0D0D)


• graphicBeam1MaxVal <0...val>
  Definition of the maximum amount of the primary beam of the first level for calculating the maximum beam height. height. This results in an adjustment of the permissible total height of the graphic.
  The value “0” is used for dynamic adjustment.
  (default: 0)


• graphicBeam2Color
  Color selection of the secondary bars of the first level.
  (default: C4C4A7)


• graphicBeam2FontColor
  Selection of the font color of the secondary bars of the first level.
  (default: 000000)


• graphicBeam3Color
  Color selection of the primary bars of the second level.
  (default: BED6C0)


• graphicBeam3FontColor
  Selection of the font color of the primary bars of the second level.
  (default: 000000)


• graphicBeam4Color
  Color selection of the secondary bars of the second level.
  (default: DBDBD0)


• graphicBeam4FontColor
  Selection of the font color of the secondary bars of the second level.
  (default: 000000)


• graphicBeamXContent
  Defines the content of the bars to be displayed in the bar charts. The bar charts are available in two levels.
  Level 1 is preset by default. The content is determined by the attributes graphicBeam1Content and graphicBeam2Content.
  Level 2 can be activated by setting the attributes graphicBeam3Content and graphicBeam4Content.
  The attributes graphicBeam1Content and graphicBeam3Content represent the primary beams, the attributes graphicBeam2Content and graphicBeam4Content attributes represent the secondary beams of the respective level.
  
  

  consumption	Energy consumption
  consumptionForecast	forecasted energy consumption
  energycosts	Cost of energy purchased from the grid. The currency is defined in the setupMeterDev, key conprice.
  feedincome	Remuneration for feeding into the grid. The currency is defined in the setupMeterDev, key feedprice.
  gridconsumption	Energy purchase from the public grid
  gridfeedin	Feed into the public grid
  pvReal	real PV generation (default for graphicBeam1Content)
  pvForecast	predicted PV generation (default for graphicBeam2Content)

  
  Hinweis: The selection of the parameters energycosts and feedincome only makes sense if the optional keys conprice and feedprice are set in setupMeterDev.


• graphicBeamHeightLevelX <value>
  Multiplier for determining the maximum bar height of the respective level.
  In conjunction with the attribute graphicHourCount this can also be used to generate very small graphic outputs.
  (default: 200)


• graphicBeamWidth <value>
  Width of the bars of the bar chart in px. If no attribute is set, the width of the bars is determined by the module automatically.
  


• graphicEnergyUnit <Wh | kWh>
  Defines the unit for displaying the electrical power in the graph. The kilowatt hour is rounded to one decimal place.
  (default: Wh)


• graphicHeaderDetail
  Selection of the zones of the graphic header to be displayed.
  (default: all)
  
  

  all	all zones of the head area (default)
  co	show consumption range
  pv	show creation area
  own	user zone (see graphicHeaderOwnspec)
  status	status information area



• graphicHeaderOwnspec <Label>:<Reading>[@Device] <Label>:<Set>[@Device] <Label>:<Attr>[@Device] ...
  Display of any readings, set commands and attributes of the device in the graphic header.
  Readings, set commands and attributes of other devices can be displayed by specifying the optional [@Device].
  The values to be displayed are separated by spaces. Four values (fields) are displayed per line.
  The input can be made in multiple lines. Values with the units "Wh" or "kWh" are converted according to the setting of the attribute graphicEnergyUnit.
  
  Each value is to be defined by a label and the corresponding reading connected by ":".
  Spaces in the label are to be inserted by "&nbsp;", a line break by "<br>".
  An empty field in a line is created by ":".
  A line title can be inserted by specifying "#:<Text>", an empty title by entering "#".
  
  
  Example:
  

  attr <name> graphicHeaderOwnspec	#
  	AutarkyRate:Current_AutarkyRate
  	Surplus:Current_Surplus
  	current&nbsp;Gridconsumption:Current_GridConsumption
  	:
  	#
  	CO&nbsp;until&nbsp;sunset:statistic_todayConForecastTillSunset
  	PV&nbsp;Day&nbsp;after&nbsp;tomorrow:statistic_dayAfterTomorrowPVforecast
  	:
  	:
  	#Battery
  	in&nbsp;today:statistic_todayBatIn
  	out&nbsp;today:statistic_todayBatOut
  	:
  	:
  	#Settings
  	Autocorrection:pvCorrectionFactor_Auto : : :
  	Consumer<br>Replanning:consumerNewPlanning : : :
  	Consumer<br>Quickstart:consumerImmediatePlanning : : :
  	Weather:graphicShowWeather : : :
  	History:graphicHistoryHour : : :
  	ShowNight:graphicShowNight : : :
  	Debug:ctrlDebug : : :



• graphicHeaderOwnspecValForm
  The readings to be displayed with the attribute graphicHeaderOwnspec can be manipulated with sprintf and other Perl operations.
  There are two basic notation options that cannot be combined with each other.
  The notations are always specified within two curly brackets {...}.
  
  Notation 1:
  A simple formatting of readings of your own device with sprintf is carried out as shown in line 'Current_AutarkyRate' or 'Current_GridConsumption'.
  Other Perl operations are to be bracketed with (). The respective readings values and units are available via the variables $VALUE and $UNIT.
  Readings of other devices are specified by '<Device>.<Reading>'.
  
  

  {
  'Current_AutarkyRate'	=> "%.1f %%",
  'Current_GridConsumption'	=> "%.2f $UNIT",
  'SMA_Energymeter.Cover_RealPower'	=> q/($VALUE)." W"/,
  'SMA_Energymeter.L2_Cover_RealPower'	=> "($VALUE).' W'",
  'SMA_Energymeter.L1_Cover_RealPower'	=> '(sprintf "%.2f", ($VALUE / 1000))." kW"',
  }

  
  Notation 2:
  The manipulation of reading values and units is done via Perl If ... else structures.
  The device, reading, reading value and unit are available to the structure with the variables $DEVICE, $READING, $VALUE and $UNIT.
  If the variables are changed, the new values are transferred to the display accordingly.
  
  

  {
  	if ($READING eq 'Current_AutarkyRate') {
  	$VALUE = sprintf "%.1f", $VALUE;
  	$UNIT = "%";
  	}
  	elsif ($READING eq 'Current_GridConsumption') {
  	...
  	}
  }



• graphicHeaderShow
  Show/hide the graphic table header with forecast data and certain current and statistical values.
  (default: 1)


• graphicHistoryHour
  Number of previous hours displayed in the bar graph.
  (default: 2)


• graphicHourCount <4...24>
  Number of bars/hours in the bar graph.
  (default: 24)


• graphicHourStyle
  Format of the time in the bar graph.
  
  

  nicht gesetzt	hours only without minutes (default)
  :00	Hours as well as minutes in two digits, e.g. 10:00
  :0	Hours as well as minutes single-digit, e.g. 8:0



• graphicLayoutType <single | double | diff>
  Layout of the bar graph.
  The content of the bars to be displayed is determined by the graphicBeam1Content or graphicBeam2Content attributes.
  
  

  double	displays the primary bar and the secondary bar (default)
  single	displays only the primary bar
  diff	difference display. It is valid: <Difference> = <Value primary bar> - <Value secondary bar>



• graphicSelect
  Selects the graphic segments of the module to be displayed.
  
  

  both	displays the header, consumer legend, energy flow and prediction graph (default)
  flow	displays the header, the consumer legend and energy flow graphic
  forecast	displays the header, the consumer legend and the prediction graphic
  none	displays only the header and the consumer legend



• graphicShowDiff <no | top | bottom>
  Additional display of the difference “primary bar content - secondary bar content” in the header or footer of the bar chart.
  (default: no)


• graphicShowNight
  Show/hide the night hours without values in the bar chart.
  If the selected bar contents contain a value in the night hours, these bars are also displayed if graphicShowNight=0.
  (default: 0 (hide))


• graphicShowWeather
  Show/hide weather icons in the bar graph.
  (default: 1)


• graphicSpaceSize <value>
  Defines how much space in px above or below the bars (with display type differential (diff)) is kept free for displaying the values. For styles with large fonts the default value may be too small or a bar may slip over the baseline. In these cases please increase the value.
  (default: 24)


• graphicWeatherColor
  Color of the weather icons in the bar graph for the daytime hours.


• graphicWeatherColorNight
  Color of the weather icons for the night hours.


• setupBatteryDev <Battery Device Name> pin=<Readingname>:<Unit> pout=<Readingname>:<Unit> [intotal=<Readingname>:<Unit>] [outtotal=<Readingname>:<Unit>] [cap=<Option>] [charge=<Readingname>]
  
  Specifies an arbitrary Device and its Readings to deliver the battery performance data. The module assumes that the numerical value of the readings is always positive. It can also be a dummy device with corresponding readings.
  
  

  pin	Reading which provides the current battery charging power
  pout	Reading which provides the current battery discharge rate
  intotal	Reading which provides the total battery charge as a continuous counter (optional)
  outtotal	Reading which provides the total battery discharge as a continuous counter (optional)
  cap	installed battery capacity (optional). Option can be:
  	numerical value - direct indication of the battery capacity in Wh
  	<Readingname>:<unit> - Reading which provides the capacity and unit (Wh, kWh)
  charge	Reading which provides the current state of charge (SOC in percent) (optional)
  Unit	the respective unit (W,Wh,kW,kWh)

  
  Special cases: If the reading for pin and pout should be identical but signed, the keys pin and pout can be defined as follows:
  
  
  pin=-pout    (a negative value of pout is used as pin)
  pout=-pin    (a negative value of pin is used as pout)
  
  The unit is omitted in the particular special case.
  
  
  Example:
  attr <name> setupBatteryDev BatDummy pin=BatVal:W pout=-pin intotal=BatInTot:Wh outtotal=BatOutTot:Wh cap=BatCap:kWh
  
  Note: Deleting the attribute also removes the internally corresponding data.


• setupInverterDevXX <Inverter Device Name> pv=<Readingname>:<Unit> etotal=<Readingname>:<Unit> capacity=<max. WR-Leistung> [strings=<String1>,<String2>,...] [feed=<Delivery type>] [limit=<0..100>] [icon=<Day>[@<Color>][:<Night>[@<Color>]]]
  
  Defines any inverter device or solar charger and its readings to supply the current PV generation values.
  A solar charger does not convert the energy supplied by the solar cells into alternating current, but instead directly charges an existing battery
  (e.g. a Victron SmartSolar MPPT).
  Several devices can be defined one after the other in the setupInverterDev01..XX attributes.
  This can also be a dummy device with corresponding readings.
  The values of several inverters can be combined in a dummy device, for example, and this device can be specified with the corresponding readings.
  
  
  

  pv	Reading which provides the current PV generation as a positive value
  etotal	Reading which provides the total PV energy generated (a steadily increasing counter).
  	If the reading violates the specification of a continuously rising counter,
  	SolarForecast handles this error and reports the situation by means of a log message.
  Einheit	the respective unit (W,kW,Wh,kWh)
  capacity	Rated power of the inverter according to data sheet, i.e. max. possible output in Watts
  strings	Comma-separated list of the strings assigned to the inverter (optional). The string names
  	are defined in the setupInverterStrings attribute.
  	If 'strings' is not specified, all defined string names are assigned to the inverter.
  feed	Defines special properties of the device's energy supply (optional).
  	If the key is not set, the device feeds the PV energy into the house's AC grid.
  	bat - the device supplies energy exclusively to the battery
  	grid - the energy is fed exclusively into the public grid
  limit	Defines any active power limitation in % (optional).
  icon	Icon for displaying the inverter in the flow chart (optional)
  	<Day> - Icon and optional color for activity after sunrise
  	<Night> - Icon and optional color after sunset, otherwise the moon phase is displayed

  
  
  Example:
  attr <name> setupInverterDev01 STP5000 pv=total_pac:kW etotal=etotal:kWh capacity=5000 strings=Garage icon=inverter@red:solar
  
  Note: Deleting the attribute also removes the internally corresponding data.


• setupInverterStrings <Stringname1>[,<Stringname2>,<Stringname3>,...]
  
  Designations of the active strings. These names are used as keys in the further settings.
  When using an AI based API (e.g. VictronKI API) only "KI-based" has to be entered regardless of which real strings exist.
  
  
  Examples:
  attr <name> setupInverterStrings eastroof,southgarage,S3
  attr <name> setupInverterStrings KI-based
  


• setupMeterDev <Meter Device Name> gcon=<Readingname>:<Unit> contotal=<Readingname>:<Unit> gfeedin=<Readingname>:<Unit> feedtotal=<Readingname>:<Unit> [conprice=<Field>] [feedprice=<Field>]
  
  Defines any device and its readings for measuring energy into or out of the public grid. The module assumes that the numeric value of the readings is positive. It can also be a dummy device with corresponding readings.
  
  

  gcon	Reading which supplies the power currently drawn from the grid
  contotal	Reading which provides the sum of the energy drawn from the grid (a constantly increasing meter)
  	If the counter is reset to '0' at the beginning of the day (daily counter), the module handles this situation accordingly.
  	In this case, a message is displayed in the log with verbose 3.
  gfeedin	Reading which supplies the power currently fed into the grid
  feedtotal	Reading which provides the sum of the energy fed into the grid (a constantly increasing meter)
  	If the counter is reset to '0' at the beginning of the day (daily counter), the module handles this situation accordingly.
  	In this case, a message is displayed in the log with verbose 3.
  Unit	the respective unit (W,kW,Wh,kWh)
  conprice	Price for the purchase of one kWh (optional). The <field> can be specified in one of the following variants:
  	<Price>:<Currency> - Price as a numerical value and its currency
  	<Reading>:<Currency> - Reading of the meter device that contains the price : Currency
  	<Device>:<Reading>:<Currency> - any device and reading containing the price : Currency
  feedprice	Remuneration for the feed-in of one kWh (optional). The <field> can be specified in one of the following variants:
  	<Remuneration>:<Currency> - Remuneration as a numerical value and its currency
  	<Reading>:<Currency> - Reading of the meter device that contains the remuneration : Currency
  	<Device>:<Reading>:<Currency> - any device and reading containing the remuneration : Currency

  
  Special cases: If the reading for gcon and gfeedin should be identical but signed, the keys gfeedin and gcon can be defined as follows:
  
  
  gfeedin=-gcon    (a negative value of gcon is used as gfeedin)
  gcon=-gfeedin    (a negative value of gfeedin is used as gcon)
  
  The unit is omitted in the particular special case.
  
  
  Example:
  attr <name> setupMeterDev Meter gcon=Wirkleistung:W contotal=BezWirkZaehler:kWh gfeedin=-gcon feedtotal=EinWirkZaehler:kWh conprice=powerCost:€ feedprice=0.1269:€
  
  Note: Deleting the attribute also removes the internally corresponding data.


• setupOtherProducerXX <Device Name> pcurr=<Readingname>:<Unit> etotal=<Readingname>:<Unit> [icon=<Icon>[@<Color>]]
  
  Defines any device and its readings for the delivery of other generation values (e.g. CHP, wind generation, emergency generator). This device is not intended for PV generation. It can also be a dummy device with corresponding readings.
  
  

  icon	Icon and, if applicable, color for activity to display the producer in the flow chart (optional)
  pcurr	Reading which returns the current generation as a positive value or a self-consumption (special case) as a negative value
  etotal	Reading which supplies the total energy generated (a continuously ascending counter)
  	If the reading violates the specification of a continuously rising counter,
  	SolarForecast handles this error and reports the situation that has occurred with a log entry.
  Einheit	the respective unit (W,kW,Wh,kWh)

  
  
  Example:
  attr <name> setupOtherProducer01 windwheel pcurr=total_pac:kW etotal=etotal:kWh icon=Ventilator_wind@darkorange
  
  Note: Deleting the attribute also removes the internally corresponding data.


• setupRadiationAPI
  
  Defines the source for the delivery of the solar radiation data. You can select a device of the type DWD_OpenData or an implemented API can be selected.
  Note: If OpenMeteoDWD-API is set in the 'setupWeatherDev1' attribute, no radiation data service other than OpenMeteoDWD-API can be selected.
  
  OpenMeteoDWD-API
  Open-Meteo is an open source weather API and offers free access for non-commercial purposes. No API key is required. Open-Meteo leverages a powerful combination of global (11 km) and mesoscale (1 km) weather models from esteemed national weather services. This API provides access to the renowned ICON weather models of the German Weather Service (DWD), which provide 15-minute data for short-term forecasts in Central Europe and global forecasts with a resolution of 11 km. The ICON model is a preferred choice for general weather forecast APIs when no other high-resolution weather models are available. The models DWD Icon D2, DWD Icon EU and DWD Icon Global models are merged into a seamless forecast. The comprehensive and clearly laid out API Documentation is available on the service's website.
  
  OpenMeteoDWDEnsemble-API
  This Open-Meteo API variant provides access to the DWD's global Ensemble Prediction System (EPS).
  The ensemble models ICON-D2-EPS, ICON-EU-EPS and ICON-EPS are seamlessly combined.
  Ensemble weather forecasts are a special type of forecasting method that takes into account the uncertainties in weather forecasting. They do this by running several simulations or models with slight differences in the starting conditions or settings. Each simulation, known as an ensemble member, represents a possible outcome of the weather. In this implementation, 40 ensemble members per weather feature are combined and the most probable result is used.
  
  OpenMeteoWorld-API
  As a variant of the Open Meteo service, the OpenMeteoWorld API provides the optimum forecast for a specific location worldwide. The OpenMeteoWorld API seamlessly combines weather models from well-known organizations such as NOAA (National Oceanic and Atmospheric Administration), DWD (German Weather Service), CMCC (Canadian) and ECMWF (European Centre for Medium-Range Weather Forecasts). The providers' models are combined for each location worldwide to produce the best possible forecast. The services and weather models are used automatically based on the location coordinates contained in the API call.
  
  SolCast-API
  API usage requires one or more API-keys (accounts) and one or more Rooftop-ID's in advance created on the SolCast website. A rooftop is equivalent to one setupInverterStrings in the SolarForecast context.
  Free API usage is limited to one daily rate API requests. The number of defined strings (rooftops) increases the number of API requests required. The module optimizes the query cycles with the attribute ctrlSolCastAPIoptimizeReq .
  
  ForecastSolar-API
  Free use of the Forecast.Solar API. does not require registration. API requests are limited to 12 within one hour in the free version. There is no daily limit. The module automatically determines the optimal query interval depending on the configured strings.
  Note: Based on previous experience, unreliable and not recommended.
  
  VictronKI-API
  This API can be applied by users of the Victron Energy VRM Portal. This API is AI based. As string the value "AI-based" has to be entered in the setup of the setupInverterStrings.
  In the Victron Energy VRM Portal, the location of the PV system must be specified as a prerequisite.
  See also the blog post Introducing Solar Production Forecast.
  
  DWD_OpenData Device
  The DWD service is integrated via a FHEM device of type DWD_OpenData. If there is no device of type DWD_OpenData yet, it must be defined in advance (look at DWD_OpenData Commandref).
  To obtain a good radiation forecast, a DWD station located near the plant site should be used.
  Unfortunately, not all DWD stations provide the required Rad1h values.
  Explanations of the stations are listed in Stationslexikon.
  At least the following attributes must be set in the selected DWD_OpenData Device:
  
  

  forecastDays	1 (set it to >= 2 if you want longer prediction)
  forecastProperties	Rad1h
  forecastResolution	1
  forecastStation	<Station code of the evaluated DWD station>
  	Note: The selected DWD station must provide radiation values (Rad1h Readings).
  	Not all stations provide this data!



• setupRoofTops <Stringname1>=<pk> [<Stringname2>=<pk> <Stringname3>=<pk> ...]
  (only when using Model SolCastAPI)
  
  The string "StringnameX" is assigned to a key <pk>. The key <pk> was created with the setter roofIdentPair. This is used to specify the rooftop ID and API key to be used in the SolCast API.
  The StringnameX is a key value of the attribute setupInverterStrings.
  
  
  Example:
  attr <name> setupRoofTops eastroof=p1 southgarage=p2 S3=p3
  


• setupStringPeak <Stringname1>=<Peak> [<Stringname2>=<Peak> <Stringname3>=<Peak> ...]
  
  The DC peak power of the string "StringnameX" in kWp. The string name is a key value of the attribute setupInverterStrings.
  When using an AI-based API (e.g. Model VictronKiAPI), the peak powers of all existing strings are to be assigned as a sum to the string name KI-based.
  
  
  Examples:
  attr <name> setupStringPeak eastroof=5.1 southgarage=2.0 S3=7.2
  attr <name> setupStringPeak KI-based=14.3 (for AI based API)
  


• setupWeatherDevX
  
  Specifies the device or API for providing the required weather data (cloud cover, precipitation, etc.).
  The attribute 'setupWeatherDev1' specifies the leading weather service and is mandatory.
  If an Open-Meteo API is selected in the 'setupWeatherDev1' attribute, this Open-Meteo service is automatically set as the source of the radiation data (Attribute setupRadiationAPI).
  
  OpenMeteoDWD-API
  Open-Meteo is an open source weather API and offers free access for non-commercial purposes. No API key is required. Open-Meteo leverages a powerful combination of global (11 km) and mesoscale (1 km) weather models from esteemed national weather services. This API provides access to the renowned ICON weather models of the German Weather Service (DWD), which provide 15-minute data for short-term forecasts in Central Europe and global forecasts with a resolution of 11 km. The ICON model is a preferred choice for general weather forecast APIs when no other high-resolution weather models are available. The models DWD Icon D2, DWD Icon EU and DWD Icon Global models are merged into a seamless forecast. The comprehensive and clearly laid out API Documentation is available on the service's website.
  
  OpenMeteoDWDEnsemble-API
  This Open-Meteo API variant provides access to the DWD's global Ensemble Prediction System (EPS).
  The ensemble models ICON-D2-EPS, ICON-EU-EPS and ICON-EPS are seamlessly combined.
  Ensemble weather forecasts are a special type of forecasting method that takes into account the uncertainties in weather forecasting. They do this by running several simulations or models with slight differences in the starting conditions or settings. Each simulation, known as an ensemble member, represents a possible outcome of the weather. In this implementation, 40 ensemble members per weather feature are combined and the most probable result is used.
  
  OpenMeteoWorld-API
  As a variant of the Open Meteo service, the OpenMeteoWorld API provides the optimum forecast for a specific location worldwide. The OpenMeteoWorld API seamlessly combines weather models from well-known organizations such as NOAA (National Oceanic and Atmospheric Administration), DWD (German Weather Service), CMCC (Canadian) and ECMWF (European Centre for Medium-Range Weather Forecasts). The providers' models are combined for each location worldwide to produce the best possible forecast. The services and weather models are used automatically based on the location coordinates contained in the API call.
  
  DWD Device
  As an alternative to Open-Meteo, an FHEM 'DWD_OpenData' device can be used to supply the weather data.
  If no device of this type exists, at least one DWD_OpenData device must first be defined. (see DWD_OpenData Commandref).
  If more than one setupWeatherDevX is specified, the average of all weather stations is determined if the respective value was supplied and is numerical.
  Otherwise, the data from 'setupWeatherDev1' is always used as the leading weather device.
  At least these attributes must be set in the selected DWD_OpenData Device:
  
  

  forecastDays	1
  forecastProperties	TTT,Neff,RR1c,ww,SunUp,SunRise,SunSet
  forecastResolution	1
  forecastStation	<Station code of the evaluated DWD station>

  
  Note: If the latitude and longitude attributes are set in the global device, the sunrise and sunset result from this information.

Spotify

[EN DE]

The Spotify module enables you to control your Spotify (Connect) playback.
To be able to control your music, you need to authorize with the Spotify WEB API. To do that, a Spotify API application is required.
While creating the app, enter any redirect_uri. By default the module will use https://oskar.pw/ as redirect_uri since the site outputs your temporary authentification code.
It is safe to rely on this site because the code is useless without your client secret and only valid for a few minutes (important: you have to press the add and save button while adding the url).
If you want to use it, make sure to add it as redirect_uri to your app - however, you are free to use any other url and extract the code after signing in yourself.



Define

define <name> Spotify <client_id> <client_secret> [ <redirect_url> ]



Example: define Spotify Spotify f88e5f5c2911152d914391592e717738 301b6d1a245e4fe01c2f8b4efd250756


Once defined, open up your browser and call the URL displayed in AUTHORIZATION_URL, sign in with spotify and extract the code after being redirected.
If you get a redirect_uri mismatch make sure to either add https://oskar.pw/ as redirect url or that your url matches exactly with the one defined.
As soon as you obtained the code call set <name> code <code> - your state should change to connected and you are ready to go.



set <required> [ <optional> ]

Without a target device given, the active device (or default device if alwaysStartOnDefaultDevice is enabled) will be used.
You can also use the name of the target device instead of the id if it does not contain spaces - where it states <device_id / device_name> spaces are allowed.
If no default device is defined and none is active, it will use the first available device.
You can get a spotify uri by pressing the share button in the spotify (desktop) app on a track/playlist/album.


• findArtistByName
  finds an artist using its name and returns the result to the readings
• findTrackByName
  finds a track using its name and returns the result to the readings
• pause
  pause the current playback
• playArtistByName <artist_name> [ <device_id> ]
  plays an artist using its name (uses search)
• playContextByURI <context_uri> [ <nr_of_start_track> ] [ <device_id / device_name> ]
  plays a context (playlist, album or artist) using a Spotify URI
• playPlaylistByName <playlist_name> [ <device_id> ]
  plays any playlist by providing a name (uses search)
• playRandomTrackFromPlaylistByURI <playlist_uri> [ <limit> ] [ <device_id / device_name> ]
  plays a random track from a playlist (only considering the first <limit> songs)
• playSavedTracks [ <nr_of_start_track> ] [ <device_id / device_name> ]
  plays the saved tracks (beginning with track <nr_of_start_track>)
• playTrackByName <track_name> [ <device_id> ]
  finds a song by its name and plays it
• playTrackByURI <track_uri> [ <device_id / device_name> ]
  plays a track using a track uri
• repeat <track,context,off>
  sets the repeat mode: either one, all (meaning playlist or album) or off
• resume [ <device_id / device_name> ]
  resumes playback (on a device)
• seekToPosition <position>
  seeks to the position <position> (in seconds, supported formats: 01:20, 80, 00:20, 20)
• shuffle <off,on>
  sets the shuffle mode: either on or off
• skipToNext
  skips to the next track
• skipToPrevious
  skips to the previous track
• togglePlayback
  toggles the playback (resumes if paused, pauses if playing)
• transferPlayback [ <device_id> ]
  transfers the current playback to the specified device (or the next inactive device if not specified)
• update
  updates playback and devices
• volume <volume> [ <device_id> ]
  sets the volume
• volumeDown [ <step> ] [ <device_id / device_name> ]
  decreases the volume by step (if not set it uses volumeStep)
• volumeFade <volume> [ <duration> <step> ] [ <device_id> ]
  fades the volume
• volumeDown [ <step> ] [ <device_id / device_name> ]
  increases the volume by step (if not set it uses volumeStep)



Get

N/A



Attributes

• alwaysStartOnDefaultDevice
  always start new playback on the default device
  default: 0
• defaultPlaybackDeviceID
  the prefered device by its id or device name
  
• disable
  disables the device
  default: 0
• updateInterval
  the interval to update your playback status while no music is running (in seconds)
  default: 300
• updateIntervalWhilePlaying
  the interval to update your playback status while music is running (in seconds)
  default: 10
• volumeStep
  the value by which the volume is in-/decreased by default (in percent)
  default: 5

TA_CMI_JSON

[EN DE]

Define

define <name> TA_CMI_JSON <IP> <CAN-Node-Id> <Query-Params>

Defines a device that receives values from the CMI at the given IP for the CAN-device with the given CAN-Node-Id.
Query-Param defines, which values you want to read. Allowed values are I,O,D.
Example:
defmod cmi TA_CMI_JSON 192.168.4.250 1 <I,O,D>


It's mandatory to define which values should be mapped to readings.
Only mapped values will not be written to readings. (see Attributes for details)

Set

• fixwertAnalog
  Set Fixwert to an analog value. Example:
  
  set cmiNode fixwertAnalog <index> <value>
set cmiNode fixwertAnalog 3 64.0 will set Fixwert 3 to 64.0
• fixwertDigital
  Set Fixwert to a digital value. Also works for impulse values. Example:
  
  set cmiNode fixwertDigital <index> <value>
set cmiNode fixwertDigital 2 1 will set Fixwert 2 to On/Yes.
• fixwertImpuls
  Trigger an impulse to Fixwert. Example:
  
  set cmiNode fixwertImpuls <index> <value>
set cmiNode fixwertImpuls 3 1 will send an On-impulse to Fixwert 3.

Get

• update
  Triggers querying of values from the CMI. Please note that the request rate is limited to one query per minute.
• readOutputStates
  Reads Output states (eg Manual-On, Auto-Off) per defined output. Can be automated by setting outputStatesInterval.

Attributes

• readingNamesDL-Bus {index:reading-name}
  This maps received values from the DL-Bus to readings. eg 1:Flowrate_Solar 2:T.Solar_Backflow
• readingNamesInputs {index:reading-name}
  This maps received values from the Inputs to readings. eg 1:Flowrate_Solar 2:T.Solar_Backflow
• readingNamesOutputs {index:reading-name}
  This maps received values from the Outputs to readings. eg 1:Flowrate_Solar 2:T.Solar_Backflow
• readingNamesLoggingAnalog {index:reading-name}
  This maps received values from Analog Logging to readings. zB eg 1:Flowrate_Solar 2:T.Solar_Backflow
• readingNamesLoggingDigital {index:reading-name}
  This maps received values from Digital Logging to readings. zB eg 1:Flowrate_Solar 2:T.Solar_Backflow
• includeUnitReadings [0:1]
  Adds another reading per value, which just contains the according unit of that reading.
• includePrettyReadings [0:1]
  Adds another reading per value, which contains value plus unit of that reading.
• interval
  Query interval in seconds. Minimum query interval is 60 seconds.
• outputStatesInterval
  Request interval in seconds for getting output states.
• prettyOutputStates [0:1]
  If set, generates a reading _State_Pretty for output states (eg Auto-On, Manual-Off)
• setList
  Used to define Set shortcuts for fixwertAnalog, Digital, and Impuls. eg Light_on:noArg fixwertImpuls 3 1
  The second parameter (for the value) can be left out and directly read from the input field. eg Water_Temperature fixwertAnalog 7
  can be used like set cmiNode Water_Temperature 55.0.
• username
  Username for querying the JSON-API. Needs to be either admin or user privilege.
• password
  Password for querying the JSON-API.

Readings

Readings will appear according to the mappings defined in Attributes.

TBot_List

[EN DE]

This module connects for allowing inline keyboard interactions between a telegramBot and PostMe lists.

Define
define <name> TBot_List <PostMe device> <listname>

Defines a TBot_List device, which will allow interaction between the telegrambot and the postme device

Example: define testtbotlist TBot_List testposteme testlist


Note: The module relies on events send from the corresponding TelegramBot devices. Specifically changes to the readings sentMsgId and msgReplyMsgId are required to enable to find the corresponding message ids to be able to modify messages. This needs to be taken into account when using the attributes event-on-*-reading on the TelegramBot device.




Set
set <name> <what> [<value>]
where <what> / <value> is one of


• start <telegrambot name> [ <peerid> [ <chatid> ] ]
  Initiate a new dialog for the given peer (or the last peer sending a message on the given telegrambot - if communication should happen in a group then both chatid with the groupid and peerid with the user id need to be specified)
• silentStart ...
  Similar to start with same parameters to start the dialog silently (no notification)
• end <telegrambot name> <peerid>
  Finalize a new dialog for the given peer on the given telegrambot


Get
get <name> <what> [<value>]
where <what> / <value> is one of


• queryAnswer <telegrambot name> <peerid> <queryData>
  Get the queryAnswer for the given query data in the dialog (will be called internally by the telegramBot on receiving querydata)
• textList
  Returns a multiline string containing the list elements or
• list
  Returns a multiline string containing the list elements or an empty String


Attributes


• telegramBots <list of telegramBot names separated by space>
  This attribute takes the names of telegram bots, that are monitored by this Tbot_List device
• optionDouble <1 or 0>
  Specify if the list shall be done in two columns (double=1) or in a single column (double=0 or not set).
• allowedPeers <list of peer ids>
  If specifed further restricts the users for the given list to these peers. It can be specifed in the same form as in the telegramBot msg command but without the leading @ (so ids will be just numbers).
• handleUnsolicited <1 or 0>
  If set to 1 and new messages are sent in a chat where a dialog of this list is active the bot will ask if an entry should be added. This helps for accidential messages without out first pressing the "add" button.
• confirmDelete <1 or 0>
  If set to 1 the bot will ask for a confirmation if an entry should be deleted. This is the default. With a value of 0 the additional confirmation will not be requested.
• deleteOnly <1 or 0>
  If set to 1 the bot will only allow deletion of entries or the complete list (no new entries or entry text can be changed - neither sorting or similar will be possible). Default is 0 (all changes allowed).
• acknowledge <text>
  If set entries can be marked as done (acknowledged) adding the corresponding prefix to the entry text (e.g. "DONE" will add "DONE ->" to the entry when marked done).
• categories <list of categories separated by ,>
  Allows assigning different categories to entries. When modifying single entries each category will be separately offered for assigning to the entry. Assigning another category from the list means the former category assignment ill be removed. Entries with categories assigned are prefixed with the category. So for category "ABC" the entry will be prefixed with "ABC -> ".


Readings
• currently none

TCM

[EN DE]

The TCM module serves an USB or TCP/IP connected TCM 120 or TCM 310x, TCM 410J, TCM 515 EnOcean Transceiver module. These are mostly packaged together with a serial to USB chip and an antenna, e.g. the BSC BOR contains the TCM 120, the USB 300 from EnOcean and the EUL from busware contains a TCM 310 or TCM 515. See also the datasheet available from www.enocean.com.
As the TCM 120 and the TCM 310, TCM 410J, TCM 515 speak completely different protocols, this module implements 2 drivers in one. It is the "physical" part for the EnOcean module.

Please note that EnOcean repeaters also send Fhem data telegrams again. Use attr <name> blockSenderID own to block receiving telegrams with TCM SenderIDs.
The address range used by your transceiver module, can be found in the parameters BaseID and LastID.

The transceiver moduls do not always support all commands. The supported range of commands depends on the hardware and the firmware version. A firmware update is usually not provided.

Eltako RS485 bus
The TCM module enables also a wired connection to Eltako actuators over the Eltako RS485 bus in the switchboard or distribution box via Eltako FGW14 RS232-RS485 gateway modules. These actuators are linked to an associated wireless antenna module (FAM14) on the bus. The FAM14 device frequently polls the actuator status of all associated devices if the FAM14 operating mode rotary switch is on position 4. Therefore, actuator states can be retrieved more reliable, even after any fhem downtime, when switch events or actuator confirmations could not have been tracked during the downtime. As all actuators are polled approx. every 1-2 seconds, it should be avoided to use event-on-update-reading. Use instead either event-on-change-reading or event-min-interval. The Eltako bus uses the EnOcean Serial Protocol version 2 (ESP2). For this reason, a FGW14 can be configured as a ESP2. The attribute comType must be set to RS485.

Multi-transceiver operation
It is possible to operate multiple transceivers in one Fhem instance in parallel. EnOcean repeaters meet the usual requirements for increasing range in homes much more easily than a multi-transceiver instance. It is interesting to operate several transceivers but with extensive building complexes. In addition, the radio channel utilization can be reduced compared to the use of several repeaters when self-contained spatial zones are formed. After all, multiple transceivers can increase the number of available SenderIDs in Fhem.

Within an Fhem installation with multiple transceivers, one of these transceivers sends the outgoing telegrams. The transceiver is assigned to IODev when an EnOcean device is set up. One of the enabled transceivers can be specifically selected as the transmitting device (IODev) for manual setup of EnOcean devices. For this purpose, the attribute

attr <name> assignIODev yes
must be set.

For teach-in sensors or actuators, the desired transceiver must be set by

set <name> teach <t/s>
into learning mode.

Incoming telegrams are received by all transceivers. Duplicates are determined and suppressed by the fingerprint function. This function must be used for each transceiver using the

attr <name> fingerprint on
activated. Furthermore, the global attribute must be

attr global dupTimeout 0.6
or larger. The attributes are set automatically if they have not already been manually defined.

Transceivers on remote servers have been tested with the Linux service ser2net. For example, ser2net can be set up on a Raspberry PI Remote server for a transceiver on the /dev/ttyUSB0@57600 USB port (8, 'none', 1) in the following steps:

Package provisioning

sudo apt install ser2net
Configuration in the file: /etc/ser2net.conf

7000:raw:0:/dev/ttyUSB0:57600 8DATABITS NONE 1STOPBIT HANGUP_WHEN_DONE
Program start for a test

sudo ser2net -n
Automatically boot (insert script /etc/init.d/ser2net into startup procedure)

sudo update-rc.d ser2net defaults
Take program from the autostart

sudo update-rc.d -f ser2net remove

On the remote server, ser2net and Fhem should not be active in parallel. During Fhem start, the autocreate function may inadvertently integrate the transceiver into Fhem and then errors occur.

On the target system, the transceiver is then connected to the IP address of the remote server via

define TCM_Remote TCM ESP3 <ip1>.<ip2>.<ip3>.<ip4>:7000
set up.

Only ESP3 transceivers have been tested.

Define
define <name> TCM [ESP2|ESP3] <device>

First you have to specify the type of the EnOcean Transceiver Chip, i.e either ESP2 for the TCM 120 or ESP3 for the TCM 310x, TCM 410J, TCM 515, USB 300, USB400J, USB 500.

device can take the same parameters (@baudrate, @directio, TCP/IP, none), but you probably have to specify the baudrate: the TCM 120 should be opened with 9600 Baud, the TCM 310 and TCM 515 with 57600 baud. For Eltako FGW14 devices, type has to be set to 120 and the baudrate has to be set to 57600 baud if the FGW14 operating mode rotary switch is on position 6.

Example:
define BscBor TCM ESP2 /dev/ttyACM0@9600
define FGW14 TCM ESP2 /dev/ttyS3@57600
define TCM310 TCM ESP3 /dev/ttyACM0@57600
define TCM310 TCM ESP3 COM1@57600 (Windows)


Set

ESP2 (TCM 120)

• baseID [FF000000 ... FFFFFF80]
  Set the BaseID.
  Note: The firmware executes this command only up to then times to prevent misuse.
• modem_off
  Deactivates TCM modem functionality
• modem_on [0000 ... FFFF]
  Activates TCM modem functionality and sets the modem ID
• reset
  Reset the device
• sensitivity [00|01]
  Set the TCM radio sensitivity: low = 00, high = 01
• sleep
  Enter the energy saving mode
• teach <t/s>
  Set Fhem in learning mode, see learningMode and learningDev.
  The command is always required for UTE and to teach-in bidirectional actuators e. g. EEP 4BS (RORG A5-20-XX), see Teach-In / Teach-Out.
• wake
  Wakes up from sleep mode

For details see the TCM 120 User Manual available from www.enocean.com.


ESP3 (TCM 310x, TCM 410J, TCM 515, USB 300, USB400J, USB 515)

• baseID [FF000000 ... FFFFFF80]
  Set the BaseID.
  Note: The firmware executes this command only up to then times to prevent misuse.
• baudrate [00|01|02|03]
  Modifies the baud rate of the EnOcean device.
  baudrate = 00: 56700 baud (default)
  baudrate = 01: 115200 baud
  baudrate = 02: 230400 baud
  baudrate = 03: 460800 baud
• bist
  Perform Flash BIST operation (Built-in-self-test).
• >filterAdd Add filter to filter list. Description of the filter parameters and examples, see EnOcean Serial Protocol 3 (ESP3)
• filterDel <FilterType><FilterValue>
  Del filter from filter list. Description of the filter parameters, see EnOcean Serial Protocol 3 (ESP3)
• filterDelAll
  Del all filter from filter list.
• filterEnable <FilterON/OFF><FilterOperator>
  Enable/Disable all supplied filters. Description of the filter parameters, see EnOcean Serial Protocol 3 (ESP3)
• init
  Initialize serial communication and transceiver configuration
• maturity [00|01]
  Waiting till end of maturity time before received radio telegrams will transmit: radio telegrams are send immediately = 00, after the maturity time is elapsed = 01
• mode [00|01]
  mode = 00: Compatible mode - ERP1 - gateway uses Packet Type 1 to transmit and receive radio telegrams
  mode = 01: Advanced mode - ERP2 - gateway uses Packet Type 10 to transmit and receive radio telegrams (for FSK products with advanced protocol)
• noiseThreshold [2E|2F|30|31|32|33|34|35|36|37|38]
  Modifies the noise threshold of the EnOcean device.
  noiseThreshold = 2E: -100 dBm
  noiseThreshold = 2F: -99 dBm
  noiseThreshold = 30: -98 dBm
  noiseThreshold = 31: -97 dBm
  noiseThreshold = 32: -96 dBm (default)
  noiseThreshold = 33: -95 dBm
  noiseThreshold = 34: -94 dBm
  noiseThreshold = 35: -93 dBm
  noiseThreshold = 36: -92 dBm
  noiseThreshold = 37: -91 dBm
  noiseThreshold = 38: -90 dBm
• pskAdd [16 byte hex]
  Set the pre-shared key (psk) for secure teach-in. The key is stored until the Fhem restart.
• pskDel
  Delete the pre-shared key (psk) for secure teach-in.
• remanCode [00000000-FFFFFFFF]
  Sets secure code to unlock Remote Management functionality by radio.
• remanRepeating [00|01]
  Select if REMAN telegrams originating from this module can be repeated: off = 00, on = 01.
• reset
  Reset the device
• resetEvents
  Reset generated events
• repeater [0000|0101|0102]
  Set Repeater Level: off = 0000, 1 = 0101, 2 = 0102.
• sleep <t/10 ms> (Range: 00000000 ... 00FFFFFF)
  Enter the energy saving mode
• smartAckLearn <t/s>
  Set Fhem in Smart Ack learning mode.
  The post master fuctionality must be activated using the command smartAckMailboxMax in advance.
  The simple learnmode is supported, see smartAckLearnMode
  A device, which is then also put in this state is to paired with Fhem. Bidirectional learn in for 4BS, UTE and Generic Profiles are supported.
  t/s is the time for the learning period.
• smartAckMailboxMax 0..20
  Enable the post master fuctionality and set amount of mailboxes available, 0 = disable post master functionality. Maximum 28 mailboxes can be created. This upper limit is for each firmware restricted and may be smaller.
• startupDelay [00-FF]
  Sets the startup delay [10ms]: the time before the system initializes.
• subtel [00|01]
  Transmitting additional subtelegram info: Enable = 01, Disable = 00
• teach <t/s>
  Set Fhem in learning mode for RBS, 1BS, 4BS, GP, STE and UTE teach-in / teach-out, see learningMode and learningDev.
  The command is always required for STE, GB, UTE and to teach-in bidirectional actuators e. g. EEP 4BS (RORG A5-20-XX), see Teach-In / Teach-Out.

For details see the EnOcean Serial Protocol 3 (ESP3) available from www.enocean.com.


Get

TCM 120

• baseID
  Get the BaseID. You need this command in order to control EnOcean devices, see the EnOcean paragraph.
• modem_status
  Requests the current modem status.
• sensitivity
  Get the TCM radio sensitivity, low = 00, high = 01
• version
  Read the device SW version / HW version, chip-ID, etc.

For details see the TCM 120 User Manual available from www.enocean.com.


TCM 310

• baseID
  Get the BaseID. You need this command in order to control EnOcean devices, see the EnOcean paragraph.
• dutycycleLimit
  Read actual duty cycle limit values.
• filter
  Get supplied filters. Description of the filter parameters, see EnOcean Serial Protocol 3 (ESP3)
• freqencyInfo
  Reads Frequency and protocol of the Device, see EnOcean Serial Protocol 3 (ESP3)
• getFreeID
  Get free Transceiver SenderIDs.
• getUsedID
  Get used Transceiver SenderIDs.
• numSecureDev
  Read number of teached in secure devices.
• remanRepeating
  REMAN telegrams originating from this module can be repeated: off = 00, on = 01.
• repeater
  Read Repeater Level: off = 0000, 1 = 0101, 2 = 0102.
• smartAckLearnMode
  Get current smart ack learn mode
  Enable: 00|01 = off|on
  Extended: 00|01|02 = simple|advance|advanceSelectRep
• smartAckLearnedClients
  Get information about the learned smart ack clients
• stepCode
  Reads Hardware Step code and Revision of the Device, see EnOcean Serial Protocol 3 (ESP3)
• version
  Read the device SW version / HW version, chip-ID, etc.

For details see the EnOcean Serial Protocol 3 (ESP3) available from www.enocean.com.


Attributes
• assignIODev <no|yes>, [assignIODev] = no is default.
  Transceiver used as IO device (IODev) for manually set up EnOcean devices.
• blockSenderID <own|no>, [blockSenderID] = own is default.
  Block receiving telegrams with a TCM SenderID sent by repeaters.
• dummy
• baseID <FF000000 ... FFFFFF80>, [baseID] = is default.
  Set Transceiver baseID and override automatic allocation. Use this attribute only if the IODev does not allow automatic allocation. The BaseID must be set in increments of 0x80.
• fingerprint <off|on>, [fingerprint] = off is default.
  Activate the fingerprint function. The fingerprint function eliminates multiple identical data telegrams received via different TCM modules.
  The function must be activated for each TCM module.
• comModeUTE <auto|biDir|uniDir>, [comModeUTE] = auto is default.
  Presetting the communication method of actuators that be taught using the UTE teach-in. The automatic selection of the communication method should only be overwrite manually, if this is explicitly required in the operating instructions of the actuator. The parameters should then be immediately re-set to "auto".
• comType <TCM|RS485>, [comType] = TCM is default.
  Type of communication device
• do_not_notify
• learningDev <all|teachMsg>, [learningDev] = teachMsg is default.
  Learning method for automatic setup of EnOcean devices:
  [learningDev] = all: All incoming telegrams generate device definitions
  [learningDev] = teachMsg: Only incoming learning telegrams generate device definitions. RPS telegrams always create new devices due to principle.
  
• learningMode <always|demand|nearfield>, [learningMode] = demand is default.
  Learning method for automatic setup of EnOcean devices:
  [learningMode] = always: Teach-In/Teach-Out telegrams always accepted, with the exception of bidirectional devices
  [learningMode] = demand: Teach-In/Teach-Out telegrams accepted if Fhem is in learning mode, see also set <IODev> teach <t/s>
  [learningMode] = nearfield: Teach-In/Teach-Out telegrams accepted if Fhem is in learning mode and the signal strength RSSI >= -60 dBm.
• msgCounter <off|on>, [msgCounter] = off is default.
  Counts the received and sent messages in the last day, last hour, and minute, see internals MsgRcvPerDay, MsgSndPerDay, MsgRcvPerHour, MsgSndPerHour, MsgRcvPerMin MsgSndPerMin.
• rcvIDShift <00000080 ... FFFFFF80>, [rcvIDShift] = is default.
  Shift the address range of the received data telegrams. The attribute is supported only for the ESP2 protocol. The rcvIDShift must be set in increments of 0x80.
• sendInterval <0 ... 250>
  ESP2: [sendInterval] = 100 ms is default.
  ESP3: [sendInterval] = 15 ms is default.
  Smallest interval between two sending telegrams
• smartAckLearnMode <simple|advance|advanceSelectRep>
  select Smart Ack learn mode; only simple supported by Fhem
• smartAckMailboxMax <0 ... 28>
  Amount of mailboxes available, 0 = disable post master functionality. Maximum 28 mailboxes can be created. This upper limit is for each firmware restricted and may be smaller.
• verbose



Generated events
• baseID <transceiver response>
• maturity 00|01
• modem_status <transceiver response>
• numSecureDev <transceiver response>
• repeater 0000|0101|0102
• sensitivity 00|01
• version <transceiver response>
• state: opend|initialized

TEK603

[EN DE]

The TEK603 is a fhem module for the Tekelek TEK603 Eco Monitor a liquid level monitor designed for residential and small commercial applications. It works in conjunction with a TEK653 Sonic transmitter mounted on the top of the tank.


Prerequisites
The module requires the perl module Digest::CRC
On a debian based system the module can be installed with
sudo apt-get install libdigest-crc-perl


Define
define <name> TEK603 /dev/ttyUSBx

Defines an TEK603 Eco Monitor device connected to USB.

Examples:
define OelTank TEK603 /dev/ttyUSB0



define <name> TEK603 hostnameorip:port

Defines an TEK603 Eco Monitor device via ethernet on a remote host running ser2net.

Examples:
define OelTank TEK603 somehost:23000


Readings
• Time
  TEK603 internal Time
• Temperature
  Sensor Temperature
• Ullage
  Sensor Measured Ullage
• RemainingUsableLevel
  This is the usable level, with deductions due to the sensor offset and outlet height. (Liters)
• RemainingUsablePercent
  This is the usable level in percent (calculated from RemainingUsableLevel and TotalUsableCapacity)
• TotalUsableCapacity
  This is the usable volume, with deductions due to the sensor offset and outlet height. (Liters)

THINKINGCLEANER

[EN DE]

This module provides support for ThinkingCleaner hardware add-on module for Roomba cleaning robots.

Define

define <name> THINKINGCLEANER <IP-ADRESS or HOSTNAME>

Example:

define Robby THINKINGCLEANER 192.168.0.35





Set
• cleaningDelay - sets cleaning delay in minutes when using on-delayed cleaning
• damageProtection - turns damage protection on or off while sending remotrControl commands (on/off)
• dock - Send Roomba back to it's docking station
• locate - Play sound to help finding Roomba
• off - Stop/pause cleaning
• on - Start cleaning
• on-delayed - Delayed start for cleaning according to cleaningDelay
• on-max - Start cleaning with max setting
• on-spot - Start spot cleaning
• power - Turn Roomba on or off (on/off)
• remoteControl - Send remote control commands
• scheduleAdd - Add new cleaning schedule
• scheduleDel - Delete existing cleaning schedule
• scheduleMod - Modify existing cleaning schedule
• statusRequest - Update device readings
• toggle - Toogle between on and off
• undock - Let Roomba leave it's docking station
• vacuumDrive - Enable or disable vaccuming during remoteControl commands (on/off)


Attributes
• pollInterval - Set regular polling interval in minutes (defaults to 45s)
• pollMultiplierCleaning - Change interval multiplier used during cleaning (defaults to 0.5)
• pollMultiplierWebhook - Change interval multiplier used during standby and webhook being enabled (defaults to 2)
• webhookFWinstance - Set FHEMWEB instance for incoming webhook events used by Roomba (mandatory for webhook)
• webhookHttpHostname - Set HTTP Hostname or IP address for incoming webhook events used by Roomba (mandatory for webhook)
• webhookPort - Use different port instead of what defined FHEMWEB instance uses (optional)

THRESHOLD

[EN DE]

Diverse controls can be realized by means of the module by evaluation of sensor data. In the simplest case, this module reads any sensor that provides values in decimal and execute FHEM/Perl commands, if the value of the sensor is higher or lower than the threshold value. A typical application is the simulation of a thermostat or humidistat.

With one or more such modules, complex systems can be implemented for heating, cooling, ventilation, dehumidification or shading. But even simple notification when crossing or falling below a specific value can be easily realized. It no if-statements in Perl or notify definitions need to be made. This leads to quickly create and clear controls, without having to necessarily go into the Perl matter.
Some application examples are at the end of the module description.

According to the definition of a module type THRESHOLD eg:

define <name> THRESHOLD <sensor> <actor>

It is controlled by setting a desired value with:

set <name> desired <value>

The module begins with the control system only when a desired value is set!

The specification of the desired value may also come from another sensor. This control may take place by the comparison of two sensors.

Likewise, any wall thermostats can be used (eg, HM, MAX, FHT) for the definition of the reference temperature.

The switching behavior can also be influenced by another sensor or sensor group.

The combination of multiple THRESHOLD modules together is possible, see examples below.

Define

define <name> THRESHOLD <sensor>:<reading>:<hysteresis>:<target_value>:<offset> AND|OR <sensor2>:<reading2>:<state> <actor>|<cmd1_gt>|<cmd2_lt>|<cmd_default_index>|<state_cmd1_gt>:<state_cmd2_lt>|<state_format>



• sensor
  a defined sensor in FHEM


• reading (optional)
  reading of the sensor, which includes a value in decimal
  default value: temperature


• hysteresis (optional)
  Hysteresis, this provides the threshold_min = desired_value - hysteresis
  default value: 1 at temperature, 10 at huminity


• target_value (optional)
  number: Initial value, if no value is specified, it must be set with "set desired value".
  else:<sensorname>:<reading>, an additional sensor can be specified, which sets the target value dynamically.
  default value: no value


• offset (optional)
  Offset to desired value
  This results:
  threshold_max = desired_value + offset and threshold_min = desired_value - hysteresis + offset
  Defaultwert: 0
  



• AND|OR (optional)
  logical operator with an optional second sensor
  


• sensor2 (optional, nur in Verbindung mit AND oder OR)
  the second sensor


• reading2 (optional)
  reading of the second sensor
  default value: state


• state (optional)
  state of the second sensor
  default value: open



• actor (optional)
  actor device defined in FHEM


• cmd1_gt (optional)
  FHEM/Perl command that is executed, if the value of the sensor is higher than desired value and/or the value of sensor 2 is matchted. @ is a placeholder for the specified actor.
  default value: set actor off, if actor defined


• cmd2_lt (optional)
  FHEM/Perl command that is executed, if the value of the sensor is lower than threshold_min or the value of sensor 2 is not matchted. @ is a placeholder for the specified actor.
  default value: set actor on, if actor defined


• cmd_default_index (optional)
  Index of command that is executed after setting the desired value until the desired value or threshold_min value is reached.
  0 - no command
  1 - cmd1_gt
  2 - cmd2_lt
  default value: 2, if actor defined, else 0
  


• state_cmd1_gt (optional, is defined as an attribute at the same time and can be changed there)
  state, which is displayed, if FHEM/Perl-command cmd1_gt was executed. If state_cmd1_gt state ist set, other states, such as active or deactivated are suppressed.
  default value: none


• state_cmd2_lt (optional, is defined as an attribute at the same time and can be changed there)
  state, which is displayed, if FHEM/Perl-command cmd1_gt was executed. If state_cmd1_gt state ist set, other states, such as active or deactivated are suppressed.
  default value: none


• state_format (optional, is defined as an attribute at the same time and can be changed there)
  Format of the state output: arbitrary text with placeholders.
  Possible placeholders:
  _m: mode
  _dv: desired_value
  _s1v: sensor_value
  _s2s: sensor2_state
  _sc: state_cmd
  Default value: _m _dv _sc, _sc when state_cmd1_gt and state_cmd2_lt set without actor.
  
  

Examples:

Example for heating:

It is heated up to the desired value of 20. If the value below the threshold_min value of 19 (20-1) the heating is switched on again.

define thermostat THRESHOLD temp_sens heating

set thermostat desired 20


Example for heating with window contact:

define thermostat THRESHOLD temp_sens OR win_sens heating


Example for heating with multiple window contacts:

define W_ALL structure W_type W1 W2 W3 ....
attr W_ALL clientstate_behavior relative
attr W_ALL clientstate_priority open closed

then:

define thermostat THRESHOLD S1 OR W_ALL heating


More examples for dehumidification, air conditioning, watering:

define hygrostat THRESHOLD hym_sens:humidity dehydrator|set @ on|set @ off|1
define hygrostat THRESHOLD hym_sens:humidity AND Sensor2:state:close dehydrator|set @ on|set @ off|1
define thermostat THRESHOLD temp_sens:temperature:1 aircon|set @ on|set @ off|1
define thermostat THRESHOLD temp_sens AND Sensor2:state:close aircon|set @ on|set @ off|1
define hygrostat THRESHOLD hym_sens:humidity:20 watering|set @ off|set @ on|2


It can also FHEM/perl command chains are specified:

Examples:

define thermostat THRESHOLD sensor |set Switch1 on;;set Switch2 on|set Switch1 off;;set Switch2 off|1
define thermostat THRESHOLD sensor alarm|{Log 2,"value is exceeded"}|set @ on;;set Switch2 on
define thermostat THRESHOLD sensor ||{Log 2,"value is reached"}|


Examples of the reference input by another sensor:

Hot water circulation: The return temperature is 5 degrees (offset) below the hot water tank temperature and can vary by up to 4 degrees (hysteresis).

define TH_water_circulation THRESHOLD return_w:temperature:4:water_storage:temperature:-5 circualtion_pump

Control of heating by a wall thermostat with acquisition the desired and actual temperature from the wall thermostat:

define TH_heating THRESHOLD WT:measured-temp:1:WT:desired-temp heating

set TH_heating desired 17 overrides the desired-values from the wall thermostat until called set TH_heating external


Examples of customized state output:

define thermostat THRESHOLD sensor aircon|set @ on|set @ off|2|on:off


Example of state output (eg for state evaluation in other modules) without executing code:

define thermostat THRESHOLD sensor:temperature:0:30

by reason of default values​​:

define thermostat THRESHOLD sensor:temperature:0:30||||off:on|_sc


Example of combining several THRESHOLD modules together:

It should be heated when the room temperature drops below 21 degrees and the outside temperature is below 15 degrees:

define TH_outdoor THRESHOLD outdoor:temperature:0:15
define TH_room THRESHOLD indoor OR TH_outdoor:state:off heating
set TH_room desired 21


An example of time-dependent heating in combination with DOIF module:

define TH_room THRESHOLD T_living_room heating
define di_room DOIF ([05:30-23:00|8] or [07:00-23:00|7]) (set TH_room desired 20) DOELSE (set TH_room desired 18)


Examples of customized state output:

State output: <mode> <state_cmd> <desired_value> <sensor_value>

define TH_living_room THRESHOLD T_living_room heating|set @ off|set @ on|2|off:on|_m _sc _dv _s1v

or

define TH_living_room THRESHOLD T_living_room heating
attr TH_living_room state_cmd1_gt off
attr TH_living_room state_cmd2_lt on
attr TH_living_room state_format _m _sc _dv _s1v

Set

• set <name> desired <value>
Set the desired value. If no desired value is set, the module is not active.


• set <name> deactivated <command>
Module is disabled.
  <command> is optional. It can be "cmd1_gt" or "cmd2_lt" passed in order to achieve a defined state before disabling the module.


• set <name> active <value>
Module is activated. If under target_value a sensor for reference input has been defined, the current setpoint will be inhibited until set "set external".


• set <name> externel
Module is activated, reference input comes from the target sensor, if a sensor has been defined under target_value.
  


• set <name> hysteresis <value>
Set hysteresis value.


• set <name> offset <value>
Set offset value.
  Defaultwert: 0


• set <name> cmd1_gt
  Executes the command defined in cmd1_gt.
  


• set <name> cmd2_lt
  Executes the command defined in cmd2_lt.
  

Get

N/A

Attributes

• disable
• loglevel
• state_cmd1_gt
• state_cmd2_lt
• state_format
• number_format
The specified format is used in the state for formatting desired_value (_dv) and Sensor_value (_s1v) using the sprintf function.
The default value is "% .1f" to one decimal place. Other formatting, see Formatting in the sprintf function in the Perldokumentation.
If the attribute is deleted, numbers are not formatted in the state.

• target_func
Here, a Perl expression used to calculate a target value from a value of the external sensor.
The sensor value is given as "_tv" in the expression.
Example:
attr TH_heating target_func -0.578*_tv+33.56

• setOnDeactivated
Command to be executed before deactivating. Possible values: cmd1_gt, cmd2_lt

• desiredActivate
If the attribute is set to 1, a disabled module is automatically activated by "set ... desired ". "set ... active" is not needed in this case.

THZ

[EN DE]

THZ module: comunicate through serial interface RS232/USB (eg /dev/ttyxx) or through ser2net (e.g 10.0.x.x:5555) with a Tecalor/Stiebel Eltron heatpump.
Tested on a THZ303/Sol (with serial speed 57600/115200@USB) and a THZ403 (with serial speed 115200) with the same Firmware 4.39.
Tested on a LWZ404 (with serial speed 115200) with Firmware 5.39.
Tested on fritzbox, nas-qnap, raspi and macos.
Implemented: read of status parameters and read/write of configuration parameters. A complete description can be found in the 00_THZ wiki http://www.fhemwiki.de/wiki/Tecalor_THZ_Heatpump

Define
define <name> THZ <device>

device can take the same parameters (@baudrate, @directio, TCP/IP, none) like the CUL, e.g 57600 baud or 115200.
Example: direct connection
define Mytecalor THZ /dev/ttyUSB0@115200

or network connection (like via ser2net)

define Myremotetecalor THZ 192.168.0.244:2323


define Mythz THZ /dev/ttyUSB0@115200
define FileLog_Mythz FileLog ./log/Mythz-%Y.log Mythz
attr Mythz event-min-interval s.*:4800
attr Mythz event-on-change-reading .*
attr Mythz interval_sDHW 400
attr Mythz interval_sElectrDHWDay 2400
attr Mythz interval_sElectrDHWTotal 43200
attr Mythz interval_sGlobal 400
attr Mythz interval_sHC1 400
attr Mythz interval_sHeatDHWDay 2400
attr Mythz interval_sHeatDHWTotal 43200
attr Mythz interval_sHeatRecoveredDay 2400
attr Mythz interval_sHeatRecoveredTotal 43200
attr Mythz interval_sHistory 86400
attr Mythz interval_sLast10errors 86400
attr Mythz userReadings insideSetTemp:sHC1.* {THZ_Val("sHC1",21)}, insideTemp:sHC1.* {THZ_Val("sHC1",27)}, AussenTemp:sGlobal.* {THZ_Val("sGlobal",1)}
attr Mythz room pompa
attr FileLog_Mythz room pompa


If the attributes interval_XXXX are not defined (or 0 seconds), their internal polling is disabled.
This module is starting to support older firmware 2.06 or newer firmware 5.39; the following attribute adapts decoding


attr Mythz firmware 2.06

attr Mythz firmware 5.39


If no attribute firmware is set, it is assumed your firmware is compatible with 4.39.
A backup function has been implemented
get Mythz zBackupParameters
The command saves all pXXX in a backupfile with a special text format. All (or some) parameters can be easily restored with one copy&paste from the backupfile in a telnet fhem session.

TPLinkHS110

[EN DE]

Define define <name> TPLinkHS110 <ip/hostname>

Defines a TP-Link HS100 or HS110 wifi-controlled switchable power outlet.
The difference between HS100 and HS110 is, that the HS110 provides realtime measurments of
power, current and voltage.
This module automatically detects the modul defined and adapts the readings accordingly.


This module does not implement all functions of the HS100/110.
Currently, all parameters relevant for running the outlet under FHEM are processed.
Writeable are only "On", "Off" and the nightmode (On/Off) (Nightmode: the LEDs of the outlet are switched off).
Further programming of the outlet should be done by TPLinks app "Kasa", which funtionality is partly redundant
with FHEMs core functions.

Attributs

• interval: The interval in seconds, after which FHEM will update the current measurements. Default: 300s
An update of the measurements is done on each switch (On/Off) as well.
• timeout: Timeout in seconds used while communicationg with the outlet. Default: 1s
Warning:: the timeout of 1s is chosen fairly aggressive. It could lead to errors, if the outlet is not answerings the requests within this timeout.
Please consider, that raising the timeout could mean blocking the whole FHEM during the timeout!
• disable: The execution of the module is suspended. Default: no.
Warning: if your outlet is not on or not connected to the wifi network, consider disabling this module by the attribute "disable". Otherwise the cyclic update of the outlets measurments will lead to blockings in FHEM.

Requirements

This module uses the follwing perl-modules:


• Perl Module: IO::Socket::INET
• Perl Module: IO::Socket::Timeout

TRAFFIC

[EN DE]

TRAFFIC - google maps directions module

This FHEM module collects and displays data obtained via the google maps directions api
requirements:
perl JSON module
perl LWP::SIMPLE module
perl MIME::Base64 module
Google maps API key

Features:

• get distance between start and end location
• get travel time for route
• get travel time in traffic for route
• define additional waypoints
• calculate delay between travel-time and travel-time-in-traffic
• choose default language
• disable the device
• 5 log levels
• get outputs in seconds / meter (raw_data)
• state of google maps returned in error reading (i.e. The provided API key is invalid)
• customize update interval (default 3600 seconds)
• calculate ETA with localtime and delay
• configure the output readings with attribute outputReadings, text, min sec
• configure the state-reading
• optionally display the same route in return
• one-time-burst, specify the amount and interval between updates
• different Travel Modes (driving, walking, bicycling and transit)
• flexible update schedule
• integrated Map to visualize configured route or embed to external GUI


Define:

define <name> TRAFFIC <YOUR-API-KEY> [UPDATE-INTERVAL]

example:
define muc2berlin TRAFFIC ABCDEFGHIJKLMNOPQRSTVWYZ 600



Attributes:
• "start_address" - Street, zipcode City (mandatory)
• "end_address" - Street, zipcode City (mandatory)
• "raw_data" - 0:1
• "alternatives" - 0:1, include alternative routes into readings and Map
• "language" - de, en etc.
• "waypoints" - Lat, Long coordinates, separated by |
• "returnWaypoints" - Lat, Long coordinates, separated by |
• "disable" - 0:1
• "stateReading" - name the reading which will be used in device state
• "outputReadings" - define what kind of readings you want to get: text, min, sec, average
• "updateSchedule" - define a flexible update schedule, syntax <starthour>-<endhour> [<day>] <seconds> , multiple entries by sparated by |
  example: 7-9 1 120 - Monday between 7 and 9 every 2minutes
  example: 17-19 120 - every Day between 17 and 19 every 2minutes
  example: 6-8 1 60|6-8 2 60|6-8 3 60|6-8 4 60|6-8 5 60 - Monday till Friday, 60 seconds between 6 and 8 am
• "travelMode" - default: driving, options walking, bicycling or transit
• "GoogleMapsStyle" - choose your colors from: default,silver,dark,night
• "GoogleMapsSize" - Map size in pixel, <width>,<height>
• "GoogleMapsCenter" - Lat, Long coordinates of your map center, spearated by ,
• "GoogleMapsZoom" - sets your map zoom level
• "GoogleMapsStroke" - customize your map poly-strokes in color, weight and opacity
  <hex-color-code>,[stroke-weight],[stroke-opacity],<hex-color-code-of-return>,[stroke-weight-of-return],[stroke-opacity-of-return]
  must beginn with #color of each stroke, weight and opacity is optional
  example: #019cdf,#ffeb19
  example: #019cdf,20,#ffeb19
  example: #019cdf,20,#ffeb19,15
  example: #019cdf,#ffeb19,15
  example: #019cdf,20,80,#ffeb19
  example: #019cdf,#ffeb19,15,50
  example: #019cdf,20,80
  default: #4cde44,6,100,#FF0000,1,100
• "GoogleMapsTrafficLayer" - enable the basic Google Maps Traffic Layer
• "GoogleMapsDisableUI" - hide the map controls


Readings:
• alternatives
• delay
• delay_min
• distance
• duration
• duration_in_traffic
• duration_in_traffic_min
• duration_min
• error_message
• eta
• state
• summary


Set
• update [burst-update-count] [burst-update-interval] - update readings manually

TRX

[EN DE]

This module is for the RFXCOM RFXtrx433 USB based 433 Mhz RF transmitters. This USB based transmitter is able to receive and transmit many protocols like Oregon Scientific weather sensors, X10 security and lighting devices, ARC ((address code wheels) HomeEasy, KlikAanKlikUit, ByeByeStandBy, Intertechno, ELRO, AB600, Duewi, DomiaLite, COCO) and others.
Currently the following parser modules are implemented:

• 46_TRX_WEATHER.pm (see device TRX): Process messages Oregon Scientific weather sensors. See http://www.rfxcom.com/oregon.htm for a list of Oregon Scientific weather sensors that could be received by the RFXtrx433 tranmitter. Until now the following Oregon Scientific weather sensors have been tested successfully: BTHR918, BTHR918N, PCR800, RGR918, THGR228N, THGR810, THR128, THWR288A, WTGR800, WGR918. It will also work with many other Oregon sensors supported by RFXtrx433. Please give feedback if you use other sensors.
  
• 46_TRX_SECURITY.pm (see device TRX_SECURITY): Receive X10, KD101 and Visonic security sensors.
• 46_TRX_LIGHT.pm (see device RFXX10REC): Process X10, ARC, ELRO AB400D, Waveman, Chacon EMW200, IMPULS, RisingSun, Philips SBC, AC, HomeEasy EU and ANSLUT lighting devices (switches and remote control). ARC is a protocol used by devices from HomeEasy, KlikAanKlikUit, ByeByeStandBy, Intertechno, ELRO, AB600, Duewi, DomiaLite and COCO with address code wheels. AC is the protocol used by different brands with units having a learning mode button: KlikAanKlikUit, NEXA, CHACON, HomeEasy UK.

Note: this module requires the Device::SerialPort or Win32::SerialPort module if the devices is connected via USB or a serial port.

Define
define <name> TRX <device> [noinit]


USB-connected:

<device> specifies the USB port to communicate with the RFXtrx433 receiver. Normally on Linux the device will be named /dev/ttyUSBx, where x is a number. For example /dev/ttyUSB0. Please note that RFXtrx433 normally operates at 38400 baud. You may specify the baudrate used after the @ char.

Example:
define RFXTRXUSB TRX /dev/ttyUSB0@38400


Network-connected devices:

<device> specifies the host:port of the device. E.g. 192.168.1.5:10001
noninit is optional and issues that the RFXtrx433 device should not be initialized. This is useful if you share a RFXtrx433 device via LAN. It is also useful for testing to simulate a RFXtrx433 receiver via netcat or via FHEM2FHEM.

Example:
define RFXTRXTCP TRX 192.168.1.5:10001
define RFXTRXTCP2 TRX 192.168.1.121:10001 noinit


Set
• protocols: allows to enable and disable protocols similar to RfxMngr. Please check the manual which protocols are supported by your model/firmware
• save: Save the protocol selection to non-volatile storage
• reopen: reset the connection to the RFXDevice
Readings
• firmware: Firmware of the RFXTRX Device
• frequency: Frequency and type of the RFXTRX Device
• protocols: enabled protocols of the RFXTRX Device
Attributes
• dummy


• longids
  Comma separated list of device-types for TRX_WEATHER that should be handled using long IDs. This additional ID is a one byte hex string and is generated by the Oregon sensor when is it powered on. The value seems to be randomly generated. This has the advantage that you may use more than one Oregon sensor of the same type even if it has no switch to set a sensor id. For example the author uses two BTHR918N sensors at the same time. All have different deviceids. The drawback is that the deviceid changes after changing batteries. All devices listed as longids will get an additional one byte hex string appended to the device name.
  Default is to use no long IDs.
  
  Examples:

  # Do not use any long IDs for any devices (this is default):
  attr RFXCOMUSB longids 0
  # Use long IDs for all devices:
  attr RFXCOMUSB longids 1
  # Use longids for BTHR918N devices.
  # Will generate devices names like BTHR918N_f3.
  attr RFXTRXUSB longids BTHR918N
  # Use longids for TX3_T and TX3_H devices.
  # Will generate devices names like TX3_T_07, TX3_T_01 ,TX3_H_07.
  attr RFXTRXUSB longids TX3_T,TX3_H

• rssi
  1: enable RSSI logging, 0: disable RSSI logging
  Default is no RSSI logging.
  
  Examples:

  # Do log rssi values (this is default):
  attr RFXCOMUSB rssi 0
  # Enable rssi logging for devices:
  attr RFXCOMUSB rssi 1

TRX_ELSE

[EN DE]

The TRX_ELSE module is invoked by TRX if a code is received by RFXCOM RFXtrx433 RF receiver that is currently not handled by a TRX_-Module. You need to define an RFXtrx433 receiver first. See TRX.

Define
define <name> TRX_ELSE <hextype>

<hextype>
specifies the hexvalue (00 - ff) of the type received by the RFXtrx433 transceiver.


Example:
define TRX_UNKNOWN_9A TRX_ELSE 9A

TRX_LIGHT

[EN DE]

The TRX_LIGHT module receives and sends X10, ARC, ELRO AB400D, Waveman, Chacon EMW200, IMPULS, RisingSun, AC, HomeEasy EU and ANSLUT lighting devices (switches and remote control). Allows to send Philips SBC (receive not possible). ARC is a protocol used by devices from HomeEasy, KlikAanKlikUit, ByeByeStandBy, Intertechno, ELRO, AB600, Duewi, DomiaLite and COCO with address code wheels. AC is the protocol used by different brands with units having a learning mode button: KlikAanKlikUit, NEXA, CHACON, HomeEasy UK.
You need to define an RFXtrx433 transceiver receiver first. See TRX.

Define
define <name> TRX_LIGHT <type> <deviceid> <devicelog> [<deviceid2> <devicelog2>]
define <name> TRX_LIGHT PT2262 <deviceid> <devicelog> <commandcodes>

<type>
specifies the type of the device:
Lighting devices:
• MS14A (X10 motion sensor. Reports [normal|alert] on the first deviceid (motion sensor) and [on|off] for the second deviceid (light sensor))
• X10 (All other x10 devices. Report [off|on|dim|bright|all_off|all_on] on both deviceids.)
• ARC (ARC devices. ARC is a protocol used by devices from HomeEasy, KlikAanKlikUit, ByeByeStandBy, Intertechno, ELRO, AB600, Duewi, DomiaLite and COCO with address code wheels. Report [off|on|all_off|all_on|chime].)
• AB400D (ELRO AB400D devices. Report [off|on].)
• WAVEMAN (Waveman devices. Report [off|on].)
• EMW200 (Chacon EMW200 devices. Report [off|on|all_off|all_on].)
• IMPULS (IMPULS devices. Report [off|on].)
• RISINGSUN (RisingSun devices. Report [off|on].)
• PHILIPS_SBC (Philips SBC devices. Send [off|on|all_off|all_on].)
• ENER010 (Energenie ENER010 devices. deviceid: [A-P][1-4]. Send [off|on|all_off|all_on].)
• ENER5 (Energenie 5-gang devices. deviceid: [A-P][1-10]. Send [off|on].)
• COCO_GDR2 (ECOCO GDR2-2000R devices. deviceid: [A-D][1-4]. Send [off|on].)
• AC (AC devices. AC is the protocol used by different brands with units having a learning mode button: KlikAanKlikUit, NEXA, CHACON, HomeEasy UK. Report [off|on|level <NUM>|all_off|all_on|all_level <NUM>].)
• HOMEEASY (HomeEasy EU devices. Report [off|on|level|all_off|all_on|all_level].)
• ANSLUT (Anslut devices. Report [off|on|level|all_off|all_on|all_level].)
• PT2262 (Devices using PT2262/PT2272 (coder/decoder) chip. To use this enable Lighting4 in RFXmngr. Please note that this disables ARC. For more information see FHEM-Wiki)
• LIGHTWAVERF (LightwaveRF devices. Commands ["off", "on", "all_off", "mood1", "mood2", "mood3", "mood4", "mood5", "reserved1", "reserved2", "unlock", "lock", "all_lock", "close", "stop", "open", "level"].)
• EMW100 (EMW100 devices. Commands ["off", "on", "learn"].)
• BBSB (BBSB devices. Commands ["off", "on", "all_off", "all_on"].)
• MDREMOTE (MDREMOTE LED dimmer devices. Commands ["power", "light", "bright", "dim", "100", "50", "25", "mode+", "speed-", "speed+", "mode-"].)
• RSL2 (Conrad RSL2 devices. Commands ["off", "on", "all_off", "all_on"].)
• LIVOLO (Livolo devices. Commands ["all_off", "on_off", "dim+", "dim-"].)
• TRC02 (RGB TRC02 devices. Commands ["off", "on", "bright", "dim", "vivid", "pale", "color"].)
• BLYSS (Blyss devices. deviceid: [A-P][1-5]. Commands ["off", "on", "all_off", "all_on"].)
• CUVEO (Cuveo devices. deviceid: [A-P][1-5]. Commands ["off", "on", "all_off", "all_on"].)
• BYRONSX (Byron SX chime devices. deviceid: 00-FF. Commands [ "tubular3_1", "solo1", "bigben1", "tubular2_1", "tubular2_2", "solo2", "tubular3_2"].)
• SELECTPLUS (SELECTPLUS] chime devices. deviceid: 0000-FFFF. Commands [ "ring"].)
• SIEMENS_SF01 (Siemens SF01 devices. deviceid: 000000-007FFF. Commands [ "timer", "-", "learn", "+", "confirm", "light", "on", "off" ].)
• WESTINGHOUSE (Westinghouse Fans. deviceid: 000000-007FFF. Commands [ "", "Hi", "Med", "Low", "Off", "Light"].)
• HARRISON (Harrison curtain devices. deviceid: 00-FF. Commands [ "open", "close", "stop", "program" ].)
• ROLLER_TROL (Roller Trol blind devices. deviceid: 00000100-00FFFF0F. Commands [ "open", "close", "stop", "confirm_pair", "set_limit" ].)
• HASTA_OLD (Hasta old blind devices. deviceid: 00000100-00FFFF0F. Commands [ "open", "close", "stop", "confirm_pair", "set_limit" ].)
• AOK_RF01 (A-OK RF01 blind devices. deviceid: 00000100-FFFFFF0F. Commands [ "open", "close", "stop", "confirm_pair" ].)
• AOK_AC114 (A-OK AC114 blind devices. deviceid: 00000100-FFFFFF0F. Commands [ "open", "close", "stop", "confirm_pair" ].)
• RAEX_YR1326 (Raex YR1326 blind devices. deviceid: 00000100-FFFFFF0F. Commands [ "open", "close", "stop", "confirm_pair", "set_upper_limit", "set_lower_limit", "delete_limits", "change_dir", "left", "right"].)
• MEDIA_MOUNT (Media Mount blind devices. deviceid: 00000100-FFFFFF0F. Commands [ "down", "up", "stop" ].)
• DC106 (DC/RMF/Yooda blind devices. deviceid: 00000100-FFFFFFF0. Commands [ "open", "close", "stop", "confirm" ].)
• FOREST (Forest blind devices. deviceid: 00000100-FFFFFFF0. Commands [ "open", "close", "stop", "confirm_pair" ].)
• RFY (Somfy RTS devices. deviceid: 000001-0FFFFF, unicode: 01-04 (00 = allunits). Commands [ "up", "down", "stop", "program" ].)
• RFY_ext (Somfy RTS devices. deviceid: 000001-0FFFFF, unicode: 00-0F. Commands [ "up", "down", "stop", "program" ].)

<deviceid>
specifies the first device id of the device.
A lighting device normally has a house code A..P followed by a unitcode 1..16 (example "B1").
For AC, HomeEasy EU and ANSLUT it is a 10 Character-Hex-String for the deviceid, consisting of
- unid-id: 8-Char-Hex: 00000001 to 03FFFFFF
- unit-code: 2-Char-Hex: 01 to 10
For LIGHTWAVERF, EMW100, BBSB, MDREMOTE, RSL2, LIVOLO and TRC02 it is a 8 Character-Hex-String for the deviceid, consisting of
- unid-id: 8-Char-Hex: 000001 to FFFFFF
- unit-code: 2-Char-Hex: 01 to 10
For RFY and RFY-ext it is a 8 Character-Hex-String for the deviceid, consisting of
- unid-id: 8-Char-Hex: 000001 to FFFFFF
- unit-code: 2-Char-Hex: 01 to 04 for RFY (00 for all units) and 00 to 0F for RFY_ext


<devicelog>
is the name of the Reading used to report. Suggested: "motion" for motion sensors. If you use "none" then no additional Reading is reported. Just the state is used to report the change.

<deviceid2>
is optional and specifies the second device id of the device if it exists. For example ms14a motion sensors report motion status on the first deviceid and the status of the light sensor on the second deviceid.

<devicelog2>
is optional for the name used for the Reading of <deviceid2>.If you use "none" then no addional Reading is reported. Just the state is used to report the change.

<commandcodes>
is used for PT2262 and specifies the possible base4 digits for the command separated by : and a string that specifies a string that is the command. Example '0:off,1:on'.

Example:
define motion_sensor2 TRX_LIGHT MS14A A1 motion A2 light
define Steckdose TRX_LIGHT ARC G2 light
define light TRX_LIGHT AC 0101010101 light


Set
set <name> <value> [<levelnum>]

where value is one of:

• off
• on
• dim # only for X10, KOPPLA
• bright # only for X10, KOPPLA
• all_off # only for X10, ARC, EMW200, AC, HOMEEASY, ANSLUT
• all_on # only for X10, ARC, EMW200, AC, HOMEEASY, ANSLUT
• chime # only for ARC
• level <levelnum> # only AC, HOMEEASY, ANSLUT: set level to <levelnum> (range: 0=0% to 15=100%)
• ring # Byron MP001,SelectPlus, RFU, Envivo
• setExtensions # see Notes
Example:
set Steckdose on

Notes:
• on-for-timer earlier required an absolute time in the "at" format. TRX_LIGHT is now using SetExtensions, thus on-for-timer now requires a number (seconds). TimeSpecs in the format (HH:MM:SS|HH:MM) or { <perl code> } are automatically converted, however it is recommended that you adjust your set commands.

Get
N/A

Attributes
• ignore
• do_not_notify
• readingFnAttributes

TRX_SECURITY

[EN DE]

The TRX_SECURITY module interprets X10, KD101 and Visonic security sensors received by a RFXCOM RFXtrx433 RF receiver. You need to define an RFXtrx433 receiver first. See TRX.

Define
define <name> TRX_SECURITY <type> <deviceid> <devicelog> [<deviceid2> <devicelog2>]

<type>
specifies one of the following security devices:
• DS10A (X10 security ds10a Door/Window Sensor or compatible devices. This device type reports the status of the switch [Open/Closed], status of the delay switch [min|max]], and battery status [ok|low].)
• SD18 or COD18(X10 security sd18 smoke Sensor and COD18 CO Sensor). These device types report the status of the sensor [alert/normal] and battery status [ok|low])
• MS10A (X10 security ms10a motion sensor. This device type reports the status of motion sensor [normal|alert] and battery status [ok|low].))
• SD90 (Marmitek sd90 smoke detector. This device type reports the status of the smoke detector [normal|alert] and battery status [ok|low].)
• KR18 (X10 security remote control. Report the Reading "Security" with values [Arm|Disarm], "ButtonA" and "ButtonB" with values [on|off] )
• KD101 (KD101 smoke sensor. Report the Reading "smoke" with values [normal|alert])
• VISONIC_WINDOW (VISONIC security Door/Window Sensor or compatible devices. This device type reports the status of the switch [Open/Closed] and battery status [ok|low].)
• VISONIC_MOTION (VISONIC security motion sensor. This device type reports the status of motion sensor [normal|alert] and battery status [ok|low].))

<deviceid>
specifies the first device id of the device. X10 security (DS10A, MS10A) and SD90 have a a 16 bit device id which has to be written as a hex-string (example "5a54"). All other devices have a 24 bit device id.

<devicelog>
is the name of the Reading used to report. Suggested: "Window" or "Door" for ds10a, "motion" for motion sensors, "smoke" for sd90, sd18 and cod18. If you use "none" then no additional Reading is reported. Just the state is used to report the change.

<deviceid2>
is optional and specifies the second device id of the device if it exists. For example sd90 smoke sensors can be configured to report two device ids.

<devicelog2>
is optional for the name used for the Reading of <deviceid2>. If you use "none" then no additional Reading is reported. Just the state is used to report the change.

Example:
define livingroom_window TRX_SECURITY ds10a 72cd Window
define motion_sensor1 TRX_SECURITY ms10a 55c6 motion
define smoke_sensor1 TRX_SECURITY sd90 54d3 Smoke 54d3 Smoketest


Set
set <name> <value>

where value is one of:


    alert              # only for KD101
    pair               # only for KD101
    

Example:
set TRX_KD101_a5ca00 alert


Get
N/A

Attributes
• ignore
• do_not_notify
• readingFnAttributes

TRX_WEATHER

[EN DE]

The TRX_WEATHER module interprets weather sensor messages received by a RTXtrx receiver. See http://www.rfxcom.com/oregon.htm for a list of Oregon Scientific weather sensors that could be received by the RFXtrx433 tranmitter. You need to define a RFXtrx433 receiver first. See See TRX.

Define
define <name> TRX_WEATHER <deviceid>

<deviceid>
is the device identifier of the sensor. It consists of the sensors name and (only if the attribute longids is set of the RFXtrx433) an a one byte hex string (00-ff) that identifies the sensor. If an sensor uses an switch to set an additional is then this is also added. The define statement with the deviceid is generated automatically by autocreate. The following sensor names are used:
"THR128" (for THR128/138, THC138),
"THGR132N" (for THC238/268,THN132,THWR288,THRN122,THN122,AW129/131),
"THWR800",
"RTHN318",
"TX3_T" (for LaCrosse TX3, TX4, TX17),
"THGR228N" (for THGN122/123, THGN132, THGR122/228/238/268),
"THGR810",
"RTGR328",
"THGR328",
"WTGR800_T" (for temperature of WTGR800),
"THGR918" (for THGR918, THGRN228, THGN500),
"TFATS34C" (for TFA TS34C),
"BTHR918",
"BTHR918N (for BTHR918N, BTHR968),
"RGR918" (for RGR126/682/918),
"PCR800",
"TFA_RAIN" (for TFA rain sensor),
"WTGR800_A" (for wind sensor of WTGR800),
"WGR800" (for wind sensor of WGR800),
"WGR918" (for wind sensor of STR918 and WGR918),
"TFA_WIND" (for TFA wind sensor),
"BWR101" (for Oregon Scientific BWR101),
"GR101" (for Oregon Scientific GR101) "TLX7506" (for Digimax TLX7506),
"TH10" (for Digimax with short format),


Example:

define Tempsensor TRX_WEATHER TX3_T
define Tempsensor3 TRX_WEATHER THR128_3
define Windsensor TRX_WEATHER WGR918_A
define Regensensor TRX_WEATHER RGR918




define <name> TRX_WEATHER <deviceid> [<scale_current> <scale_total> <add_total>]

<deviceid>
is the device identifier of the energy sensor. It consists of the sensors name and (only if the attribute longids is set of the RFXtrx433) an a two byte hex string (0000-ffff) that identifies the sensor. The define statement with the deviceid is generated automatically by autocreate. The following sensor names are used:
"CM160" (for OWL CM119 or CM160),
"CM180" (for OWL CM180),

"CM180i"(for OWL CM180i),


The following Readings are generated:

"energy_current:":
Only for CM160 and CM180: current usage in Watt. If <scale_current> is defined the result is: energy_current * <scale_current>.
"energy_chx:":
Only for CM180i (where chx is ch1, ch2 or ch3): current usage in Ampere. If <scale_current> is defined the result is: energy_chx * <scale_current>.
"energy_total:":
current usage in kWh. If scale_total and add_total is defined the result is: energy_total * <scale_total> + <add_total>.


Example:

define Tempsensor TRX_WEATHER CM160_1401
define Tempsensor TRX_WEATHER CM180_1401 1 1 0
define Tempsensor TRX_WEATHER CM180_1401 0.9 0.9 -1000


Set
N/A

Get
N/A

Attributes
• ignore
• do_not_notify
• readingFnAttributes

TUL

[EN DE]

The TUL module is the representation of a EIB / KNX connector in FHEM. KNX instances represent the EIB / KNX devices and will need a TUL as IODev to communicate with the EIB / KNX network. The TUL module is designed to connect to EIB network either using eibd, knxd or the TUL usb stick created by busware.de Note: this module may require the Device::SerialPort or Win32::SerialPort module if you attach the device via USB and the OS sets strange default parameters for serial devices.

Define
define <name> TUL <device> <physical address>

TUL usb stick / TPUART serial devices:

<device> specifies the serial port to communicate with the TUL. The name of the serial-device depends on your distribution, under linux the cdc_acm kernel module is responsible, and usually a /dev/ttyACM0 device will be created. If your distribution does not have a cdc_acm module, you can force usbserial to handle the TUL by the following command:
modprobe usbserial vendor=0x03eb product=0x204b
In this case the device is most probably /dev/ttyUSB0.

You can also specify a baudrate if the device name contains the @ character, e.g.: /dev/ttyACM0@19200

Note: For TUL usb stick the baudrate 19200 is needed and this is the default when no baudrate is given.

Example:
define tul TUL tul:/dev/ttyACM0 1.1.249
EIBD:

<device> specifies the host:port of the eibd device. E.g. eibd:192.168.0.244:2323. When using the standard port, the port can be omitted.

Example:
define tul TUL eibd:localhost 1.1.249 define tul TUL knxd:192.168.178.1 1.1.248

If the device is called none, then no device will be opened, so you can experiment without hardware attached.
The physical address is used as the source address of telegrams sent to EIB network.

Attributes
• do_not_notify


• dummy


• showtime


• verbose


• useEIB


The device operates the module 10_EIB, if this flag is set to 1. This is used for backward compatibility only. Otherwise, only the client 10_KNX is used.

Talk2Fhem

[EN DE]

The module Talk2Fhem is a connection between natural language and FHEM commands. The configuration is carried out conveniently via the FHEM web frontend.
For a more detailed description and further examples see Talk2Fhem Wiki.

Define
define <name> Talk2Fhem

Example: define talk Talk2Fhem

The actual configuration should first be done on the FHEM side.

The individual language phrases are configured line by line. A configuration always starts by the regular expression, followed by at least one space or tab from an equal sign.
The command part begins after the equals sign with a space, tab, or newline.

<regexp> = <command>

Short refernce:
<RegExpPart> [&& [?!]<RegExpPart_n>] = [ <FHEM command> | { <Perl code> } | (<option> => '<wert>' , ... ) ]

Example: helo world = {Log 1, Helo World}

Everything after a hashtag '#' is ignored until the end of the line.

<regexp>
Regular expression describing the text at which the command should be executed


<command>
The executive part. The following formats are allowed:
• FHEM Command
• {Perlcode}
• (<option> => '<value>' , ... )

<option>

• cmd
  FHEM command as above
• offset
  Integer value in seconds that is added at the time
• answer
  Perl code whose return is written in the Reading answer

Bracket transfer:
Brackets set in the regular expression can be transferred to the command section with $1, $2, [...], $n and be modified. The following modification options are available here.
• $n
  Get the word straight without change.
• $n{<type> => <value>}
  Types are:
  true, false, integer, empty, else
  true, false, integer, float, numeral, /<regexp>/, word, empty, else
  true corresponds to: ja|1|true|wahr|ein|eins.*|auf.*|..?ffnen|an.*|rauf.*|hoch.*|laut.*|hell.*
  false corresponds to: nein|0|false|falsch|aus.*|null|zu.*|schlie..?en|runter.*|ab.*|leise.*|dunk.*
  integer Word is an integer
  float Word is a float number
  numeral Word is numeral or an integer
  /<regexp>/ Word is matching <regexp>
  word Word contains 4 or more letters
  empty Word Contains an empty string
  else If none of the cases apply
  If a <type> is identified for $n the <value> is beeing used. Example: light (\S*) = set light $1{true => on,false => off}
• $n[<list>]
  Comma separated list: [value1,value2,...,[else,value], [empty,value]] or [@modwordlist]
  If $n is a number, the word at that position in <list> is selected.
  
  If $n is a text, it searches for a list in its parenthesis in the <regexp> part. (a|b|c) or (@keywordlist) In this list, $n is searched for and successively positioned in <list> chosen for $n.
  Example: light .* (kitchen|corridor|bad) (\S*) on = set $1[dev_a,dev_b,dev_c] $2{true => on,false => off}
• $n@
  The word is adopted as it is written in the list in the <regexp>-part.

Environment variables::
There are a number of variables that can be accessed in the <command>-part.
• $& Contains all found words
• !$& Contains the rest that was not included by RegExp
• $DATE Contains the time and date text of the voice
• $AGAIN Contains the word again if it is a command again
• $TIME Contains the found time.
• $NAME Contains the devicename.
• $IF Contains the text of the detected T2F_if configuration.
• $0 Contains the text of the detected T2F_origin regexp.

Set

set <name> [!]<text>

The text is sent to the module via the set command. See commandref#set for more help.
• cleartimers
Removes the pending time-related commands
• cleartriggers
Removes the pending event-related commands

Get
get <name> <option>

Information can be read from the module via get.         See commandref#get for more information on "get".

<option>
• @keywordlist @modwordlist
  Compare the two lists word by word.
• keylistno
  A list of the configured "keyword" lists. For easier positioning of "modword" lists
• log
  Shows the log entries of the last command
• modificationtypes
  Shows the regexp of the modificationtypes.
• standardfilter
  Load the standartfilter and print it in the Attribute T2F_filter if its empty
• version
  The module version

Readings
• set
  Contains the last text sent via "set".
• cmds
  Contains the last executed command. Is also set with disable = 1.
• answer
  Contains the response text of the last command.
• err
  Contains the last error message.
  "No match" match with no RegExp.
  "Error on Command" see FHEM log.
• response
  Got the response of the fhem Command.
• origin
  Contains the found string of the RegExp defined in the attribute T2F_origin.
• status
  Got the status of the request. response, disabled, err, answers, done
• ifs
  Contains the conditions at which the command will be executed.
• notifies
  Contains a list of the devices that are relevant for the currently waiting conditional commands. There is an internal notify on these devices.

Attribute
attr <name> <attribute> <value>

See commandref#attr for more information about the attributes.

Attributes:
• T2F_keywordlist <name> = <list>
  A comma-separated list of keywords such as: rooms, names, colors, etc ...
  In other words, things named with a natural name.
• T2F_modwordlist <name> = <list>
  A comma seperated list of substitution words used for the keywords. For example: device names in FHEM
  
• T2F_if
  A collection of event-driven configurations. The syntax is that of the definition. Command part is an IF condition.
  z.B.: (when|if) .*?door = [door] eq "open"
• T2F_filter
  Comma-separated list of RegExp generally removed.
  Standard: \bplease\b,\balso\b
• T2F_origin
  A RegExp which is generally removed and whose output can be accessed via $0.
  Can be used for user mapping.
• T2F_languageDE|EN
  The used language can be set via the global attribute "language". Or overwritten with this attribute.
• T2F_disableumlautescaping <0|1>
  Disable convertimg umlauts to "\S\S?"
• disable <0|1>
  Can be used for test purposes. If the attribute is set to 1, the FHEM command is not executed but written in reading cmds.

TechemHKV

[EN DE]

This module reads the transmission of techem data meter for heating device.

It will display
• meter data for current billing period
• meter data for previous billing period including date of request
• both temperature sensors (if supported by data meter)

It will require a CUL in WMBUS_T mode, although the CUL may temporary set into that mode. The module keeps track of the CUL rfmode.

Define
define <name> TechemHKV <4|8 digit ID> [<speaking name>]
• ID: 4 digit ID displayed at techem or 8 digit as printed on bill
• speaking name: (optional) human readable identification

Readings
• current_period: meter data for current billing period
  unit-less data, cumulated since start of the current billing period. The reading will be updated once a day, after receiving the first update. Reading time will reflect the time of data (not the time where they were received)
  
• previous_period: meter data for last billing period
  unit-less data, sum of the last billing period. The reading will be updated only if a new billing period starts. Reading time will reflect the last day of previous billing period (not the time where they were received)
  
• temp1: ambient temperature
• temp2: heater surface temperature


Internals
• friendly: human readable identification of meter as specified by define
• longID: 8 digit id of meter

TechemWZ

[EN DE]

This module reads the transmission of techem volume data meter. Currently supported device:
• Messkapsel-Wasserzähler radio 3 (cold, warm water)
• Messkapsel-Wärmemengenzähler compact V (heating energy)

It will display
• meter data for current billing period
• meter data for previous billing period including date of request
• cumulative meter data

It will require a CUL in WMBUS_T mode, although the CUL may temporary set into that mode. The module keeps track of the CUL rfmode.

preliminary

Techem volume data meter does not transmit their printed meter ID. Instead they transmit the ID of the build in radio module.

Therefore a "list-mode" is available which collects all Techem meter device in range to help you find out the right one. That "list-mode" will be activated by defining a TechemWZ device with id "00000000". Let it run for a while and do a "get <name> list". You will see a list of available (received) Techem device with their ID and meter data. Choose the right one (keep in mind that the meter reading reflects last midnight), note down their ID and define the appropriate device. After done the device with ID "00000000" can be removed.

Define
define <name> TechemWZ <8 digit ID> [<speaking name>]

• ID: 8 digit ID (see list mode above)
• speaking name: (optional) human readable identification

Readings
• current_period: meter data for current billing period
  cumulated since the start of the current billing period. The reading will be updated once a day, after receiving the first update. Reading time will reflect the time of data (not the time where the data were received)
  
• previous_period: meter data for last billing period
  meter rading at the end of the last billing period. The reading will be updated if a new billing period starts. Reading time will reflect the last day of previous billing period (not the time where the data were received)
  
• meter: cumulative meter data.
  The same data that will be shown at the Techem (mechanical) display
  


Get
• list: print a list of available (received) Techem device with their ID and meter data
  only available if device ID is "00000000" (list-mode)
  


Internals
• friendly: human readable identification of meter as specified by define

TelegramBot

[EN DE]

The TelegramBot module allows the usage of the instant messaging service Telegram from FHEM in both directions (sending and receiving). So FHEM can use telegram for notifications of states or alerts, general informations and actions can be triggered.

TelegramBot makes use of the telegram bot api and does NOT rely on any addition local client installed.
Telegram Bots are different from normal telegram accounts, without being connected to a phone number. Instead bots need to be registered through the BotFather to gain the needed token for authorizing as bot with telegram.org. This is done by connecting (in a telegram client) to the BotFather and sending the command /newbot and follow the steps specified by the BotFather. This results in a token, this token (e.g. something like 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw is required for defining a working telegram bot in fhem.

Bots also differ in other aspects from normal telegram accounts. Here some examples:
• Bots can not initiate connections to arbitrary users, instead users need to first initiate the communication with the bot.
• Bots have a different privacy setting then normal users (see Privacy mode)
• Bots support commands and specialized keyboards for the interaction


Note:
• This module requires the perl JSON module.
  Please install the module (e.g. with sudo apt-get install libjson-perl) or the correct method for the underlying platform/system.
• The attribute pollingTimeout needs to be set to a value greater than zero, to define the interval of receiving messages (if not set or set to 0, no messages will be received!)
• Multiple infomations are stored in readings (esp contacts) and internals that are needed for the bot operation, so having an recent statefile will help in correct operation of the bot. Generally it is recommended to regularly store the statefile (see save command)


The TelegramBot module allows receiving of messages from any peer (telegram user) and can send messages to known users. The contacts/peers, that are known to the bot are stored in a reading (named Contacts) and also internally in the module in a hashed list to allow the usage of contact ids and also full names and usernames. Contact ids are made up from only digits, user names are prefixed with a @, group names are prefixed with a #. All other names will be considered as full names of contacts. Here any spaces in the name need to be replaced by underscores (_). Each contact is considered a triple of contact id, full name (spaces replaced by underscores) and username or groupname prefixed by @ respectively #. The three parts are separated by a colon (:).
Contacts are collected automatically during communication by new users contacting the bot or users mentioned in messages.

Updates and messages are received via long poll of the GetUpdates message. This message currently supports a maximum of 20 sec long poll. In case of failures delays are taken between new calls of GetUpdates. In this case there might be increasing delays between sending and receiving messages!
Beside pure text messages also media messages can be sent and received. This includes audio, video, images, documents, locations and venues.

Define
define <name> TelegramBot <token>

Defines a TelegramBot device using the specified token perceived from botfather
Example:
define teleBot TelegramBot 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw





Set
• message|msg|_msg|send [ @<peer1> ... @<peerN> ] [ (<keyrow1>) ... (<keyrowN>) ] <text>
  Sends the given message to the given peer or if peer(s) is ommitted currently defined default peer user. Each peer given needs to be always prefixed with a '@'. Peers can be specified as contact ids, full names (with underscore instead of space), usernames (prefixed with another @) or chat names (also known as groups in telegram groups must be prefixed with #). Multiple peers are to be separated by space.
  
  A reply keyboard can be specified by adding a list of strings enclosed in parentheses "()". Each separate string will make one keyboard row in a reply keyboard. The different keys in the row need to be separated by |. The key strings can contain spaces.
  Messages do not need to be quoted if containing spaces. If you want to use parentheses at the start of the message than add one extra character before the parentheses (i.e. an underline) to avoid the message being parsed as a keyboard.
  
  if an empty keyoard is given "()" an existing keyboard is removed
  
  Messages can also contain special characters. These include newline = \n, tab = \t and also a normal space = \s
  
  Examples:
  

  set aTelegramBotDevice message @@someusername a message to be sent

  to send to a peer having someusername as username (not first and last name) in telegram
  

  set aTelegramBotDevice message (yes) (may be) are you there?

  to send the message "are you there?" and provide a reply keyboard with two buttons ("yes" and "may be") on separate rows to the default peer
  

  set aTelegramBotDevice message @@someusername (yes) (may be) are you there?

  to send the message from above with reply keyboard to a peer having someusername as username
  

  set aTelegramBotDevice message (yes|no) (may be) are you there?

  to send the message from above with reply keyboard having 3 keys, 2 in the first row ("yes" / "no") and a second row with just one key to the default peer
  

  set aTelegramBotDevice message @@someusername @1234567 a message to be sent to multiple receipients

  to send to a peer having someusername as username (not first and last name) in telegram
  

  set aTelegramBotDevice message @Ralf_Mustermann another message

  to send to a peer with Ralf as firstname and Mustermann as last name in telegram
  

  set aTelegramBotDevice message @#justchatting Hello

  to send the message "Hello" to a chat with the name "justchatting"
  

  set aTelegramBotDevice message @1234567 Bye

  to send the message "Bye" to a contact or chat with the id "1234567". Chat ids might be negative and need to be specified with a leading hyphen (-).
  

• silentmsg, silentImage, silentDocument, silentLocation, silentVoice , silentInline ...
  Sends the given message silently (with disabled_notifications) to the recipients. Syntax and parameters are the same as in the corresponding send/message command.
• msgForceReply [ @<peer1> ... @<peerN> ] <text>
  Sends the given message to the recipient(s) and requests (forces) a reply. Handling of peers is equal to the message command. Adding reply keyboards is currently not supported by telegram.
• reply <msgid> [ @<peer1> ] <text>
  Sends the given message as a reply to the msgid (number) given to the given peer or if peer is ommitted to the defined default peer user. Only a single peer can be specified. Beside the handling of the message as a reply to a message received earlier, the peer and message handling is otherwise identical to the msg command.
• msgEdit <msgid> [ @<peer1> ] <text>
  Changes the given message on the recipients clients. The msgid of the message to be changed must match a valid msgId and the peers need to match the original recipient, so only a single peer can be given or if peer is ommitted the defined default peer user is used. Beside the handling of a change of an existing message, the peer and message handling is otherwise identical to the msg command.
• msgDelete <msgid> [ @<peer1> ]
  Deletes the given message on the recipients clients. The msgid of the message to be changed must match a valid msgId and the peers need to match the original recipient, so only a single peer can be given or if peer is ommitted the defined default peer user is used. Restrictions apply for deleting messages in the Bot API as currently specified here (deleteMessage)
• favoritesMenu [ @<peer> ]
  send the favorites menu to the corresponding peer if defined
• cmdSend|cmdSendSilent [ @<peer1> ... @<peerN> ] <fhem command>
  Executes the given fhem command and then sends the result to the given peers or the default peer (cmdSendSilent does the same as silent message).
  Example: The following command would sent the resulting SVG picture to the default peer:
  set tbot cmdSend { plotAsPng('SVG_FileLog_Aussen') }
• queryInline [ @<peer1> ... @<peerN> ] (<keyrow1>) ... (<keyrowN>) <text>
  Sends the given message to the recipient(s) with an inline keyboard allowing direct response
  IMPORTANT: The response coming from the keyboard will be provided in readings and a corresponding answer command with the query id is required, sicne the client is frozen otherwise waiting for the response from the bot! REMARK: inline queries are only accepted from contacts/peers that are authorized (i.e. as for executing commands, see cmdKeyword and cmdRestrictedPeer !)
• queryEditInline <msgid> [ @<peer> ] (<keyrow1>) ... (<keyrowN>) <text>
  Updates the original message specified with msgId with the given message to the recipient(s) with an inline keyboard allowing direct response
  With this method interactive inline dialogs are possible, since the edit of message or inline keyboard can be done multiple times.
• queryAnswer <queryid> [ <text> ]
  Sends the response to the inline query button press. The message is optional, the query id can be collected from the reading "callbackID". This call is mandatory on reception of an inline query from the inline command above
• sendImage|image [ @<peer1> ... @<peerN>] <file> [<caption>]
  Sends a photo to the given peer(s) or if ommitted to the default peer. File is specifying a filename and path to the image file to be send. Local paths should be given local to the root directory of fhem (the directory of fhem.pl e.g. /opt/fhem). Filenames with special characters (especially spaces) need to be given with url escaping (i.e. spaces need to be replaced by %20). Rules for specifying peers are the same as for messages. Multiple peers are to be separated by space. Captions can also contain multiple words and do not need to be quoted.
• sendVideo [ @<peer1> ... @<peerN>] <file> [<caption>]
  Sends a video (prefered mp4 format accordingt to Telegram) to the given peer(s) or if ommitted to the default peer. File is specifying a filename and path to the video file to be send. Further description for sendImage also applies here.
• sendMedia|sendDocument [ @<peer1> ... @<peerN>] <file>
  Sends a media file (video, audio, image or other file type) to the given peer(s) or if ommitted to the default peer. Handling for files and peers is as specified above.
• sendVoice [ @<peer1> ... @<peerN>] <file>
  Sends a voice message for playing directly in the browser to the given peer(s) or if ommitted to the default peer. Handling for files and peers is as specified above.
• silentImage|silentVideo ...
  Sends the given image/video silently (with disabled_notifications) to the recipients. Syntax and parameters are the same as in the send... command.


• sendLocation [ @<peer1> ... @<peerN>] <latitude> <longitude>
  Sends a location as pair of coordinates latitude and longitude as floating point numbers
  Example: set aTelegramBotDevice sendLocation @@someusername 51.163375 10.447683 will send the coordinates of the geographical center of Germany as location.


• replaceContacts <text>
  Set the contacts newly from a string. Multiple contacts can be separated by a space. Each contact needs to be specified as a triple of contact id, full name and user name as explained above.
• reset
  Reset the internal state of the telegram bot. This is normally not needed, but can be used to reset the used URL, internal contact handling, queue of send items and polling
  ATTENTION: Messages that might be queued on the telegram server side (especially commands) might be then worked off afterwards immedately. If in doubt it is recommened to temporarily deactivate (delete) the cmdKeyword attribute before resetting.


• token <apitoken>
  Specify a new APItoken to be stored for this bot


Get
• urlForFile <fileid>
  Get a URL for a file id that was returned in a message
• update
  Execute a single update (instead of automatic polling) - manual polling
• peerId <peer>
  Ask for a peerId for a given peer, the peer can be specified in the same form as in a message without the initial '@'


Attributes


• defaultPeer <name>
  Specify contact id, user name or full name of the default peer to be used for sending messages.
• defaultPeerCopy <1 (default) or 0>
  Copy all command results also to the defined defaultPeer. If set results are sent both to the requestor and the defaultPeer if they are different.
• parseModeSend <0_None or 1_Markdown or 2_HTML or 3_Inmsg >
  Specify the parse_mode (allowing formatting of text messages) for sent text messages. 0_None is the default where no formatting is used and plain text is sent. The different formatting options for markdown or HTML are described here https://core.telegram.org/bots/api/#formatting-options. The option 3_Inmsg allows to specify the correct parse_mode at the beginning of the message (e.g. "Markdown*bold text*..." as message).
• webPagePreview <1 or 0>
  Disable / Enable (Default = 1) web page preview on links in messages. See parameter https://core.telegram.org/bots/api/#sendmessage as described here: https://core.telegram.org/bots/api/#sendmessage


• cmdKeyword <keyword>
  Specify a specific text that needs to be sent to make the rest of the message being executed as a command. So if for example cmdKeyword is set to ok fhem then a message starting with this string will be executed as fhem command (see also cmdTriggerOnly).
  NOTE: It is advised to set cmdRestrictedPeer for restricting access to this feature!
  Example: If this attribute is set to a value of ok fhem a message of ok fhem attr telegram room IM send to the bot would execute the command attr telegram room IM and set a device called telegram into room IM. The result of the cmd is sent to the requestor and in addition (if different) sent also as message to the defaultPeer (This can be controlled with the attribute defaultPeerCopy).
  Note: shutdown is not supported as a command (also in favorites) and will be rejected. This is needed to avoid reexecution of the shutdown command directly after restart (endless loop !).
• cmdSentCommands <keyword>
  Specify a specific text that will trigger sending the last commands back to the sender
  Example: If this attribute is set to a value of last cmd a message of last cmd woud lead to a reply with the list of the last sent fhem commands will be sent back.
  Please also consider cmdRestrictedPeer for restricting access to this feature!
  


• cmdFavorites <keyword>
  Specify a specific text that will trigger sending the list of defined favorites or executes a given favorite by number (the favorites are defined in attribute favorites).
  NOTE: It is advised to set cmdRestrictedPeer for restricting access to this feature!
  Example: If this attribute is set to a value of favorite a message of favorite to the bot will return a list of defined favorite commands and their index number. In the same case the message favorite <n> (with n being a number) would execute the command that is the n-th command in the favorites list. The result of the command will be returned as in other command executions.
• favorites <list of commands>
  Specify a list of favorite commands for Fhem (without cmdKeyword). Multiple favorites are separated by a single semicolon (;). A double semicolon can be used to specify multiple commands for a single favorite
  
  Favorite commands are fhem commands with an optional alias for the command given. The alias can be sent as message (instead of the favoriteCmd) to execute the command. Before the favorite command also an alias (other shortcut for the favorite) or/and a descriptive text (description enclosed in []) can be specifed. If alias or description is specified this needs to be prefixed with a '/' and the alias if given needs to be specified first.
  Favorites can also only be callable with the alias command and not via the corresponding favorite number and it will not be listed in the keyboard. For this the alias needs to be prefixed with a hyphen (-) after the leading slash
  
  Example: Assuming cmdFavorites is set to a value of favorite and this attribute is set to a value of
  get lights status; /light=set lights on; /dark[Make it dark]=set lights off; /-heating=set heater; /[status]=get heater status;
  
  • Then a message "favorite1" to the bot would execute the command get lights status
  • A message "favorite 2" or "/light" to the bot would execute the command set lights on. And the favorite would show as "make it dark" in the list of favorites.
  • A message "/heating on" to the bot would execute the command set heater on
    (Attention the remainder after the alias will be added to the command in fhem!). SInce this favorite is hidden only the alias can be used to call the favorite
  • A message "favorite 3" (since the one before is hidden) to the bot would execute the command get heater status and this favorite would show as "status" as a description in the favorite list
  
  Favorite commands can also be prefixed with a question mark ('?') to enable a confirmation being requested before executing the command.
  Examples: get lights status; /light=?set lights on; /dark=set lights off; ?set heater;
  
  
  Favorite commands can also be prefixed with a exclamation mark ('!') to ensure an ok-result message is sent even when the attribute cmdReturnEmptyResult is set to 0.
  Examples: get lights status; /light=!set lights on; /dark=set lights off; !set heater;
  
  The question mark needs to be before the exclamation mark if both are given.
  
  The description for an alias can also be prefixed with a '-'. In this case the favorite command/alias will not be shown in the favorite menu. This case only works for inline keyboard favorite menus.
  
  Favorite commands can also include multiple fhem commands being execute using ;; as a separator
  Example: get lights status; /blink=set lights on;; sleep 3;; set lights off; set heater;
  
  Meaning the full format for a single favorite is /alias[description]=commands where the alias can be empty if the description is given or /alias=command or /-alias=command for a hidden favorite or just the commands. In any case the commands can be also prefixed with a '?' or a '!' (or both). The description also can be given as [-description] to remvoe the command or alias from the favorite menus in inline keyboard menus. Spaces are only allowed in the description and the commands, usage of spaces in other areas might lead to wrong interpretation of the definition. Spaces and also many other characters are not supported in the alias commands by telegram, so if you want to have your favorite/alias directly recognized in the telegram app, restriction to letters, digits and underscore is required. Double semicolon will be used for specifying mutliple fhem commands in a single favorites, while single semicolon is used to separate between different favorite definitions
• favorites2Col <1 or 0>
  Show favorites in 2 columns keyboard (instead of 1 column - default)
• favoritesInline <1 or 0>
  When set to 1 it shows favorite dialog as inline keyboard and results will be also displayed inline (instead of as reply keyboards - default)


• cmdRestrictedPeer <peer(s)>
  Restrict the execution of commands only to messages sent from the given peername or multiple peernames (specified in the form of contact id, username or full name, multiple peers to be separated by a space). This applies to the internal machanisms for commands in the TelegramBot-Module (favorites, cmdKeyword etc) not for external methods to react on changes of readings. A message with the cmd and sender is sent to the default peer in case of another peer trying to sent messages
  NOTE: It is recommended to use only peer ids for this restriction to reduce spoofing risk!
• cmdRespondChat <1 or 0>
  Results / Responses from Commands will be sent to a group chat (1 = default) if originating from this chat. Otherwise responses will be sent only to the person initiating the command (personal chat) if set to value 0.
  Note: Group chats also need to be allowed as restricted Peer in cmdRestrictedPeer if this is set.
• allowUnknownContacts <1 or 0>
  Allow new contacts to be added automatically (1 - Default) or restrict message reception only to known contacts and unknwown contacts will be ignored (0).
• saveStateOnContactChange <1 or 0>
  Allow statefile being written on every new contact found, ensures new contacts not being lost on any loss of statefile. Default is on (1).
• cmdReturnEmptyResult <1 or 0>
  Return empty (success) message for commands (default). Otherwise return messages are only sent if a result text or error message is the result of the command execution.
• allowedCommands <list of command>
  Restrict the commands that can be executed through favorites and cmdKeyword to the listed commands (separated by space). Similar to the corresponding restriction in FHEMWEB. The allowedCommands will be set on the corresponding instance of an allowed device with the name "allowed_<TelegrambotDeviceName> and not on the telegramBotDevice! This allowed device is created and modified automatically.
  ATTENTION: This is not a hardened secure blocking of command execution, there might be ways to break the restriction!
• allowChannels <0 or 1>
  Support also messages coming from channels to the bot. This must be explicitely activated, since channels contain anonymous messages (without a defined sender of the message)
• cmdTriggerOnly <0 or 1>
  Restrict the execution of commands only to trigger command. If this attr is set (value 1), then only the name of the trigger even has to be given (i.e. without the preceding statement trigger). So if for example cmdKeyword is set to ok fhem and cmdTriggerOnly is set, then a message of ok fhem someMacro would execute the fhem command trigger someMacro.
  Note: This is deprecated and will be removed in one of the next releases
• queryAnswerText <text>
  Specify the automatic answering to buttons send through queryInline command. If this attribute is set an automatic answer is provided to the press of the inline button. The text in the attribute is evaluated through set-logic, so that readings and also perl code can be stored here. The result of the translation with set-logic will be sent as a text with the answer (this text is currently limited by telegram to 200 characters).
  Note: A value of "0" in the attribute or as result of the evaluation will result in no text being sent with the answer.
  Note: If the peer sending the button is not authorized an answer is always sent without any text.


• pollingTimeout <number>
  Used to specify the timeout for long polling of updates. A value of 0 is switching off any long poll. In this case no updates are automatically received and therefore also no messages can be received. It is recommended to set the pollingtimeout to a reasonable time between 15 (not too short) and 60 (to avoid broken connections). See also attribute disable.
• pollingVerbose <0_None 1_Digest 2_Log>
  Used to limit the amount of logging for errors of the polling connection. These errors are happening regularly and usually are not consider critical, since the polling restarts automatically and pauses in case of excess errors. With the default setting "1_Digest" once a day the number of errors on the last day is logged (log level 3). With "2_Log" every error is logged with log level 2. With the setting "0_None" no errors are logged. In any case the count of errors during the last day and the last error is stored in the readings PollingErrCount and PollingLastError
• disable <0 or 1>
  Used to disable the polling if set to 1 (default is 0).


• cmdTimeout <number>
  Used to specify the timeout for sending commands. The default is a value of 30 seconds, which should be normally fine for most environments. In the case of slow or on-demand connections to the internet this parameter can be used to specify a longer time until a connection failure is considered.


• maxFileSize <number of bytes>
  Maximum file size in bytes for transfer of files (images). If not set the internal limit is specified as 10MB (10485760B).
• filenameUrlEscape <0 or 1>
  Specify if filenames can be specified using url escaping, so that special chanarcters as in URLs. This specifically allows to specify spaces in filenames as %20. Default is off (0).
• maxReturnSize <number of chars>
  Maximum size of command result returned as a text message including header (Default is unlimited). The internal shown on the device is limited to 1000 chars.
• maxRetries <0,1,2,3,4,5>
  Specify the number of retries for sending a message in case of a failure. The first retry is sent after 10sec, the second after 100, then after 1000s (~16min), then after 10000s (~2.5h), then after approximately a day. Setting the value to 0 (default) will result in no retries.


• textResponseConfirm <TelegramBot FHEM : $peer\n Bestätigung \n>
  Text to be sent when a confirmation for a command is requested. Default is shown here and $peer will be replaced with the actual contact full name if added.
• textResponseFavorites <TelegramBot FHEM : $peer\n Favoriten \n>
  Text to be sent as starter for the list of favorites. Default is shown here and $peer will be replaced with the actual contact full name if added.
• textResponseCommands <TelegramBot FHEM : $peer\n Letzte Befehle \n>
  Text to be sent as starter for the list of last commands. Default is shown here and $peer will be replaced with the actual contact full name if added.
• textResponseResult <TelegramBot FHEM : $peer\n Befehl:$cmd:\n Ergebnis:\n$result\n>
  Text to be sent as result for a cmd execution. Default is shown here and $peer will be replaced with the actual contact full name if added. Similarly $cmd and $result will be replaced with the cmd and the execution result. If the result is a response with just spaces, or other separator characters the result will be not sent at all (i.e. a values of "\n") will result in no message at all.
• textResponseUnauthorized <UNAUTHORIZED: TelegramBot FHEM request from user :$peer\n Msg: $msg>
  Text to be sent as warning for unauthorized command requests. Default is shown here and $peer will be replaced with the actual contact full name and id if added. $msg will be replaced with the sent message.
• utf8Special <0 or 1>
  Specify if utf8 encodings will be resolved before sending to avoid issues with timeout on HTTP send (experimental ! / default is off).


Readings


• Contacts <text>
  The current list of contacts known to the telegram bot. Each contact is specified as a triple in the same form as described above. Multiple contacts separated by a space.


• msgId <text>
  The id of the last received message is stored in this reading. For secret chats a value of -1 will be given, since the msgIds of secret messages are not part of the consecutive numbering
• msgDate <timestamp>
  The timestamp of the last message receied representing the time when it was sent to telegram
• msgPeer <text>
  The sender name of the last received message (either full name or if not available @username)
• msgPeerId <text>
  The sender id of the last received message
• msgChat <text>
  The name of the Chat in which the last message was received (might be the peer if no group involved)
• msgChatId <ID>
  The id of the chat of the last message, if not identical to the private peer chat then this value will be the peer id
• msgText <text>
  The last received message text is stored in this reading. Information about special messages like documents, audio, video, locations or venues will be also stored in this reading
• msgFileId <fileid>
  The last received message file_id (Audio, Photo, Video, Voice or other Document) is stored in this reading.
• msgReplyMsgId <text>
  Contains the message id of the original message, that this message was a reply to


• prevMsgId <text>
  The id of the SECOND last received message is stored in this reading
• prevMsgDate <timestamp>
  The timestamp of the SECOND last received message . g
• prevMsgPeer <text>
  The sender name of the SECOND last received message (either full name or if not available @username)
• prevMsgPeerId <text>
  The sender id of the SECOND last received message
• prevMsgText <text>
  The SECOND last received message text is stored in this reading
• prevMsgFileId <fileid>
  The SECOND last received file id is stored in this reading

Note: All prev... Readings are not triggering events


• sentMsgId <text>
  The id of the last sent message is stored in this reading, if not succesful the id is empty
• sentMsgResult <text>
  The result of the send process for the last message is contained in this reading - SUCCESS if succesful


• StoredCommands <text>
  A list of the last commands executed through TelegramBot. Maximum 10 commands are stored.


• PollingErrCount <number>
  Show the number of polling errors during the last day. The number is reset at the beginning of the next day.
• PollingLastError <number>
  Last error message that occured during a polling update call


• callbackID <id> / callbackPeerId <peer id> / callbackPeer <peer>
  Contains the query ID (respective the peer id and peer name) of the last received inline query from an inline query button (see set ... inline)


Examples


• Send a telegram message if fhem has been newly started

  define notify_fhem_reload notify global:INITIALIZED set <telegrambot> message fhem started - just now



• A command, that will retrieve an SVG plot and send this as a message back (can be also defined as a favorite).

  Send the following message as a command to the bot ok fhem { plotAsPng('SVG_FileLog_Aussen') }
  assuming ok fhem is the command keyword)

  ( The png picture created by plotAsPng will then be send back in image format to the telegram client. This also works with other pictures returned and should also work with other media files (e.g. MP3 and doc files). The command can also be defined in a favorite.
  Remark: Example requires librsvg installed


• Allow telegram bot commands to be used
  If the keywords for commands are starting with a slash (/), the corresponding commands can be also defined with the Bot Father. So if a slash is typed a list of the commands will be automatically shown. Assuming that cmdSentCommands is set to /History. Then you can initiate the communication with the botfather, select the right bot and then with the command /setcommands define one or more commands like

  History-Show a history of the last 10 executed commands

  When typing a slash, then the text above will immediately show up in the client.

TellStick

[EN DE]

Define
define <name> TellStick </path/to/tdtool>

Defines a path to the program "tdtool", which is used to control a (locally attached) "Telldus TellStick [Duo]" USB device. A TellStick controls a wide range of 433 MHz devices, like the widely available switchable power outlets from InterTechno.

To keep things simple, FHEM interfaces with the telldus-core suite (available for Linux, Windows, Mac OSX) via the supplied tool, "tdtool". This FHEM module will initially use "tdtool --list" to receive a list of configured devices, then let autocreate (if enabled) create them as SIS_PMS devices.

Please make sure that the user running FHEM under ("fhem" in a standard setup on Linux) has the r/w-right to access the stick's device ("/dev/tellstick" in telldus-core version 2.0) — if the state of your devices do not change when modified im FHEM, access rights problems are the most probable cause (chmod o+rw /dev/tellstick should fix that; you may want to automate it via udev or adding the fhem user to the proper group ;))

This module has only been tested with the 2.0 branch of teldus-core because of a known bug in 2.1, preventing version 2.1 working properly with some TellSticks and/or "tdtool" application; FTR, the "Batch: 8" version a was granted usage of for writing this module was impacted by it ... To actually control any power sockets, you need to define a SIS_PMS device — TellStick.pm uses SIS_PMS devices ("socket" is te:ll:st:ck:01, "socketnr" is the ID of the device in "tdtool"), as as of now only on/off switching is supported and this was the easiest implementation path. SIS_PMS is supported by andFHEM, the Android frontend, so this make some sense. (Furthermore, I don't own dimmable devices and they are actually not really cheap; >15 EUR/socket compared to the 15 EUR for 5 switch-only, non-self learning socket adapters from Intertechno at your local home improvement store.)

Example:
define TStick TellStick /usr/bin/tdtool
define Deckenfluter SIS_PMS te:ll:st:ck:01 2



Set
N/A

Get
N/A

Attributes
• none

Tesla Powerwall 2 AC

[EN DE]

TeslaPowerwall2AC - Retrieves data from a Tesla Powerwall 2AC System
With this module it is possible to read the data from a Tesla Powerwall 2AC and to set it as reading.

Define

define <name> TeslaPowerwall2AC <HOST>

Example:

define myPowerWall TeslaPowerwall2AC 192.168.1.34


This statement creates a Device with the name myPowerWall and the Host IP 192.168.1.34.
After the device has been created, the current data of Powerwall is automatically read from the device.


Readings
• actionQueue - information about the entries in the action queue
• aggregates-* - readings of the /api/meters/aggregates response
• batteryLevel - battery level in percent
• batteryPower - battery capacity in kWh
• powerwalls-* - readings of the /api/powerwalls response
• registration-* - readings of the /api/customer/registration response
• siteinfo-* - readings of the /api/site_info response
• sitemaster-* - readings of the /api/sitemaster response
• state - information about internel modul processes
• status-* - readings of the /api/status response
• statussoe-* - readings of the /api/system_status/soe response
• setPassword - write password encrypted to password file
• removePassword - remove password from password file
get
• aggregates - fetch data from url path /api/meters/aggregates
• powerwalls - fetch data from url path /api/powerwalls
• registration - fetch data from url path /api/customer/registration
• siteinfo - fetch data from url path /api/site_info
• sitemaster - fetch data from url path /api/sitemaster
• status - fetch data from url path /api/status
• statussoe - fetch data from url path /api/system_status/soe


set
• removePassword - remove password from password file
• setPassword - save password in passswordfile ATTANTION!!! text must begin with pass= (Example: pass=meinpassword)


Attribute
• interval - interval in seconds for automatically fetch data (default 300)
• emailaddr - emailadress to get cookie token

Text2Speech

[EN DE]

Define

Local : define <name> Text2Speech <alsadevice>
Remote: define <name> Text2Speech <host>[:<portnr>][:SSL] [portpassword] Server: define <name> Text2Speech none


This module converts any text into speech with several possible providers. The Device can be defined as locally or remote instance.

• Local Device
  
  The output will be sent to any connected audio device. For example speakers connected per jack, network, WiFI or Bluetooth. Playback can be done using MPlayer or any other application.
  
  Mplayer installation under Debian/Ubuntu/Raspbian:
  apt-get install mplayer
  The given alsa device has to be configured in /etc/asound.conf

  Special AlsaDevice: default
  The internal Mplayer command will be without any audio directive if the given alsa device is default. In this case Mplayer is using the standard audio device.

  Example:
  define MyTTS Text2Speech hw=0.0
define MyTTS Text2Speech default

• Remote Device
  
  This module can be configured as remote-device for client-server environments. The Client has to be configured as local device.
  Notice: the Name of the locally instance has to be the same!
  • Host: setting up IP-adress
  • PortNr: setting up TelnetPort of FHEM; default: 7072
  • SSL: setting up if connect over SSL; default: no SSL
  • PortPassword: setting up the configured target telnet passwort

  Example:
  define MyTTS Text2Speech 192.168.178.10:7072 fhempasswd define MyTTS Text2Speech 192.168.178.10

  If a PRESENCE Device is avilable for the host IP-address, than this will be used to detect the reachability instead of the blocking internal method.
• Server Device
  In case of an usage as a server, only the mp3 file will be generated and displayed as lastFilename reading. It makes no sense to use the attribute TTS_speakAsFastAsPossible here. Its recommend, to use the attribute TTS_useMP3Wrap. Otherwise only the last audiobrick will be shown in reading lastFilename.

  Example:
  define MyTTS Text2Speech none

Set

• tts:
  Definition of text for voice output. To output mp3 files directly, they must be specified with leading and closing colons. Therefore, the text itself must not contain any double punctuation. The mp3 files must be stored in the TTS_FileTemplateDir directory. SSML can be used for the Amazon Polly language engine. See examples.
• volume:
  Setting up the volume audio response.
  Notice: Only available in locally instances!

Get

N/A

Attributes

• TTS_Delimiter
  Optional: By using the Google engine, its not possible to convert more than 100 characters in a single audio brick. With a delimiter the audio brick will be split at this character. A delimiter must be a single character!
  By default, each audio brick will be split at sentence end. Is a single sentence longer than 100 characters, the sentence will be split additionally at comma, semicolon and the word and.
  Notice: Only available in locally instances with Google engine!
• TTS_Ressource
  Optional: Selection of the Translator Engine
  Notice: Only available in locally instances!
  • Google
    Google Engine. Prerequisite: Active Internet connection
    This engine is recommended for its quality and is used by default.
  • VoiceRSS
    VoiceRSS Engine. Prerequisite: Active Internet connection
    Free of charge up to 350 requests per day. If you need more, you have to pay. This engine is also recommended due to its quality. To use this engine, you need an APIKey (see TTS_APIKey)
  • ESpeak
    eSpeak Engine. Prerequisite: Installation of Espeak and lame
    eSpeak is an open source software speech synthesizer for English and other languages.
  • SVOX-pico
    SVOX-Pico TTS-Engine (from the AOSP). Prerequisite: Installation of SVOX-Pico and lame
    sudo apt-get install libttspico-utils lame
    
    On ARM/Raspbian the package libttspico-utils,
    so you may have to compile it yourself or use the precompiled package from this guide, in short:
    sudo apt-get install libpopt-dev lame
cd /tmp
wget http://www.dr-bischoff.de/raspi/pico2wave.deb
sudo dpkg --install pico2wave.deb
  • Amazon-Polly
    Amazon Polly Engine. Prerequisite: Active Internet connection, Perl package Paws
    Amazon service that turns text into lifelike speech. An AWS Access and Polly Aws User is required.
    cpan paws
    The credentials to your AWS Polly are expected at ~/.aws/credentials
    [default] aws_secret_access_key = xxxxxxxxxxxxxxxxxxxxxx aws_access_key_id = xxxxxxxxxxxxxxx
  • maryTTS
    maryTTS or Mimic 3 Engine. Prerequisite: Installation of respective server and lame, appropriate settings in TTS_User attribute (if other than default settings shall be applied).
    Both are open source software speech synthesizers for English and other languages.
• TTS_Language
  Selection of different languages
• TTS_Language_Custom
  If you want another engine and speech of default languages, you can insert this here.
  The definition depends on the used engine. This attribute overrides an TTS_Language attribute.
  Please refer to the specific API reference.
• TTS_APIKey
  An APIKey is needed if you want to use VoiceRSS. You have to register at the following page:
  http://www.voicerss.org/registration.aspx
• TTS_User
  Actual only used for maryTTS (and Mimic 3). Needed in case if a TTS Engine needs a username and an APIKey for a request.
  

  (Full) example for maryTTS (values are defaults and may be left out):

  attr t2s TTS_User host=127.0.0.1 port=59125 lang=de_DE voice=de_DE/thorsten_low

• TTS_CacheFileDir
  Optional: The downloaded Google audio bricks are saved in this folder. No automatic delete/cleanup available.
  Default: cache/
  Notice: Available on local instances only!
• TTS_UseMP3Wrap
  For best voice output, it is recommended that the individual downloads are combined into a single file. Each downloaded audio bricks are concatinated to a single audio file to play with Mplayer.
  Installtion of the mp3wrap package is required.
  apt-get install mp3wrap
  Notice: Available on local instances only!
• TTS_MplayerCall
  Optional: Definition of the system call to Mplayer or a different tool.
  If a tool other than Mplayer is used, the following templates apply:
  
  • {device}
  • {volume}
  • {volumeadjust}
  • {file}
  • {options}
  {options} are provided inside the text in parentheses during the set command. Used for example to set special parameters for each call separately
  Example: set myTTS tts [192.168.0.1:7000] This is my text
  
  Examples:
  attr myTTS TTS_MplayerCall sudo /usr/bin/mplayer
attr myTTS TTS_MplayerCall AUDIODEV={device} play -q -v {volume} {file}
attr myTTS TTS_MplayerCall player {file} {options}
  
• TTS_SentenceAppendix
  Optional: Definition of one mp3-file to append each time of audio response.
  Mp3Wrap is required. The audio chunks must be downloaded to the CacheFileDir beforehand. Example: silence.mp3
• TTS_FileMapping
  Definition of mp3files with a custom template definition. Separated by space. All template definitions can be used in audiobricks by tts command. The definition must begin and end with a colon. The mp3files must be saved in TTS_FIleTemplateDir.
  attr myTTS TTS_FileMapping ring:ringtone.mp3 beep:MyBeep.mp3
set MyTTS tts Attention: This is my ringtone :ring: Its loud?
• TTS_FileTemplateDir
  Directory to save all mp3-files are defined in TTS_FileMapping und TTS_SentenceAppendix
  Optional, Default: cache/templates
• TTS_VolumeAdjust
  Basic volume increase
  Default: 110
  attr myTTS TTS_VolumeAdjust 400
• TTS_noStatisticsLog
  If set to 1, it prevents logging statistics to DbLog Devices, default is 0
  Note: This logging is important to be able to delete cache files that have not been used for a longer period of time. If you disable this, you will have to clean your cache directory manually.
• TTS_speakAsFastAsPossible
  Trying to get a speech as fast as possible. In case of not present audio bricks, you can hear a short break as the audio brick will be downloaded at this time. In case of a presentation of all audio bricks at local cache, this attribute has no impact.
  Attribute is only valid on local or server instances.
• TTS_OutputFile
  Definition of a fixed file name as mp3 output. The attribute is only relevant in conjunction with TTS_UseMP3Wrap. If a file name is specified, then TTS_CacheFileDir is also taken into account.
  attr myTTS TTS_OutputFile output.mp3
attr myTTS TTS_OutputFile /media/miniDLNA/output.mp3
  
• TTS_RemotePlayerCall
  The Text2Speech devices provide a URL to the last generated mp3 file: <protocol>://<fhem server ip or name>:<fhem port>/fhem/Text2Speech/<device name>/last.mp3.
  If this attibute contains a remote player call, it will be executed after the last mp3 file is generated.
  attr <device name> TTS_RemotePlayerCall GetFileFromURL('<protocol>://<remote player name or ip>:<remote player port>/?cmd=playSound&url=<protocol>://<fhem server name orip>:<fhem port>/fhem/Text2Speech/<device name>/last.mp3&loop=false&password=<password>')
  
• readingFnAttributes


• disable
  If this attribute is activated, the sound output will be disabled.
  Possible values: 0 => not disabled , 1 => disabled
  Default Value is 0 (not disabled)
  
  
• verbose
  4: each step will be logged
  5: Additionally the individual debug information from Mplayer and mp3wrap will be logged

Examples

define TTS_EG_WZ Text2Speech hw=/dev/snd/controlC3
attr TTS_EG_WZ TTS_Language English
attr TTS_EG_WZ TTS_Ressource Amazon-Polly
attr TTS_EG_WZ TTS_UseMP3Wrap 1

set MyTTS tts <speak>Mary had a little lamb.</speak>
define MyTTS Text2Speech hw=0.0
set MyTTS tts The alarm system is ready.
set MyTTS tts :beep.mp3:
set MyTTS tts :mytemplates/alarm.mp3:The alarm system is ready.:ring.mp3:
Example of MaryTTS and using SSML:
define T2S Text2Speech default attr T2S TTS_MplayerCall /usr/bin/mplayer attr T2S TTS_Ressource maryTTS attr T2S TTS_User host=192.168.100.1 port=59125 lang=de_DE voice=de_DE/thorsten_low ssml=1 set T2S tts '<voice name="de_DE/m-ailabs_low#rebecca_braunert_plunkett">Das ist ein Test in deutsch </voice><voice name="en_US/vctk_low#p236">and this is an test in english.</voice>'

Timer Modul

[EN DE]

The timer module is a programmable timer.

In Frontend you can define new times and actions. The smallest possible definition of an action is a 10 second interval.
You can use the dropdown menu to make the settings for the time switch point. Only after clicking on the Save button will the setting be taken over. In the drop-down list, the numerical values ​​for year / month / day / hour / minute / second are available for selection.

In addition, you can use the selection SR and SS in the hour and minute column. These rumps represent the time of sunrise and sunset.
For example, if you select at minute SS , you have set the minutes of the sunset as the value. As soon as you set the value to SS at hour and minute the timer uses the calculated sunset time at your location. (For this calculation the FHEM global attributes latitude and longitude are necessary!)

Programmable actions are currently:

• on | off - The states must be supported by the device
• DEF - for a PERL code or a FHEM command *
  
  
  example for DEF:
  • { Log 1, "Timer: now switch" } (PERL code)
  • update (FHEM command)
  • trigger Timer state:ins Log geschrieben (FHEM-command)
  • set TYPE=IT:FILTER=room=Stube.*:FILTER=state=on off (FHEM-command)

* To do this, enter the code to be executed in the respective attribute. example: Timer_03_set

Interval switching of the timer is only possible in the following variants:

• minute, define second and set all other values ​​(minute, hour, day, month, year) to all
• hourly, define second + minute and set all other values ​​(hour, day, month, year) to all
• daily, define second + minute + hour and set all other values ​​(day, month, year) to all
• monthly, define second + minute + hour + day and set all other values ​​(month, year) to all
• annually, define second + minute + hour + day + month and set the value (year) to all
• sunrise, define second & define minute + hour with SR and set all other values ​​(day, month, year) to all
• sunset, define second & define minute + hour with SS and set all other values ​​(day, month, year) to all

Any interval circuits can be defined in which in the associated timer attribute e.g. the following Perl code is inserted:
{if ($min % 5 == 0) {fhem("set FS10_6_11 toggle");}}
This timer would run every 5 minutes if the timer is configured to run in a minute as described.

The following variables for time and date are available:
$sec, $min, $hour, $mday, $month, $year, $wday, $yday, $isdst, $hms, $we, $today
This makes it possible, for example, to have a timer run every Sunday at 15:30:00.

Define

define <NAME> Timer

example:
define timer Timer

Set

• addTimer: Adds a new timer
• deleteTimer: Deletes the selected timer
• saveTimers: Saves the settings in file Timers.txt on directory ./FHEM/lib.
• sortTimer: Sorts the saved timers alphabetically.


Get

• loadTimers: Loads a saved configuration from file Timers.txt from directory ./FHEM/lib.


Attribute

• disable


• stateFormat
  It is used to format the value state
  example: { ReadingsTimestamp($name, "state", 0) ." - ". ReadingsVal($name, "state", "none");}
                 - will format to output: 2019-09-19 17:51:44 - Timer_04 saved


• Table_Border
  Shows the table border. (on | off = default)


• Table_Border_Cell
  Shows the cell frame. (on | off = default)


• Table_Header_with_time
  Shows or hides the sunrise and sunset with the local time above the table. (on | off, standard off)


• Table_Size_TextBox
  Correction value to change the length of the text box for the device name / designation. (default 20)


• Table_Style
  Turns on the defined table style. (on | off, default off)


• Table_View_in_room
  Toggles the tables UI in the room view on or off. (on | off, standard on)
  In the room Unsorted the table UI is always switched off!


• Timer_preselection
  Sets the input values ​​for a new timer to the current time. (on | off = default)


• Timer_xx_set
  Location for the FHEM command or PERL code of the timer (xx has the numerical value of 01-99). WITHOUT this attribute, which only appears if action DEF is set , The module does not process FHEM command or PERL code from the user. *


• Offset_Horizon
  Different elevation angles are used to calculate sunrise and sunset times.
  (REAL = 0°, CIVIL = -6°, NAUTIC = -12°, ASTRONOMIC = -18°, default REAL)


• Show_DeviceInfo
  Shows the additional information (alias | comment, default off)


Generated readings

• Timer_xx
  Memory values ​​of the individual timer


• internalTimer
  State of the internal timer (stop or Interval until the next call)



Hints:

• Entries in the system logfile like: 2019.09.20 22:15:01 3: Timer: time difference too large! interval=59, Sekunde=01 say that the timer has recalculated the time.

TrashCal

[EN DE]

Note: this module needs the HTTP::Request,HTML::Parser and LWP::UserAgent perl modules.
At this moment only city "Magdeburg" is supported at this site:
http://sab.metageneric.de/app/sab_i_tp/index.php

Define
define <name> TrashCal <type>

Defines a new instanze of Trashcalendar. At this time the <type> is not used
Examples:
define MyTrashCal TrashCal Restabfall


Set
N/A

Get
N/A

Attributes
• TrashCal_Link
  setting up the URL to grab the Trashcalendar
  Example:
  http://sab.metageneric.de/app/sab_i_tp/index.php?r=getHausnummerInfo&strasse=Torplatz&hausnummer=1&stadtteil_id=1609&dsd_behaelter_value=b120_b240
  
• readingFnAttributes


• disable
  If this attribute is activated, the module will be disabled.
  Possible values: 0 => not disabled , 1 => disabled
  Default Value is 0 (not disabled)
  
  
• verbose
  4: each major step will be logged
  5: Additionally some minor steps will be logged

Twilight

[EN DE]

General Remarks
This module profited much from the use of the yahoo weather API. Unfortunately, this service is no longer available, so Twilight functionality is very limited nowerdays. To some extend, the use of useExtWeather may compensate to dect cloudy skys. If you just want to have astronomical data available, consider using Astro instead.

Define
define <name> Twilight [<latitude> <longitude>] [<indoor_horizon> [<weatherDevice[:Reading]>]]

Defines a virtual device for Twilight calculations

latitude, longitude
The parameters latitude and longitude are decimal numbers which give the position on earth for which the twilight states shall be calculated. They are optional, but in case if set, you have to set both of them. If not set, global values will be used instead (global itself defaults to Frankfurt/Main).

indoor_horizon
The parameter indoor_horizon gives a virtual horizon, that shall be used for calculation of indoor twilight. Minimal value -6 means indoor values are the same like civil values. indoor_horizon 0 means indoor values are the same as real values. indoor_horizon > 0 means earlier indoor sunset resp. later indoor sunrise.
Defaults to 3 if not set.

weatherDevice:Reading
The parameter weatherDevice:Reading can be used to point to a device providing cloud coverage information to calculate twilight_weather.
The reading used shoud be in the range of 0 to 100 like the reading c_clouds in an openweathermap device, where 0 is clear sky and 100 are overcast clouds.
Example: MyWeather:cloudCover

NOTE 1: using useExtWeather attribute may override settings in DEF.

NOTE 2: If weatherDevice-type is known, is optional (atm only "Weather" or "PROPLANTA" type devices are supported).
A Twilight device periodically calculates the times of different twilight phases throughout the day. It calculates a virtual "light" element, that gives an indicator about the amount of the current daylight. Besides the location on earth it is influenced by a so called "indoor horizon" (e.g. if there are high buildings, mountains) as well as by weather conditions. Very bad weather conditions lead to a reduced daylight for nearly the whole day. The light calculated spans between 0 and 6, where the values mean the following:

light
0 - total night, sun is at least -18 degree below horizon
1 - astronomical twilight, sun is between -12 and -18 degree below horizon
2 - nautical twilight, sun is between -6 and -12 degree below horizon
3 - civil twilight, sun is between 0 and -6 degree below horizon
4 - indoor twilight, sun is between the indoor_horizon and 0 degree below horizon (not used if indoor_horizon=0)
5 - weather twilight, sun is between indoor_horizon and a virtual weather horizon (the weather horizon depends on weather conditions (optional)
6 - maximum daylight

state will reflect the current virtual "day phase" (0 = after midnight, 1 = sr_astro has passed, ...12 = ss_astro has passed)
Azimut, Elevation, Twilight
The module calculates additionally the azimuth and the elevation of the sun. The values can be used to control a roller shutter.

As a new (twi)light value the reading Twilight ist added. It is derived from the elevation of the sun with the formula: (Elevation+12)/18 * 100). The value allows a more detailed control of any lamp during the sunrise/sunset phase. The value ist betwenn 0% and 100% when the elevation is between -12° and 6°.

You must know, that depending on the latitude, the sun will not reach any elevation. In june/july the sun never falls in middle europe below -18°. In more northern countries(norway ...) the sun may not go below 0°.

Any control depending on the value of Twilight must consider these aspects.

Examples:

      define myTwilight Twilight 49.962529  10.324845 3 localWeather:clouds
    

      define myTwilight2 Twilight 4 localWeather
    


Set
N/A

Get
get <name> <reading>



light	the current virtual daylight value
nextEvent	the name of the next event
nextEventTime	the time when the next event will probably happen (during light phase 5 and 6 this is updated when weather conditions change
sr_astro	time of astronomical sunrise
sr_naut	time of nautical sunrise
sr_civil	time of civil sunrise
sr	time of sunrise
sr_indoor	time of indoor sunrise
sr_weather	time of weather sunrise
ss_weather	time of weather sunset
ss_indoor	time of indoor sunset
ss	time of sunset
ss_civil	time of civil sunset
ss_nautic	time of nautic sunset
ss_astro	time of astro sunset
azimuth	the current azimuth of the sun 0° ist north 180° is south
compasspoint	a textual representation of the compass point
elevation	the elevaltion of the sun
twilight	a percetal value of a new (twi)light value: (elevation+12)/18 * 100)
twilight_weather	a percetal value of a new (twi)light value: (elevation-WEATHER_HORIZON+12)/18 * 100). So if there is weather, it is always a little bit darker than by fair weather
condition	the yahoo condition weather code
condition_txt	the yahoo condition weather code as textual representation
horizon	value auf the actual horizon 0°, -6°, -12°, -18°


Attributes
• readingFnAttributes
• useExtWeather <device>[:<reading>] [<usercode>]
use data from other devices to calculate twilight_weather.
The reading used shoud be in the range of 0 to 100 like the reading c_clouds in an openweathermap device, where 0 is clear sky and 100 are overcast clouds.
Note: Atm. additional weather effects like heavy rain or thunderstorms are neglegted for the calculation of the twilight_weather reading.
By adding usercode, (Note: experimental feature! May work or not or lead to crashes etc....) you may get more realistic results for sr_weather and ss_weather calculation. Just return - besides the actual cloudCover reading value additional predicted values for corresponding indoor times, seperated by ":"


      Value_A:Value_B:Value_C
    

Value_A representing the actual cloudCover value, Value_B at sr_indoor and Value_C at ss_indoor (all values in 0-100 format).
Example:

      attr myTwilight useExtWeather MyWeather:cloudCover { myCloudCoverAnalysis("MyWeather") }
    

with corresponding code for myUtils:

    sub myCloudCoverAnalysis {
        my $weatherName = shift;
        my $ret = ReadingsVal($weatherName,"cloudCover",50);
        $ret .= ":".ReadingsVal($weatherName,"cloudCover_morning",55);
        $ret .= ":".ReadingsVal($weatherName,"cloudCover_evening",65);
        return $ret; 
    }
  


Functions
• twilight($twilight, $reading, $min, $max)
- implements a routine to compute the twilighttimes like sunrise with min max values.



$twilight	name of the twilight instance
$reading	name of the reading to use example: ss_astro, ss_weather ...
$min	parameter min time - optional
$max	parameter max time - optional


Example:

    define BlindDown at *{twilight("myTwilight","sr_indoor","7:30","9:00")} set xxxx position 100
    # xxxx is a defined blind

UBUS_CALL

The uBus IPC/RPC system is a common interconnect system used by OpenWrt. Services can connect to the bus and provide methods that can be called by other services or clients or deliver events to subscribers. This module implements the "call" type request. It is supposed to be used together with an UBUS_CLIENT device, which must be defined first.

Define

define <name> UBUS_CALL <module> <function> [<parameters>]

uBus calls are grouped under separate modules or "paths". In order to call a particular function, one needs to specify this path, the function to be called and optional parameters as <key>=<value> pairs. Examples:

• define <name> UBUS_CALL system board

• define <name> UBUS_CALL iwinfo devices

• define <name> UBUS_CALL network.device status name=eth0

• define <name> UBUS_CALL file list path=/tmp

• define <name> UBUS_CALL file read path=/etc/hosts

The supported calls highly depend on the device on which the uBus daemon is running and its firmware. To get an overview of the calls supported by your device, consult the readings of the UBUS_CLIENT device which represents the connection to the physical device. The <module>, <function> and each <value> can be in any of the following forms:

• A single keyword. In this case, only one call will be performed, with the module / function / parameter value set to the given content.
• A comma-separated list. In this case, one call will be performed for every value given in the list. Example:

  define <name> UBUS_CALL system board,info

  This will perform two calls, one to the function board and another to the function info.
• Perl code (enclosed in {}). The code may return a single keyword, a comma-separated list or an array reference. It is called whenever an uBus call is performed, and thus allows to set the value dynamically. If a single keyword is returned, only one call is performed, as if the keyword is given directly. If a comma-separated list or an array of keywords are returned, the call is performed for each of the returned values. Example:

  define <name> UBUS_CALL network.device status name={<code returning a list of network devices>>}

Note that the <module>, <function> and each <value> must not contain whitespace (since whitespace is used to separate the arguments). This also applies to Perl code. For longer pieces of code, it is recommended to define a sub in 99_myUtils.pm and call it from there.

If more than one comma-separated list or Perl code returning an array reference is used, calls are performed for each possible configuration. Example:

define <name> UBUS_CALL file stat,read path=/etc/hosts,/etc/group

This will perform four calls, to perform both stat and read on each of the two files. To distinguish the different calls when the response is received and parsed into readings, use a custom readings parser code, that makes use of the variables $MODULE, $FUNCTION and %PARAMS. These will contain the values used for the call, for which the response has been received.

See the FHEM wiki for further examples.

Set

• set <name> disable

  Sets the state of the device to inactive, disables periodic updates and disconnects a websocket connection.

• set <name> enable

  Enables the device, so that automatic updates are performed.

• set <name> update

  Performs an uBus call, updates the corresponding readings and resets any pending interval timer.

Get

There are no get commands defined.

Attributes

• disable
• disabledForIntervals

• attr <name> interval <interval>

  Defines the interval (in seconds) between performing consecutive calls and updating the readings.

• attr <name> IODev <device>

  If there are multiple UBUS_CLIENT devices defined, set this attribute to the value of the device which should be used to make the connection. It is not needed if there is only one device.

• attr <name> readings {<Perl-code>}

  Perl code which must return a hash of <key> => <value> pairs, where <key> is the name of the reading and <value> is its value. The following variables are available in the code:

  • $NAME: name of the UBUS_CALL device.
  • $MODULE: module name used in the call (see definition).
  • $FUNCTION: function name used in the call (see definition).
  • %PARAMS: hash of parameters used in the call (see definition).
  • $RAW: raw JSON response returned by the call.
  • $ERROR: reported error code, 0 means success.
  • %DATA: decoded result data as Perl hash.

  If this attribute is omitted, its default value is {FHEM::UBUS_CALL::DefaultReadings($RAW)}. This function executes json2nameValue in the JSON result and turns all returned data into readings named by their position in the JSON tree. It is also possible to call this function in user-defined Perl code first, and then modify the returned hash, for example by deleting unwanted readings or adding additional, computed readings. The variables $MODULE, $FUNCTION and %PARAMS contain the values used for the call, for which the response has been received, and can be used to give unique names to the readings.

Readings

Any readings are defined by the attribute readings.

UBUS_CLIENT

The uBus IPC/RPC system is a common interconnect system used by OpenWrt. Services can connect to the bus and provide methods that can be called by other services or clients or deliver events to subscribers. This module provides different methods to connect to an uBus interface, either using its command line interface or remotely via websocket or HTTP.

Define

define <name> UBUS_CLIENT <method>

The following connection methods for <method> are supported:

• For a websocket connection, a url of the form (ws|wss)://<host>[:port][/path] is used. Example:

  define <name> UBUS_CLIENT ws://192.168.1.1

• For a HTTP connection, a url of the form (http|https)://<host>[:port][/path] is used. Example:

  define <name> UBUS_CLIENT http://192.168.1.1/ubus

When using the websocket or HTTP connection methods, a valid user name and password must be provided. The user name defaults to user, but can be changed with an attribute:

attr <name> username <username>

The password is set with the following command, which must be issued only once, and stored as an obfuscated value on disk:

set <name> password <password>

When a connection and login have been performed successfully, a list command is executed to obtain the available calls supported by this device, and the result is filled into the readings of the device.

See the FHEM wiki for further examples.

Set

• set <name> disable

  Sets the state of the device to inactive, disables periodic updates and disconnects a websocket connection.

• set <name> enable

  Enables the device, establishing a websocket connection first if necessary.

• set <name> password <password>

  Sets the password used to authenticate via websocket or HTTP and stores it on disk.

Get

There are no get commands defined.

Attributes

• disable
• disabledForIntervals

• attr <name> refresh <period>

  Automatically check the connection after period seconds by issuing a session list request. If the session is expired, a new login is attempted. Some devices do not allow the session list command; in this case, set the value to 0 in order to disable the periodic refresh. The default value is 180 seconds.

• attr <name> timeout <period>

  Sets the timeout value in the login request, i.e., the period of inactivity after which a session expires. This should be set larger than the time between requests. The default value is 300 seconds.

• attr <name> username <username>

  Defines the username to be used for login via websocket or HTTP. The default value is user.

Readings

When the connection is established, the module executes a list command and creates the following readings:

• mod_<n>_name: name (path) of the n'th module in the uBus tree
• mod_<n>_func_<m>_name: name of the m'th function supported by the n'th module
• mod_<n>_func_<m>_param_<k>_name: name of the k'th parameter of the m'th function of the n'th module
• mod_<n>_func_<m>_param_<k>_type: type of the k'th parameter of the m'th function of the n'th module

These can be used to perform calls using the UBUS_CALL module.

UNIRoll

[EN DE]

The protocol is used by the Lott UNIROLL R-23700 reciever. The radio (868.35 MHz) messages are either received through an FHZ or an CUL device, so this must be defined first. Recieving sender messages is not integrated jet. The CUL has to allow working with zero synchbits at the beginning of a raw-message. This is possible with culfw 1.49 or higher.

Define
define <name> UNIRoll <devicegroup> <deviceaddress>

The values of devicegroup address (similar to the housecode) and device address (button) has to be defined as hexadecimal value. There is no master or group code integrated.

• <devicecode> is a 4 digit hex number, corresponding to the housecode address.
• <channel> is a 1 digit hex number, corresponding to a button of the transmitter.

Example:
define roll UNIRoll 7777 0


Set
set <name> <value> [<time>]

where value is one of:


    up
    stop
    down
    pos  (The attribute useRolloPos has to be set to 1 to use this.)
    [<time>] in seconds for up, down or pos
    

Examples:
set roll up
set roll up 10
set roll1,roll2,roll3 up
set roll1-roll3 up



Get
N/A

Attributes
• IODev
  Set the IO or physical device which should be used for sending signals for this "logical" device. An example for the physical device is an FHZ or a CUL. The device will not work without this entry.


• eventMap
  Replace event names and set arguments. The value of this attribute consists of a list of space separated values, each value is a colon separated pair. The first part specifies the "old" value, the second the new/desired value. If the first character is slash(/) or komma(,) then split not by space but by this character, enabling to embed spaces.
  
  Examples:
  attr device eventMap up:open down:closed
set device open


• showtime


• sendStopBeforeCmd <value>
  Before any up/down-command a stop-command will be sent to stop a random operation. This might cause failure in some situations. This attribute can be used to switch off the stop-command by setting it to these values.
  
  where value is one of:
  

          1 - send always stop (default)
          0 - send no stop
          2 - send stop only before up
          3 - send stop only before down
          

• useRolloPos <value>
  The position of each device can be stored. By this it is possible to move from any position to any other position. As this feature is software-based, a manual operation will not be recognized. To set the device into a definite state, a up or down command will reset the counter for the position.
  
  where value is one of:
  

          1 - RolloPos will be used
          0 - RolloPos is not used (default)
          

  
  These attributes will be created automatical if useRolloPos is set to 1. They will not be deleted, if the value is set to 0 or the attribut is deleted.

          rMin - Time in seconds for the topmost position
          rMax - Time in seconds until the device is fully closed
          rPos - This is an internal value and must not be changed!
          

• model
  The model attribute denotes the model type of the device. The attributes will (currently) not be used by the fhem.pl directly. It can be used by e.g. external programs or web interfaces to distinguish classes of devices and send the appropriate commands. The spelling of the model names are as quoted on the printed documentation which comes which each device. This name is used without blanks in all lower-case letters. Valid characters should be a-z 0-9 and - (dash), other characters should be ommited. Here is a list of "official" devices:
  
  Receiver/Actor: there is only one reciever: R_23700

USBWX

[EN DE]

The USBWX module interprets the messages received by the ELV USB-WDE1 weather receiver. This receiver is compaptible with the following ELV sensors: KS200/KS300, S300IA, S300TH, ASH2200, PS50. It also known to work with Conrad weather sensors KS555, S555TH and ASH555.
This module was tested with ELV S300TH, ELV ASH2200, ELV KS300, Conrad S555TH and Conrad KS555.
Readings and STATE of temperature/humidity sensors are compatible with the CUL_WS module. For KS300/KS555 sensors STATE is compatible with the KS300 module. The module is integrated into autocreate to generate the appropriate filelogs and weblinks automatically.

Note: this module requires the Device::SerialPort or Win32::SerialPort module if the devices is connected via USB or a serial port.

Define
define <name> USBWX <serial device>

Defines USB-WDE1 attached via usb.

define <name> USBWX <code> [corr1...corr4]

<code> is the code which must be set on the sensor. Valid values are 1 through 8.
9 is used as the sensor id of the ks300 sensor.
corr1..corr4 are up to 4 numerical correction factors, which will be added to the respective value to calibrate the device. Note: rain-values will be multiplied and not added to the correction factor.

Example:

    define USBWDE1 USBWX /dev/ttyUSB0
    define USBWX_1 USBWX 1
    define USBWX_livingroom USBWX 2
    define USBWX_ks300 USBWX 9
    

Set
N/A

Get
N/A

Attributes
• model
• loglevel

USF1000

[EN DE]

Fhem can receive your tank's fill level from the USF1000S device through a FHZ device, so one must be defined first. The state contains the fill level in % (lower case v in the device state) and the current volume in liters (upper case V in the device state). Measured distance to the liquid's surface, fill level, volume and warnings (Test mode, Battery low) are available. Due to the design of the USF1000S protocol, you can have only one USF1000S in range of your FHZ as these devices cannot be distinguished.

Define
define <name> USF1000 <geometry>

<geometry> determines the form of the tank and the position of the sensor. The following geometries are currently supported:


• cub <length> <width> <height> <offset>
• cylv <diameter> <height> <offset>

cub stands for a cuboid whose base is <length> × <width>. cylv stands for a vertical cylinder whose diameter is <diameter>. <height> is the distance of the surface of the liquid from the ground if the tank is full. <offset> is the distance of the sensor relative to the surface of the liquid. All quantities are expressed in meters.

Example:

define MyTank USF1000 cylv 2 1 0.3: a cylindrical water tank with 2 meters diameter. The water stands 1 meter high if the tank is full. The sensor is fixed 1,3 meters above ground.


Set
N/A

Get
N/A

Attributes
• IODev


• do_not_notify
• showtime
• model (usf1000s)
• ignore
• readingFnAttributes

UWZ

[EN DE]

This modul extracts thunderstorm warnings from www.unwetterzentrale.de.
Therefore the same interface is used as the Android App Alerts Pro does. A maximum of 10 thunderstorm warnings will be served. Additional the module provides a few functions to create HTML-Templates which can be used with weblink.
The following Perl-Modules are used within this module: HTTP::Request, LWP::UserAgent, JSON, Encode::Guess und HTML::Parse.

Define

define <Name> UWZ [CountryCode] [AreaID] [INTERVAL]


Example:
define Unwetterzentrale UWZ UK 08357 1800
attr Unwetterzentrale download 1
attr Unwetterzentrale humanreadable 1
attr Unwetterzentrale maps eastofengland unitedkingdom

define UnwetterDetails weblink htmlCode {FHEM::UWZ::UWZAsHtml("Unwetterzentrale")}
define UnwetterMapE_UK weblink htmlCode {FHEM::UWZ::UWZAsHtmlKarteLand("Unwetterzentrale","eastofengland")}
define UnwetterLite weblink htmlCode {FHEM::UWZ::UWZAsHtmlLite("Unwetterzentrale")} define UnwetterMovie weblink htmlCode {FHEM::UWZ::UWZAsHtmlMovie("Unwetterzentrale","clouds-precipitation-uk")}
 
• [CountryCode]
  Possible values: DE, AT, CH, UK, ...
  (for other countries than germany use SEARCH for CountryCode to start device in search mode)


• [AreaID]
  For Germany you can use the postalcode, other countries use SEARCH for CountryCode to start device in search mode.
  


• [INTERVAL]
  Defines the refresh interval. The interval is defined in seconds, so an interval of 3600 means that every hour a refresh will be triggered onetimes.
  




Example Search-Mode:
define Unwetterzentrale UWZ SEARCH

now get the AreaID for your location (example shows london):
get Unwetterzentrale SearchAreaID London

now redefine your device with the outputted CountryCode and AreaID.

 

Get


• get <name> soil-frost
  give info about current soil frost (active|inactive).


• get <name> extremfrost
  give info about current frost (active|inactive).


• get <name> thunderstorm
  give info about current thunderstorm (active|inactive).


• get <name> glaze
  give info about current glaze (active|inactive).


• get <name> glazed-rain
  give info about current freezing rain (active|inactive).


• get <name> hail
  give info about current hail (active|inactive).


• get <name> heat
  give info about current heat (active|inactive).


• get <name> rain
  give info about current rain (active|inactive).


• get <name> snow
  give info about current snow (active|inactive).


• get <name> storm
  give info about current storm (active|inactive).


• get <name> forest-fire
  give info about current forest fire (active|inactive).



Get (Search-Mode)


• get <name> SearchAreaID <city>
  Get AreaID coresponnding to entered location.



Set


• set <name> update
  Executes an imediate update of thunderstorm warnings.



Attributes


• download
  Download maps during update (0|1).
  
• savepath
  Define where to store the map png files (default: /tmp/).
  
• maps
  Define the maps to download space seperated. For possible values see UWZAsHtmlKarteLand.
  
• humanreadable
  Add additional Readings Warn_?_Start_Date, Warn_?_Start_Time, Warn_?_End_Date and Warn_?_End_Time containing the coresponding timetamp in a human readable manner. Additionally Warn_?_uwzLevel_Str and Warn_?_Type_Str will be added to device readings (0|1).
  
• lang
  Overwrite requested language for short and long warn text. (de|en|it|fr|es|..).
  
• sort_readings_by
  define how readings will be sortet (start|severity|creation).
  
• htmlsequence
  define warn order of html output (ascending|descending).
  
• htmltitle
  title / header for the html ouput
  
• htmltitleclass
  css-Class of title / header for the html ouput
  
• localiconbase
  define baseurl to host your own thunderstorm warn pics (filetype is png).
  
• intervalAtWarnLevel
  define the interval per warnLevel. Example: 2=1800,3=900,4=300
  



Readings


• Warn_0|1|2|3...|9_... - active warnings
• WarnCount - warnings count
• WarnUWZLevel - total warn level
• WarnUWZLevel_Color - total warn level color
• WarnUWZLevel_Str - total warn level string
• Warn_0_AltitudeMin - minimum altitude for warning
• Warn_0_AltitudeMax - maximum altitude for warning
• Warn_0_EventID - warning EventID
• Warn_0_Creation - warning creation
• Warn_0_Creation_Date - warning creation datum
• Warn_0_Creation_Time - warning creation time
• currentIntervalMode - default/warn, Interval is read from INTERVAL or INTERVALWARN Internal
• Warn_0_Start - begin of warnperiod
• Warn_0_Start_Date - start date of warnperiod
• Warn_0_Start_Time - start time of warnperiod
• Warn_0_End - end of warnperiod
• Warn_0_End_Date - end date of warnperiod
• Warn_0_End_Time - end time of warnperiod
• Warn_0_Severity - Severity of thunderstorm (0 no thunderstorm, 4, 7, 11, .. heavy thunderstorm)
• Warn_0_Hail - warning contains hail
• Warn_0_Type - kind of thunderstorm
• Warn_0_Type_Str - kind of thunderstorm (text)
• 1 - unknown
• 2 - storm
• 3 - snow
• 4 - rain
• 5 - frost
• 6 - forest fire
• 7 - thunderstorm
• 8 - glaze
• 9 - heat
• 10 - freezing rain
• 11 - soil frost
• Warn_0_uwzLevel - Severity of thunderstorm (0-5)
• Warn_0_uwzLevel_Str - Severity of thunderstorm (text)
• Warn_0_levelName - Level Warn Name
• Warn_0_ShortText - short warn text
• Warn_0_LongText - detailed warn text
• Warn_0_IconURL - cumulated URL to display warn-icons from www.unwetterzentrale.de

Weblinks

With the additional implemented functions UWZAsHtml, UWZAsHtmlLite, UWZAsHtmlFP, UWZAsHtmlKarteLand and UWZAsHtmlMovie HTML-Code will be created to display warnings and weathermovies, using weblinks.


Example:

• define UnwetterDetailiert weblink htmlCode {FHEM::UWZ::UWZAsHtml("Unwetterzentrale")}


• define UnwetterLite weblink htmlCode {FHEM::UWZ::UWZAsHtmlLite("Unwetterzentrale")}


• define UnwetterFloorplan weblink htmlCode {FHEM::UWZ::UWZAsHtmlFP("Unwetterzentrale")}


• define UnwetterKarteLand weblink htmlCode {FHEM::UWZ::UWZAsHtmlKarteLand("Unwetterzentrale","Bayern")}
• The second parameter should be one of:
  • europa
  
  
  • deutschland
  • deutschland-small
  • niedersachsen
  • bremen
  • bayern
  • schleswig-holstein
  • hamburg
  • mecklenburg-vorpommern
  • sachsen
  • sachsen-anhalt
  • nordrhein-westfalen
  • thueringen
  • rheinland-pfalz
  • saarland
  • baden-wuerttemberg
  • hessen
  • brandenburg
  • berlin
  
  
  • oesterreich
  • burgenland
  • kaernten
  • niederoesterreich
  • oberoesterreich
  • salzburg
  • steiermark
  • tirol
  • vorarlberg
  • wien
  
  
  • schweiz
  • aargau
  • appenzell_ausserrhoden
  • appenzell_innerrhoden
  • basel_landschaft
  • basel_stadt
  • bern
  • fribourg
  • geneve
  • glarus
  • graubuenden
  • jura
  • luzern
  • neuchatel
  • nidwalden
  • obwalden
  • schaffhausen
  • schwyz
  • solothurn
  • stgallen
  • ticino
  • thurgau
  • uri
  • waadt
  • wallis
  • zug
  • zuerich
  
  
  • liechtenstein
  
  
  • belgique
  
  
  • denmark
  
  
  • finnland
  
  
  • france
  • alsace
  • aquitaine
  • basse-normandie
  • bretagne
  • champagne-ardenne
  • franche-comte
  • haute-normandie
  • ile-de-france
  • languedoc-roussillon
  • limousin
  • lorraine
  • bourgogne
  • centre
  • midi-pyrenees
  • nord-pas-de-calais
  • pays-de-la-loire
  • picardie
  • poitou-charentes
  • provence-alpes-cote-dazur
  • rhone-alpes
  
  
  • letzebuerg
  
  
  • nederland
  • drenthe
  • flevoland
  • friesland
  • gelderland
  • groningen
  • limburg
  • noordbrabant
  • noordholland
  • overijssel
  • utrecht
  • zeeland
  • zuidholland
  
  
  • norwegen
  
  
  • portugal
  
  
  • sverige
  
  
  • espana
  
  
  • unitedkingdom
  • eastofengland
  • eastmidlands
  • london
  • northeastengland
  • northernireland
  • northwestengland
  • scotland
  • southeastengland
  • southwestengland
  • wales
  • westmidlands
  • yorkshireandthehumber
  
  
  • isobaren1
  • isobaren2
  • isobaren3
• define UnwetterKarteMovie weblink htmlCode {FHEM::UWZ::UWZAsHtmlMovie("Unwetterzentrale","currents")}
• The second parameter should be one of:
  • niederschlag-wolken
  • stroemung
  • temperatur
  
  
  • niederschlag-wolken-de
  • stroemung-de
  
  
  • niederschlag-wolken-ch
  • stroemung-ch
  
  
  • niederschlag-wolken-at
  • stroemung-at
  
  
  • neerslag-wolken-nl
  • stroming-nl
  
  
  • nuages-precipitations-fr
  • courants-fr
  
  
  • clouds-precipitation-uk
  • currents-uk
  
  

UbiquitiMP

[EN DE]

FHEM module for the Ubiquiti mFi mPower modules
Please read also the Wiki at https://wiki.fhem.de/wiki/Ubiquit_mFi/mPower
FHEM Forum : http://forum.fhem.de/index.php/topic,35722.0.html Define
define <name> UbiquitiMP <IP or FQDN>
example :
define myUbi UbiquitiMP 192.168.0.100
define myUbi UbiquitiMP myhost.mynet.net
Perl Net::Telnet and JSON module are required. On a Raspberry you can install them with :
sudo apt-get install libjson-perl
sudo apt-get install libnet-telnet-perl

Set
• Outx on / off (force) -> turns Port x on or off
• Outx toggle -> toggle port
• Outx lock / unlock -> protects port to switch port on/off
• Outx reset -> reset power counter for this port
• Outx enable / disable -> power counting for this port
Get
• status -> returns the status of all Outs
• info -> returns some internal informations of the device
• reboot -> reboot the device


Attributes
• ignoreList -> list of ignored ports
  e.g. attr name ignoreList 456
  ignores all values of ports 4,5 & 6
  
• groupPorts -> space separeted list to group ports so you can use them like a single device
  e.g. attr name groupPorts TV=12 Media=4,5,6 (GroupName=Port numbers in the group)
  set name TV on or set name Media toggle
• ledconnect -> led color since fhem connect
• subDevices -> use a single sub devices for each out port
  (default 1 for the 3 and 6 port mPower, default 0 for the mPower mini) requires 98_UbiquitiOut.pm
• interval -> polling interval in seconds, set to 0 to disable polling (default 300)
• timeout -> seconds to wait for a answer from the Power Module (default 5 seconds)
• user -> defined user on the Power Module (default ubnt)
• password -> password for user (default ubnt)

UbiquitiOut

[EN DE]

sub device for the UbiquitiMP or InfratekPM modul

Define
define <name> UbiquitiOut <UbiquitiMP device> <Out #>
Set
set Extensions

Unifi

[EN DE]

Unifi is the FHEM module for the Ubiquiti Networks (UBNT) - Unifi Controller.

e.g. you can use the 'presence' function, which will tell you if a device is connected to your WLAN (even in PowerSave Mode!).
Immediately after connecting to your WLAN it will set the device-reading to 'connected' and about 5 minutes after leaving your WLAN it will set the reading to 'disconnected'.
The device will be still connected, even it is in PowerSave-Mode. (In this mode the devices are not pingable, but the connection to the unifi-controller does not break off.)

Or you can use the other readings or set and get features to control your unifi-controller, accesspoints and wlan-clients.


Prerequisites

The Perl module JSON is required.
On Debian/Raspbian: apt-get install libjson-perl
Via CPAN: cpan install JSON

Define

define <name> Unifi <ip> <port> <username> <password> [<interval> [<siteID>]]


<name>:
The FHEM device name for the device.

<ip>:
The ip of your unifi-controller.

<port>:
The port of your unifi-controller. Normally it's 8443 or 443.

<username>:
The Username to log on.

<password>:
The password to log on.

[<interval>]:
(optional without <siteID>)
Interval to fetch the information from the unifi-api.
default: 30 seconds

[<siteID>]:
(optional)
You can find the site-ID by selecting the site in the UniFi web interface.
e.g. https://192.168.12.13:8443/manage/s/foobar the siteId you must use is: foobar.
default: default

UDM?
If you use an UDM as Controller:
Additionally set Attribute isUDM to 1.




Examples

define my_unifi_controller Unifi 192.168.1.15 443 admin secret

Or with optional parameters <interval> and <siteID> :
define my_unifi_controller Unifi 192.168.1.15 443 admin secret 30 default


Set

Note: Some setters are not available if controller is not connected, or no data is available for them.


• set <name> update
  Makes immediately a manual update.


• set <name> updateClient <mac>
  Makes immediately a manual update of the client specified by MAC-Adress.


• set <name> clear <readings|clientData|voucherCache|all>
  Clears the readings, clientData, voucherCache or all.


• set <name> archiveAlerts
  Archive all unarchived Alerts.


• set <name> disconnectClient <all|user_id|controllerAlias|hostname|devAlias>
  Disconnect one ore all clients.


• set <name> restartAP <all|_id|name|ip>
  Restart one ore all accesspoints.


• set <name> setLocateAP <all|_id|name|ip>
  Start 'locate' on one or all accesspoints.


• set <name> unsetLocateAP <all|_id|name|ip>
  Stop 'locate' on one or all accesspoints.


• set <name> startRFScan <all|_id|name|ip>
  Start 'RF-Scan' on one or all accesspoints. Does not work with 1. Gen APs.


• set <name> blockClient <clientname>
  Block the <clientname>. Can also be called with the mac-address of the client.


• set <name> unblockClient <clientname>
  Unblocks the <clientname>. Can also be called with the mac-address of the client.


• set <name> disableWLAN <ssid>
  Disables WLAN with <ssid>


• set <name> enableWLAN <ssid>
  Enables WLAN with <ssid>


• set <name> switchSiteLEDs <on|off>
  Enables or disables the Status-LED settings of the site.


• set <name> createVoucher <expire> <n> <quota> <note>
  Creates <n> vouchers that expires after <expire> minutes, are usable <quota>-times with a <note>no spaces in note allowed


• set <name> removeClientReadings <clientname>
  Deletes the readings for <clientname>. Only disconnected clients should be removed, because connected clients will create readings in next update-cycle.


• set <name> refreshUCversion
  Refresh the INTERNAL-value for the version of your unifi-controller.


• set <name> refreshUsergroups
  Usergroups won't be updated automatically. Use this setter to update usergroups manually.



Get

Note: Some getters are not available if no data is available for them.


• get <name> clientData <all|user_id|controllerAlias|hostname|devAlias>
  Show more details about clients.


• get <name> deviceData <all|AP-Name;
  Show data of the specified (or all) device(s) in (simple formatted) json. Can be used for userreadings (use decode_json(..) in myUtils.pm).


• get <name> events
  Show events in specified 'eventPeriod'.


• get <name> unarchivedAlerts
  Show all unarchived Alerts.


• get <name> voucher [note]
  Show next voucher-code with specified note. If <note> is used in voucherCache the voucher will be marked as delivered


• get <name> voucherList [all|note]
  Show list of vouchers (all or with specified note only).


• get <name> showAccount
  Show decrypted user and passwort.



Attributes

• attr devAlias
  Can be used to rename device names in the format <user_id|controllerAlias|hostname>:Aliasname.
  Separate using blank to rename multiple devices.
  Example (user_id): attr unifi devAlias 5537d138e4b033c1832c5c84:iPhone-Claudiu
  Example (controllerAlias): attr unifi devAlias iPhoneControllerAlias:iPhone-Claudiu
  Example (hostname): attr unifi devAlias iphone:iPhone-Claudiu
  


• attr eventPeriod <1...168>
  Can be used to configure the time-period (hours) of fetched events from controller.
  default: 24


• attr disable <1|0>
  With this attribute you can disable the whole module.
  If set to 1 the module will be stopped and no updates are performed.
  If set to 0 the automatic updating will performed.


• attr ignoreWiredClients <1|0>
  With this attribute you can disable readings for wired clients.
  If set to 1 readings for wired clients are not generated.
  If set to 0 or not defined, readings for wired clients will be generated.


• attr ignoreWirelessClients <1|0>
  With this attribute you can disable readings for wireless clients.
  If set to 1 readings for wireless clients are not generated.
  If set to 0 or not defined, readings for wireless clients will be generated.


• attr verbose 5
  This attribute will help you if something does not work as espected.


• attr httpLoglevel <1,2,3,4,5>
  Can be used to debug the HttpUtils-Module. Set it smaller or equal as your 'global verbose level'.
  default: 5


• attr voucherCache <expire n quota note, ...>
  Define voucher-cache(s). Comma separeted list of four parameters that are separated by spaces; no spaces in note!.
  By calling get voucher <note> the delivery-time of the voucher will be saved in the cache. The voucher with the oldest delivery-time will be returned by get voucher <note>. If the voucher is not used for 2 hours, the delivery-time in the cache will be deleted.
  e.g.: 120 2 1 2h,180 5 2 3h defines two caches.
  The first cache has a min size of 2 vouchers. The vouchers expire after 120 minutes and can be used one-time.
  The second cache has a min size of 5 vouchers. The vouchers expire after 180 minutes and can be used two-times.


• attr customClientReadings clientNameRegEx1:ClientReadingRegEx1 clientNameRegEx2:ClientReadingRegEx2 ...
  Can be used to customize the readings for clients.
  default: .:^accesspoint$|^essid$|^hostname$|^last_seen$|^snr$|^uptime$ Note: rssi ist called snr in old default before attr customClientReadings.


• attr customClientNames <value>
  Can be used to control the naming convention for client readings. Any valid clientData field is allowed, though only mac seems to be useful. For a list, see <unifi> get ClientData all.
  When using formatted readings (reading is named like <clientName>_f_...) with disconnected clients e.g. in DOIF or notifies, also specify the unformatted value as customClientReading.
  e.g. ^_f_last_seen_duration$|^last_seen$
  Reason: Disconnected clients won't be send by UnifiController and are loosing their values when restarting fhem. The UnifiModul tries to restore the clients from existing readings. This won't work for formatted readings if the unformatted value hasn't a reading itself.
  Client naming follows these rules:
  1. devAlias (if present for this client)
  2. attribute customClientNames (if it is set and the corresponding data field exists for client)
  3. name (alias) in Unifi-Controller
  4. hostname of the client


• attr isUDM <0,1>
  Informs the module that the Unifi-Controller API is provided by an UDM if set to 1.
  default: 0


• readingFnAttributes

Readings

Note: All readings generate events. You can control this with these global attributes.
• When clientnames start with a . (dot), FHEMWEB hides readings for this client when global showInternal Values ne 1.
• Each client has 7 readings for connection-state, SNR, uptime, last_seen-time, connected-AP, essid and hostname if attribute customClientReadings is not used.
• -UC_newClients shows names of a new clients, could be a comma-separated list. Will be set to empty at next interval.
• -UC_blockedClients shows names of a blocked clients, could be a comma-separated list.
• Each AP has 5 readings for state (can be 'ok' or 'error'), essid's, utilization, locate and count of connected-clients.
• The unifi-controller has 6 readings for event-count in configured 'timePeriod', unarchived-alert count, accesspoint count, overall wlan-state (can be 'ok', 'warning', or other?), connected user count and connected guest count.
• The unifi-controller has also readings for wan_ip and results of the speedtest (UC_speed_ping,UC_speed_down,UC_speed_up).
• The Unifi-device reading 'state' represents the connection-state to the unifi-controller (can be 'connected', 'disconnected', 'initialized' and 'disabled').
• Each voucher-cache has a reading with the next free voucher code.

UnifiClient

[EN DE]

UnifiClient is the FHEM module for the Ubiquiti Networks (UBNT) Client.

You can use the readings or set features to control your clients.


Prerequisites

• A connected Unifi-Device as IODev.
• The Perl module JSON is required.
  On Debian/Raspbian: apt-get install libjson-perl
  Via CPAN: cpan install JSON

Define

define <name> UnifiClient <clientName>
<name>:
The FHEM device name for the device.

<clientName>:
The name of the client in unifi-module.


Set

• set <name> clear <readings|usedOnlineTime>
  Clears the readings or set the usedOnlimeTime=0.


• set <name> blockClient <
  Blocks the client.


• set <name> unblockClient <
  Unblocks the client.


• set <name> usergroup <
  Set the usergroup for the client.


• set <name> update <
  Updates the client data.



Get

• get <usergroups> todo
  Show information about the configuered usergroups in UnifiController.



Attributes

• attr maxOnlineMinutesPerDay <number>
  Defines the maximum minutes this client is allowed to use the unifi-network. The client will be blocked when the reading fhem_usedOnlineTime is above this attribute.
  


• attr thresholdBytesPerMinute <number>
  Clients often use the network without user interaction. Define a threshold thats allowed per Minute without counting to usedOnlineTime.
  Default: 75000
  


• readingFnAttributes

Readings

Note: All readings generate events. You can control this with these global attributes.
• todo
  todo.

UnifiProtect

[EN DE]

Module to integrate UnifiProtect devices with FHEM.

define <name> UnifiProtect <ip> <user> <password>

Notes:
• JSON has to be installed on the FHEM host.
• create protect read only user: users->invite users->local access only
• define <name> webLink htmlCode {UnifiProtect_2html('<nvr>','<cam>[,<cam2>,..]'[,<width>])}

Set
• snapshot cam=<cam> width=<width> fileName=<fileName>
  takes a snapshot from <cam> with optional <width> and stores it with the optional <fileName>
  <cam> can be the number of the camera, its id or a regex that is matched against the name.
• reconnect
  
Get
• user
  shows the configured user.
• password
  shows the configured password.
Attr
• filePath
  path to store the snapshot images to. default: .../www/snapshots
• user
  user to use for nvr access
• password
  password to use for nvr access

UnifiSwitch

[EN DE]

UnifiSwitch is the FHEM module for the Ubiquiti Networks (UBNT) Switch - USW.

You can use the readings or set features to control your unifi-switch.


Prerequisites

• A connected Unifi-Device as IODev.
• The Perl module JSON is required.
  On Debian/Raspbian: apt-get install libjson-perl
  Via CPAN: cpan install JSON

Define

define <name> UnifiSwitch <ip> <nameOfSwitch>
Normaly this device will be autocreated!

<name>:
The FHEM device name for the device.

<nameOfSwitch>:
The name of the switch in unifi-controller.


Set

• set <name> clear <readings|all>
  Clears the readings or all.


• set <name> poeMode <port> <off|auto|passive|passthrough|restart>
  Set PoE mode for <port>.


• set <name> disablePort <port>
  Only visible when Attr portProfileDisableID is set.
  Set the PortProfile from Attr portProfileDisableID for <port>.
• set <name> portProfile <port>
  Set the PortProfile ID. The ID can be found with get portOverrides.

Get

• get <name> poeState
  Show more details about the ports of the switch.


• get <name> portOverrides
  Show more details about the portOverrides of the switch.



Attributes

• attr portProfileDisableID
  Quick Workaround for special purposes: Must contain the ID off the disable-PortConfig. Then set disablePort can be used.
  The ID can be found with get portOverrides.
  To enable the port the UnifiController-Software must be used.


• readingFnAttributes

Readings

Note: All readings generate events. You can control this with these global attributes.
• There are some readings for the switch in general (prefix switch_).
• switch_general_temperature
  Only if switch has temperature-sensor.
• switch_overheating
  Only if switch has temperature-sonsor. Values: 0 if normal, Value for overheated is unknown at the moment (please contact maintainer if you know the value).
• switch_fan-level
  Only if switch has fan.
• switch_cpu
  CPU-usage in percent.
• switch_mem
  Memory-usage in percent.
• Each port has the readings name and state. POE-ports have more readings (prefix port_XX_; XX is portNumber).
• port_XX_name
  The name of the port as defined in UnifiController.
• port_XX_state
  The connection state of the port. Can be disconnected or in Mbps/Gbps.
• port_XX_poe_current
  The current of the port.
• port_XX_poe_mode
  The poe-mode of the port.
• port_XX_poe_power
  The power of the port.
• port_XX_poe_voltage
  The voltage of the port.

UnifiVideo

[EN DE]

Module to integrate UnifiVideo devices with FHEM.

define <name> UnifiVideo <ip> [<apiKey>]

Notes:
• JSON has to be installed on the FHEM host.
• create nvr api key: admin->my account->api access
• define <name> webLink htmlCode {UnifiVideo_2html('<nvr>','<cam>[,<cam2>,..]'[,<width>])}

Set
• snapshot cam=<cam> width=<width> fileName=<fileName>
  takes a snapshot from <cam> with optional <width> and stores it with the optional <fileName>
  <cam> can be the number of the camera, its id or a regex that is matched against the name.
• reconnect
  
Get
• apiKey
  shows the configured apiKey.
Attr
• filePath
  path to store the snapshot images to. default: .../www/snapshots
• apiKey
  apiKey to use for nvr access
• ssh_user
  ssh user for nvr logfile access. used to fhem events after motion detection.

Utils

[EN DE]

This is a collection of functions that can be used module-independant in all your own development

Defined functions


• abstime2rel("HH:MM:SS")
  tells you the difference as HH:MM:SS between now and the argument


• ltrim("string")
  returns string without leading spaces


• max(str1, str2, ...)
  returns the highest value from a given list (sorted alphanumeric)


• maxNum(num1, num2, ...)
  returns the highest value from a given list (sorted numeric)


• min(str1, str2, ...)
  returns the lowest value from a given list (sorted alphanumeric)


• minNum(num1, num2, ...)
  returns the lowest value from a given list (sorted numeric)


• rtrim("string")
  returns string without trailing spaces


• time_str2num("YYYY-MM-DD HH:MM:SS")
  convert a time string to number of seconds since 1970


• trim("string")
  returns string without leading and without trailing spaces


• UntoggleDirect("deviceName")
  For devices paired directly, converts state 'toggle' into 'on' or 'off'


• UntoggleIndirect()
  For devices paired indirectly, switches the target device 'on' or 'off', also when a 'toggle' was sent from the source device


• defInfo("devspec", "internal")
  return an array with the internal values of all devices found with devspec, e.g. defInfo("TYPE=SVG", "GPLOTFILE").


• SVG_time_to_sec("YYYY-MM-DD_HH:MM:SS")
  converts the argument to the number of seconds since 1970. Optimized for repeated use of similar timestamps.


• fhemNc("host:port", "textToSend", waitForReturn)
  sends textToSend to host:port, and if waitForReturn is set, then read the answer (wait up to 5 seconds) and return it. Intended as small nc replacement.


• round(value, digits)
  round <value> to given digits behind comma


• getUniqueId()
  return the FHEM uniqueID used by the fheminfo command. Uses the getKeyValue / setKeyValue functions.


• setKeyValue(keyName, value)
  store the value in the file $modpath/FHEM/FhemUtils/uniqueID (the name is used for backward compatibility), or in the database, if using configDB. value may not contain newlines, and only one value per key is stored. The file/database entry will be written immediately, no explicit save is required. If the value is undef, the entry will be deleted. Returns an error-string or undef.


• getKeyValue(keyName)
  return ($error, $value), stored previously by setKeyValue. $error is set if there was an error. Both are undef, if there is no value yet for this key.


• sortTopicNum("asc"|"desc",<list of numbers>)
  sort an array of numbers like x.x.x
  (Forum #98578)


• Svn_GetFile(from, to, [finishFn])
  Retrieve a file diretly from the fhem.de SVN server.
  If the third (optional) parameter is set, it must be a function, which is executed after the file is saved. Example:
  { Svn_GetFile("contrib/86_FS10.pm", "FHEM/86_FS10.pm") } { Svn_GetFile("contrib/86_FS10.pm", "FHEM/86_FS10.pm", sub(){CommandReload(undef, "86_FS10")}) }


• WriteFile(file, content)
  Write a file in/below the curent directory. Example:
  attr m2d readingList map:.* { WriteFile("www/images/map.png",$EVENT);; {map=>"images/map.png"} } attr m2d devStateIcon { '<img src="fhem/images/map.png" style="max-width:256;;max-height:256;;">' }

VBUSDEV

[EN DE]

RESOL-Adapter (USB oder LAN) Info:
http://www.resol.de/

Information http://hobbyelektronik.org/w/index.php/VBus-Decoder/ or github https://github.com/pejonp/vbus



Define
define <name> VBUSDEV <id> [<interval>]

Connects to various RESOL VBus devices
Examples:
define VBUSDEV_7321 VBUSDEV 7321


Readings
• The readings are dependant of the model of the VBUS device.

VBUSIF

[EN DE]

This module connects to the RESOL VBUS LAN or Serial Port adapter. It serves as the "physical" counterpart to the VBUSDevice devices.

Define
define <name> VBUS <device>

<device> is a <host>:<port> combination, where <host> is the address of the RESOL LAN Adapter and <port> 7053.
Please note: the password of RESOL Device must be unchanged at <host>
Examples:
define vbus VBUSIF 192.168.1.69:7053
define vbus VBUSIF /dev/ttyS0

VCLIENT

[EN DE]

This modul provides a GUI for Viessmann heatings. Whereas VCONTROL and VCONTROL300 send and receive commands directly VCLIENT is based on the external running daemon 'vcontrold.
Viessmann is only controlled by vcontrold. This modul only connects to vcontrold and is more or less a vcontrold client for FHEM. If a command does not do what it should this is caused by vcontrold not VCLIENT.

Requirements

This module only works if on another (external) host vcontrold is running. Furthermore, an Optolink cable (by Viessmann or DIY) must be connected to the heating and the host as well. Otherwise VCLIENT will not giv any results. For installation and running of vcontrold as well as Optolink cables see https://github.com/openv/openv
(In this module the FHEM commands and vcontrold commands are called get-commands and set-commands. FHEM commands and vcontrold commands must be kept linguistically separate.)

Requirement

VCLIENT requires a configuration file. In this file there are entries line by line. Every line allocates a vcontrold-command to a reading name. If the command specified in the line is executed, the result obtained by vcontrold is written to the corresponding reading. A typical line in the configuration file looks like this:


  ###### VCLIENT configuration file #########
  #This is a commend
  getTempA outsidetemperatur
  getTempBrennerstarts burnerstarts
  getTempBrennerstarts burnerstartsTillYesterday daily
  #up to now these were get commands, now we look at set commands
  getTimerWWMo HotWater_1Monday manually
  setTimerWWMo WW_1Mo_late 08:00-10:00|12:00-12:30|| 
  setTempWW HotWaterTemp 70,65,60,55


Get commands:The vcontrold command must be the first word in the line, no spaces allowed (e.g., getTempWW). The return of the vcontrold command "getTempA" is then written to the VCLIENT reading, in this case "outsidetemperature". Please use a separate line for each command. If a command is to be executed only once a day, the third word in the cfg file must be "daily". If a command is only to be executed manually, the third word in the cfg file must be "manually". The format of time commands (so-called timers) is recognized automatically.
Set commands:The vcontrold command must be the first word in the line, no spaces allowed (e.g., setTempWW). Then the name to be used in the FHEM set command is given, here HotWaterTemp (the complete FHEM command would be set <name> HotWaterTemp 65). Finally, the possible selections of a dropdown list are displayed in the line. It is indispensable that the values to be selected are comma-separated and written without spaces. Timer commands make an exception here. Again, the vcontrold command (here setTimerWWMo) is executed first, followed by the command that triggers the FHEM entries (here set <name> WW_1Mo_late). In FHEM, however, the times of the day are not entered, but rather in the cfg file. There must be an even number of times, a maximum of eight. The times of the day must be separated by exactly three separators | from each other. The times, in turn, are to be written using the entries HH:MM-HH:MM. Only minutes that are multiples of 10 are permitted (something like 08:14 is not allowed); the later specifications must be to right (something like 08:00-07:00 is not allowed). The times as well as the set command must not contain any spaces.

Define

define <name> VCLIENT <host> <port> <configfilename> <interval>

<host> is the host on which vcontrold is running.
<port> is the port for vcontrold (usually 3002).
<configfilename> is the configuration file, see above.
<interval> is the time difference in seconds for regular queries. The value 0 (only manual queries) is possible.


Set


reload_command_file
set <name> reload_command_file <configfilename>
Changes the name and/or path of the configuration file. The file must exist, otherwise an error message appears (specify full path).
<vcontrold/FHEM command>
set <name> <vcontrold/FHEM command> args
The set command can also be used to execute vcontrold commands. These commands must be defined before in the cfg configuration file. If you look at the above example of a configuration file, a FHEM command in the form set <name> HotWaterTemp 70 would send the command setTempWW 70 internally to the heating: vcontrold would send the command setTempWW 70 which would then set the hot water temperature to 70 degrees Celsius. An OK must appear in the reading last_set_cmd if the command was executed successfully. More complex time specifications for timers can be set analogously. Unfortunately, at the moment vcontrold returns an error message when setting timer values - although the values were transferred correctly.
Get


update
get <name> update
Executes the vcontrold commands specified in the configuration file and writes the results to the readings specified there. If these are not available, they are created.
update_manually
get <name> update_manually
Executes the vcontrold commands specified in the configuration file for all manual entries and writes the results to the readings specified there. If these are not available, they are created.
Attribute


timeout
attr <name> <timeout> 5
Any access to a remote host is not blocking but must still include the possibility of an abort (if no response occurs). Timeout describes after how many seconds the query will be aborted unsuccessfully. In such a case, the entire query list is also terminated. Please note: A too short timeout is problematic, because then the module could not receive any feedback from the heating. The default setting (if no attribute is set) is 5 second.


internal_update_interval
attr <name> <internal_update_interval> 0.1
This is an attribute that should only be used if, despite an intensive search, problems still occur when controlling the system. Normally it is not necessary to set this attribute.
Two different commands cannot be sent to the installation at the same time, because then with an answer it is not clear to which question the result refers. This is implemented internally by VCLIENT by using a small time span between two commands. This time span is now an exact multiple of $internal_update_interval. $internal_update_interval is internally set to 0.1 seconds; this should normally be sufficient. $internal_update_interval must be greater than zero. A larger value leads to a longer duration for all queries, a smaller value may shorten the total duration but could also lead to instabilities.

VCONTROL

[EN DE]

VCONTROL is a fhem-Modul to control and read information from a VIESSMANN heating via Optolink-adapter.

An Optolink-Adapter is necessary (USB or LAN), you will find information here:
http://openv.wikispaces.com/

Additionaly you need to know Memory-Adresses for the div. heating types (e.g. V200KW1, VScotHO1, VPlusHO1 ....),
that will be read by the module to get the measurements or to set the actual state.
Additional information you will find in the forum http://forum.fhem.de/index.php/topic,20280.0.html und auf der wiki Seite http://www.fhemwiki.de/wiki/Vitotronic_200_%28Viessmann_Heizungssteuerung%29


Define
define <name> VCONTROL <serial-device/LAN-Device:port> <configfile> [<intervall>]


• <serial-device/LAN-Device:port>
  USB Port (e.g. com4, /dev/ttyUSB3) or TCPIP:portnumber
  
• <intervall>
  Poll Intervall in seconds (default 180)
  
• <configfile>
  path to the configuration file, containing the memory addresses
  

Example:

serial device com4, every 3 minutes will be polled, configuration file name is 99_VCONTROL.cfg, existing in the fhem root directory

Windows:
define Heizung VCONTROL com4 99_VCONTROL.cfg 180

Linux:
define Heizung VCONTROL /dev/ttyUSB3 99_VCONTROL.cfg 180



Set
These commands will be configured in the configuartion file.


Get
get <name> CONFIG

reload the module specific configfile

More commands will be configured in the configuration file.


configfile
You will find example configuration files for the heating types V200KW1, VScotHO1, VPlusHO1 on the wiki page http://www.fhemwiki.de/wiki/Vitotronic_200_%28Viessmann_Heizungssteuerung%29.

The lines of the configuration file can have the following structure:


• lines beginning with "#" are comments!
  
• Polling Commands (POLL) to read values.
  
• Set Commands (SET) to set values.
  

Polling Commands have the following structure:

POLL, ADDRESSE, PARSEMETHODE, DIVISOR, READING-NAME, KUMULATION


• POLL
  is fix POLL
  


• ADDRESSE
  Memory Address leading to the value, the will be read in the memory on the heating.
  It is subdivided in 3 parts:
  
  • Beginning is fix 01F7 (defines a reading command)
  • followed by actuak address
    
  • followed by number of Bytes to be read.
    


• PARSEMETHODE
  Method how to parse the read bytes.
  methods so far:
  
  • 1ByteU :
    Read value is 1 Byte without algebraic sign (if column Divisor set to state -> only 0 / 1 or off / on)
    
  • 1ByteS :
    Read value is 1 Byte with algebraic sign (wenn Spalte Divisor state ist -> nur 0 / 1 also off / on)
    
  • 2ByteS :
    Read value is 2 Byte with algebraic sign
    
  • 2ByteU :
    Read value is 2 Byte without algebraic sign
    
  • 2BytePercent :
    Read value is 2 Byte in percent
    
  • 4Byte :
    Read value is 4 Byte
    
  • mode :
    Read value is the actual operating status
    
  • timer :
    Read value is an 8 Byte timer value
    
  • date :
    Read value is an 8 Byte timestamp
    
  POLL Commands unsing the method timer will not be polled permanent, they have to be read by a GET Commando explicitly.
  GET <devicename> TIMER
  


• DIVISOR
  If the parsed value is multiplied by a factor, you can configure a divisor.
  Additionally for values, that just deliver 0 or 1, you can configure state in this column.
  This will force the reading to off and on, instead of 0 and 1.
  


• READING-NAME
  The read and parsed value will be stored in a reading with this name in the device.


• KUMULATION
  Accumulated Day values will be automatically stored for polling commands with the value day in the column KUMULATION.
  Futhermore there will be stored the values of the last day in additional readings after 00:00.
  So you have the chance to plot daily values.
  The reading names will be supplemented by DayStart, Today and LastDay!
  

Examples:

POLL, 01F7080402, 2ByteS, 10 , Temp-WarmWater-Actual , -
POLL, 01F7088A02, 2ByteU, 1 , BurnerStarts , day



Set Commands have the following structure:

SET,SETCMD, ADRESSE, CONVMETHODE, NEXT_CMD or DAY for timer


• SET
  is fix SET
  


• SETCMD
  SETCMD are commands that will be used in FHEM to set a value of a device
  set <devicename> <setcmd>
  e.g. SET <devicename> WW to set the actual operational status to Warm Water processing
  


• ADDRESSE
  Memory Address where the value has to be written in the memory of the heating.
  It is subdivided in 4 parts:
  
  • Beginning is fix 01F4 (defines a writing command)
  • followed by actual address
    
  • followed by number of data-bytes to be written
    
  • followed by the data-bytes themselves
    
  
  There are two Address versions:
  
• Version 1: Value to be set is fix, e.g. Spar Mode on is fix 01
  
• Version 2: Value has to be passed, e.g. warm water temperature
  


• CONVMETHODE
  Method how to convert the value with Version 2 in Bytes.
  For Version 1 you can use - here.
  Methods so far:
  
  • 1ByteU :
    Value to be written in 1 Byte without algebraic sign
    with Version 2 it has to be a number
    
  • 1ByteS :
    Value to be written in 1 Byte with algebraic sign
    with Version 2 it has to be a number
    
  • 2ByteS :
    Value to be written in 2 Byte with algebraic sign
    with Version 2 it has to be a number
    
  • 2ByteU :
    Value to be written in 2 Byte without algebraic sign
    with Version 2 it has to be a number
    
  • timer :
    Value to be written is an 8 Byte Timer value
    with Version 2 it has to be a string with this structure:
    8 times of day comma separeted. (ON1,OFF1,ON2,OFF2,ON3,OFF3,ON4,OFF4)
    no time needed ha to be specified with -- .
    Minutes of the times are just allowed to thi values: 00,10,20,30,40 or 50
    Example: 06:10,12:00,16:00,23:00,--,--,--,--
  • date :
    Value to be written is an 8 Byte timestamp
    with Version 2 it has to be a string with this structure:
    format specified is DD.MM.YYYY_HH:MM:SS
    Example: 21.03.2014_21:35:00


• NEXT_CMD or DAY
  This column has three functions:
  • If this columns is configured with a name of another SETCMD, it will be processed directly afterwards.
    Example: after setting Spar Mode on (S-ON), you have to set Party Mode off (P-OFF)
    
  • Using a CONVMETHODE 1ByteU or 1ByteS or 2ByteS or 2ByteU , you can use the column as an multiplicator,
    which will be multiplied to the value in the SET command
    Example: SET, TEMPNHK1 , 01F4200002 , 2ByteU , 10 With SET DEVICE TEMPNHK1 21 210 will be send to the heating.
  • Using timer as CONVMETHODE, so it has to be specified a week day in this columns.
    possible values: MO DI MI DO FR SA SO
    
  
  
  Examples:
  
  SET, WW , 01F423010100, state , -
SET, S-ON , 01F423020101, state_spar , P-OFF
SET, WWTEMP , 01F4630001 , 1ByteU , -
SET, TIMER_2_MO, 01F4200008 , timer , MO


Readings
The values read will be stored in readings, that will be configured as described above.

VIERA

[EN DE]

Define
define <name> VIERA <host> <interval> <pin code> <?>

This module controls Panasonic TV device over ethernet, old TV's and new TV's with crypted communication. It's possible to change volume, switch it off, mute/unmute the TV or send commands like the ones on the remote control.

Defining a VIERA device will schedule an internal task, which periodically reads the status of volume and mute status and triggers notify/filelog commands.

To implement the module several steps may be needed. First define the TV with PinCode <0000>, ? for the encryption and any time interval you like (60 is ok). Switch TV on and wait until the module detects the encyption mode yes/no. If encryption is equal no, you are done. If encryption is yes execute any command like "set myTV1 off". A PinCode should be displayed on the TV. Edit the definition delete the "?" and replace 0000 with the PinCode. Execute the command again while the PinCode is still displayed on TV. You are done.
state: Initialized - on (green) - dormant (orange) - off (red)

This module may require further PERL libraries. For raspbian you have to enter the following commands in the terminal:
sudo cpan
install MIME::Base64
install Crypt::Mode::CBC
install Digest::SHA
q for exit.

Notes:

Activate Remote Control and VIERA-LINK in the TV menue under network and setup

Example:
define myTV1 VIERA 192.168.178.20 ## PinCode ?
define myTV1 VIERA 192.168.178.20 60 0000 ? (with custom interval of 60 seconds and start PinCode)
define myTV1 VIERA 192.168.178.20 60 1234 (changed definition with PinCode transfered from TV)


Set
set <name> <command> [<value>]

Currently, the following commands are defined.
on_off
mute [on|off]
volume [0-100]
channel [1-9999]
input [hdmi1|hdmi2|hdmi3|hdmi4|sdCard|tv]
statusRequest
web

For the web command, please use https:// up front. Example:
set <name> web https://google.de



Remote control commands, depending on your TV
For this application the following commands are available:

set <name> remoteControl .........


3D_button => switch to 3D mode
apps => show apps
aspect => change aspect
AV => switch input to AV
blue_button => blue button
cancel => cancel or clear
channel_down => one channel down
channel_up => one channel up
digit_0 => Digit 0
digit_1 => Digit 1
digit_2 => Digit 2
digit_3 => Digit 3
digit_4 => Digit 4
digit_5 => Digit 5
digit_6 => Digit 6
digit_7 => Digit 7
digit_8 => Digit 8
digit_9 => Digit 9
display_mode
down => cursor down
enter => enter
EPG => program guide
exit => exit
fast_forward => fast foreward
favorite => favorites
game
green_button => green button
guide => guide
HDMI_1 => input HDMI 1
HDMI_2 => input HDMI 2
HDMI_3 => input HDMI 3
HDMI_4 => input HDMI 4
hold => hold
home => home
index => index
info => info
last_view => last view
left => cursor left
menu => menu
mute => mute
noise_reduction => noise reduction
on_off => on off switch
option => option
pause => pause
play => play
program => program
record => record
red_button => red button
return => return
rewind => rewind
right => cursor right
SD_card => SD card
skip_next => skip to next
skip_previous => skip to previous
stop => stop
subtitle => subtitle
tune => tune
TV => TV
up => cursor up
videotext => videotext
VIERA_connect
VIERA_link
VIERA_tools
volume_down => volume down
volume_up => volume up
yellow_button => yellow button



set <name> remoteControlApp ......


netflix
youtube
shoutcast
calendar
browser
amazonprime
iplayer
bbc_iplayer
itv
all_4
demand_5
recorded_tv
multi_window
bbc_news
bbc_sport
weather
developer


Example:

set <name> mute on
set <name> volume 20


Get
get <name> <what>

Currently, the following commands are defined and return the current state of the TV.
mute
volume
presence


Attributes
blocking [0|1]

Generated events:
• volume
• mute
• presence
• state

Vallox

[EN DE]

Vallox is a manufacturer for ventilation devices.
Their products have a built-in RS485-Interface on the central ventilation unit as well as on connected control units on which all control communication is handeled.
More Info on the particular page of FHEM-Wiki (in German).
 
Define
define <name> Vallox <RS485-Device[@baud]> [BusVersion]
If the baudrate is omitted, it is set to 9600 (default Vallox baudrate).
The BusVersion can be set to 1 for older systems. (Default: 2).

Example: define Ventilation Vallox /dev/ttyUSB1

Set
• FanSpeed < 1-8 >
  Allows to set the fan speed (1 = lowest; 8 = highest).
  


• BasicHumidityLevel < 0-100 >
  Allows to set the basic humidity level in percentage.
  


• HeatRecoveryCellBypassSetpointTemperature < 0-20 >
  Allows to set the heat recovery cell bypass setpoint temperature.
  


• raw < HexValue >
  HexValue is two 2-digit hex number to identify the type and value of setting.


Example to set the fan speed to 3:
set Ventilation raw 2907
or:
set Ventilation FanSpeed 3

Get
• reading < readingname >
  Allows to get any predefined reading.
  


• raw < HexValue >
  HexValue is a 2-digit hex number to identify the requested reading.



Attributes
• ValloxIDDomain < HexValue >
  HexValue is a 2-digit hex number to identify the "address" of the bus domain. (01 by default).


• ValloxIDCentral < HexValue >
  HexValue is a 2-digit hex number to identify the "address" of the central ventilation unit. (11 by default).
  In a normal installation ventilation units in the scope 11 to 19 and are addressed with 10 for broadcast-messages.


• ValloxIDFHEM < HexValue >
  HexValue is a 2-digit hex number to identify the "address" of this system as a virtual control terminal. (2F by default)
  In a normal installation control terminals are in the scope 21 to 29 and are addressed with 20 for broadcast-messages.
  The address must be unique.
  The "panel address" of the physical control terminal can be set on the settings of it. Possible values are 1-15 which is the second digit of the Hex-Value (1-F). The first digit is always 2.
  The physical control terminal is usually 21.


• ValloxBufferDebug < 0/1 >
  When 1, modul creates an Internal which fills with the raw Hex-Data from the bus. DEBUG ONLY! (0 by default).


• ValloxForceBroadcast < 0/1 >
  When 1, modul sends commands not only to the central ventilation unit (11) but to all possible addresses by broadcast (10/20). This is sometimes nessecary for older systems. (0 by default; Function always on on BusVersion 1).


• ValloxProcessOwnCommands < 0/1 >
  When 1, modul sends commands not only to the bus but processes it as a received reading. This is sometimes nessecary for older systems. (0 by default; Function always on on BusVersion 1).


• readingFnAttributes

Verkehrsinfo

[EN DE]

Verkehrsinfo can read trafficinformation from various source.


• Verkehrsinfo.de
For receiving the traffic informationen, following website https://www.verkehrsinfo.de/httpsmobil will be called on.
There you can select streets or federal states. Afterwards the URL will be committed as a parameter.


• Hessenschau.de
Here is no configuration necessary, the URL http://hessenschau.de/verkehr/index.html will be used as a parameter.


• RadioSAW.de
Here is no configuration necessary, the keyword radiosaw will be used as a parameter.


Requirement:

For this module, following perl-modules are required:

• HTML::TreeBuilder::XPath
  sudo apt-get install libxml-treebuilder-perl libhtml-treebuilder-xpath-perl


Define
define <name> Verkehrsinfo <url> <interval>

example: define A8 Verkehrsinfo https://www.verkehrsinfo.de/httpsmobil/index.php?c=staulist&street=A8&lat=&lon= 3600

Options:
• url
  URL regarding the traffic information
• interval
  How often the data will be updated in seconds

Set

set <name> <option>

Options:
• update
  update will be executed right away

Get

get <name> <option>

Options:
• info
  output currently traffic information

Attributes

attr <name> <option> <value>

Options:
• filter_exclude
  This is an exclusion filter. Traffic information containing these words, will not be displayed.
  The filter supports regular expressions. Attention: regex control character, for example brackets have to be masked with a backslash "\".
  Multiple searching keywords can be seperated with the pipe "|".
  
  
• filter_include
  This is an inclusion filter. Traffic information containing these words, will be displayed.
  The filter supports regular expressions. Attention: regex control character, for example brackets have to be masked with a backslash "\".
  Multiple searching keywords can be seperated with the pipe "|".
  
  
• Hint: Both filters can be used at the same time, or optional just one.
  The filters are linked with a logical and. That means, for example, when something is excluded, it can be reincluded with the other filter.
  
  
• orderby
  Messages will be sorted by relevance by reference to the string.
  The sort supports regular expressions.
  Multiple searching keywords can be seperated with the pipe "|".
  
  
• msg_format [ road | head | both ] (only Verkehrsinfo.de and RadioSAW.de)
  Using this parameter you can format the output, regarding streets, direction or both.
  
  
• disable
  1 = inactive and 0 = active
  
  
• timeout
  Timeout for web request
  
  
• readingFnAttributes
  
  

Readings


• e_0|1|2|3...|9_... - aktiv message
• count - number of aktiv messages
• e_0_road - street
• e_0_head - direction
• e_0_msg - message

Funktion
Verkehrsinfo_GetData(<devicename>)

The function can be accessed anywhere in FHEM. The output of this function is the same as get info and the string can be used for further forwarding.

example: my $result = Verkehrsinfo_GetData('A8')

VolumeLink

[EN DE]

VolumeLink links the volume-level & mute-state from a physical device (e.g. a Philips-TV) with the volume & mute control of a fhem device (e.g. a SONOS-Playbar, Onkyo, Yamaha or Denon Receiver, etc.).



Define

define <name> VolumeLink <interval> <url> <ampDevice> [<timeout> [<httpErrorLoglevel> [<httpLoglevel>]]]


<interval>:
interval to fetch current volume & mute level from physical-device.

<url>:
url to fetch volume & mute level, see Example below. (Example applies to many Philips TV's)

<ampDevice>:
the target fhem-device.

[<timeout>]:
optional: timeout of a http-get. default: 0.5 seconds

[<httpErrorLoglevel>]:
optional: loglevel of http-errors. default: 4

[<httpLoglevel>]:
optional: loglevel of http-messages. default: 5




Example

define tvVolume_LivingRoom VolumeLink 0.2 http://192.168.1.156:1925/5/audio/volume Sonos_LivingRoom
set tvVolume_LivingRoom on

Note:
- This example will work out of the box with many Philips TV's and a SONOS-Playbar as fhem-device.
- Pre 2014 Philips TV's use another protocoll, which can be accessed on http://<ip>/1/audio/volume



Set

set <name> <on|off>

Set on or off, to start or to stop.



Get

N/A



Attributes

Note:
- All Attributes takes effect immediately.
- The default value of volumeRegexPattern & muteRegexPattern applies to many Philips-TV's, otherwise it must be configured.
- The default values of amp* applies to a SONOS-Playbar, otherwise it must be configured.
- If you don't receive a result from url, or the lastHttpErrorMessage shows every time 'timed out', try setting attribute 'httpNoShutdown' to 0.


• disable <1|0>
  With this attribute you can disable the whole module.
  If set to 1 the module will be stopped and no volume will be fetched from physical-device or transfer to the amplifier-device.
  If set to 0 you can start the module again with: set <name> on.
• httpNoShutdown <1|0>
  If set to 0 VolumeLink will tell the http-server to explicit close the connection.
  Default: 1
• ampInputReading <value>
  Name of the Input-Reading on amplifier-device
  To disable the InputCheck if your amplifier-device does not support this, set this attribute to 0.
  Default (which applies to SONOS-Player's): currentTitle
• ampInputReadingVal <RegEx>
  RegEx for the Reading value of the corresponding Input-Channel on amplifier-device
  Default (which applies to a SONOS-Playbar's SPDIF-Input and if no Input is selected): SPDIF-Wiedergabe|^$
• ampVolumeReading <value>
  Name of the Volume-Reading on amplifier-device
  Default: Volume
• ampVolumeCommand <value>
  Command to set the volume on amplifier device
  Default: Volume
• ampMuteReading <value>
  Name of the Mute-Reading on amplifier-device
  Default: Mute
• ampMuteReadingOnVal <value>
  Reading value if muted
  Default: 1
• ampMuteReadingOffVal <value>
  Reading value if not muted
  Default: 0
• ampMuteCommand <value>
  Command to mute the amplifier device
  Default: Mute
• volumeRegexPattern <RegEx>
  RegEx which is applied to url return data. Must return a number for volume-level.
  Default (which applies to many Phlips-TV's): current":\s*(\d+)
• muteRegexPattern <RegEx>
  RegEx which is applied to url return data. Must return true, false, 1 or 0 as mute-state.
  Default (which applies to many Phlips-TV's): muted":\s*(\w+|\d+)



Readings

Note: All VolumeLink Readings except of 'state' does not generate events!


• lastHttpError
  The last HTTP-Error will be recorded in this reading.
  Define httpErrorLoglevel, httpLoglevel or attribute verbose for more information.
  Note: Attr verbose will not output all HTTP-Messages, define httpLoglevel for this.
• mute
  The current mute-state fetched from physical device.
• volume
  The current volume-level fetched from physical device.
• state
  on if VolumeLink is running, off if VolumeLink is stopped.

WINCONNECT

[EN DE]

This module controls a Windows PC.


Define
define <name> WINCONNECT <ip-address-or-hostname> [<poll-interval>]

Defining an WINCONNECT device will schedule an internal task (interval can be set with optional parameter <poll-interval> in seconds, if not set, the value is 45 seconds), which periodically reads the status of the device and triggers notify/filelog commands.

Example:

define Buero.PC WINCONNECT 192.168.0.10

# With custom interval of 60 seconds
define Buero.PC WINCONNECT 192.168.0.10 60



More information on FHEM Wiki.

WMBUS - Wireless M-Bus

[EN DE]

This module supports Wireless M-Bus meters for e.g. water, heat, gas or electricity. Wireless M-Bus is a standard protocol supported by various manufacturers. It uses the 868 MHz band for radio transmissions. Therefore you need a device which can receive Wireless M-Bus messages, e.g. a CUL with culfw >= 1.59 or an AMBER Wireless AMB8465M.
WMBus uses three different radio protocols, T-Mode, S-Mode and C-Mode. The receiver must be configured to use the same protocol as the sender. In case of a CUL this can be done by setting rfmode to WMBus_T, WMBus_S or WMBus_C respectively.
WMBus devices send data periodically depending on their configuration. It can take days between individual messages or they might be sent every minute.
WMBus messages can be optionally encrypted. In that case the matching AESkey must be specified with attr AESkey. Otherwise the decryption will fail and no relevant data will be available. The module can decrypt messages encrypted according to security profile A or B (mode 5 and 7).

Prerequisites
This module requires the perl modules Digest::CRC, Crypt::Mode::CBC, Crypt::Mode::CTR and Digest::CMAC (last three only if encrypted messages should be processed).
On a debian based system these can be installed with
sudo apt-get install libdigest-crc-perl
sudo cpan -i Crypt::Mode::CBC Crypt::Mode:CTR Digest::CMAC

Define
define <name> WMBUS [<manufacturer id> <identification number> <version> <type> [<MessageEncoding>]]|<b[<MessageEncoding>]HexCode>

Normally a WMBus device isn't defined manually but automatically through the autocreate mechanism upon the first reception of a message.
For a manual definition there are two ways.
• By specifying a raw WMBus message as received by an IODev. Such a message starts with a lower case 'b' and contains at least 24 hexadecimal digits. The WMBUS module extracts all relevant information from such a message.
• Explictly specify the information that uniquely identifies a WMBus device.
  The manufacturer code, which is is a three letter shortcut of the manufacturer name. See dlms.com for a list of registered ids.
  The identification number is the serial no of the meter.
  version is the version code of the meter
  type is the type of the meter, e.g. water or electricity encoded as a number.
  MessageEncoding is either CUL or AMB, depending on which kind of IODev is used. The default encoding is CUL.



Set
• rawmsg hexadecimal contents of a raw message (without the leading b)
  Will be parsed as if the message has been received by the IODev. Mainly useful for debugging.

Get
N/A

Attributes
• IODev
  Set the IO or physical device which should be used for receiving signals for this "logical" device. An example for the physical device is a CUL.


• AESkey
  A 16 byte AES-Key in hexadecimal digits. Used to decrypt messages from meters which have encryption enabled.


• ignore


• rawmsg_as_reading
  If set to 1, received raw messages will be stored in the reading rawmsg. This can be used to log raw messages to help with debugging.


• ignoreUnknownDataBlocks
  If set to 1, datablocks containing unknown/manufacturer specific data will be ignored. This is useful if a meter sends data in different formats of which some can be interpreted and some not. This prevents the unknown data overwriting the readings of the data that can be interpreted.


• ignoreMasterMessages
  Some devices (e.g. Letrika solar inverters) only send data if they have received a special message from a master device. The messages sent by the master are ignored unless explictly enabled by this attribute.


• useVIFasReadingName
  Some devices send several types of messages with different logical content. As the readings are normally numbered consecutively they will be overwitten by blocks with a different semantic meaning. If ths attribute is set to 1 the naming of the readings will be changed to start with storage number and VIF (Value Information Field) name. Therefor each semantically different value will get a unique reading name.
  Example:
  

       1_storage_no 0
       1_type VIF_ENERGY_WATT
       1_unit Wh
       1_value 1234.5
       

  will be changed to
  

       0_VIF_ENERGY_WATT_unit Wh
       0_VIF_ENERGY_WATT_value 1234.5
       


Readings

Meters can send a lot of different information depending on their type. An electricity meter will send other data than a water meter. The information also depends on the manufacturer of the meter. See the WMBus specification on oms-group.org for details.

The readings are generated in blocks starting with block 1. A meter can send several data blocks. Each block has at least a type, a value and a unit, e.g. for an electricity meter it might look like

1_type VIF_ENERGY_WATT
1_unit Wh
1_value 2948787


There is also a fixed set of readings.
• is_encrypted is 1 if the received message is encrypted.
• decryption_ok is 1 if a message has either been successfully decrypted or if it is unencrypted.
• state contains the state of the meter and may contain error message like battery low. Normally it contains 'no error'.
• batteryState contains ok or low.
For some well known devices specific readings like the energy consumption in kWh created.

WOL

[EN DE]

Defines a WOL device via its MAC and IP address.

when sending the on command to a WOL device it wakes up the dependent device by sending a magic packet. When running in repeat mode the magic packet ist sent every n seconds to the device. So, for example a Buffalo NAS can be kept awake.

Define

define <name> WOL <MAC> <IP> [<mode> [<repeat>]]



MAC

MAC-Adress of the host

IP

IP-Adress of the host (or broadcast address of the local network if IP of the host is unknown)

mode [EW|UDP]

EW: wakeup by usr/bin/ether-wake

UDP: wakeup by an implementation like Net::Wake(CPAN)

CMD: wakeup via own command (FHEM command, Perl Code or system Command - see Attribut wolCmd



Examples:
define computer1 WOL 72:11:AC:4D:37:13 192.168.0.24             switching only one time
define computer1 WOL 72:11:AC:4D:37:13 192.168.0.24 EW          by ether-wake(linux command)
define computer1 WOL 72:11:AC:4D:37:13 192.168.0.24 BOTH        by both methods
define computer1 WOL 72:11:AC:4D:37:13 192.168.0.24 UDP 200     in repeat mode
define computer1 WOL 72:11:AC:4D:37:13 192.168.0.24 CMD



Notes:
Not every hardware is able to wake up other devices by default. Often firewalls filter magic packets and have to be configured accordingly. You may need a packet sniffer to check some malfunction.

Set

set <name> <value>

where value is one of:


    refresh           # checks(by ping) whether the device is currently running
    on                # sends a magic packet to the defined MAC address
    off               # stops sending magic packets and sends the shutdownCmd(see attributes)
    

Examples:
set computer1 on
set computer1 off
set computer1 refresh


Attributes

• attr <name> sysCmd <string>
  Custom command executed to wakeup a remote machine, i.e. /usr/bin/ether-wake or /usr/bin/wakeonlan
• attr <name> wolCmd <command>
  Custom command executed to wakeup a remote machine. Can be <command>, as in at, notify oder Watchdog. If the attribute sshHost is set, the command will be executed as a shell command in remote system. Replacements $MAC, $IP and $BC could be used for MAC, IP and UdpBroadcast.
• attr <name> shutdownCmd <command>
  Custom command executed to shutdown a remote machine. You can use <command>, like you use it in at, notify or Watchdog If the attribute sshHostShutdown is set, the command will be executed as a shell command in remote system


Examples:

    attr wol shutdownCmd    set lamp on                            # fhem command
    attr wol shutdownCmd    { Log 1, "Teatime" }                   # Perl command
    attr wol shutdownCmd    "/bin/echo "Teatime" > /dev/console"   # shell command
    

• attr <name> sshHost <IP Address>
  Expects a value like [pi@]ip-adresse[:port]. If the attribute is set, the wolCmd will be executed via ssh on the remote host. Prerequisite is that the fhem-User is allowed to login to the remote host without password prompt. (see e.g. https://www.schlittermann.de/doc/ssh.html).
• attr <name> sshHostShutdown <IP Address>
  Expects a value like [pi@]ip-adresse[:port]. If the attribute is set, the shutdownCmd will be executed via ssh on the remote host. Prerequisite is that the fhem-User is allowed to login to the remote host without password prompt. (see e.g. https://www.schlittermann.de/doc/ssh.html).
• attr <name> interval <seconds>
  defines the time between two checks by a ping if state of <name> is on. By using 0 as parameter for interval you can switch off checking the device.
• attr <name> useUdpBroadcast <broadcastAdress>
  When using UDP then the magic packet can be send to one of the broadcastAdresses (x.x.x.255, x.x.255.255, x.255.255.255) instead of the target host address. Try using this, when you want to wake up a machine in your own subnet and the wakekup with the target adress is instable or doesn't work.

WS2000

[EN DE]

Define
define <name> WS2000 <device_to_connect>

Define a WS2000 series raw receiver device sold by ELV. Details see here. Unlike 86_FS10.pm it will handle the complete device communication itself and doesnt require an external program. For this reason you can now use this also on windows.
This Device will be usually connect to a serial port, but you can also define a raw network redirector like lantronix XPORT(TM).
Note: Currently this device does not support a "set" function

Attributes:
• rain: factor for calculating amount of rain in ml/count
• altitude: height in meters to calculate pressure for NN (not used yet)

Example:
define WS2000 WS2000 /dev/ttyS0

define WS2000 WS2000 xport:10001

attr WS2000 rain 366 : use factor 366 ml/count for rain sensor S2000R



Set
N/A

Get
get <name> list
Gets the last reading of all received sensord

get <name> [TH0..TH7, T0..T7, I0..I7, R0..R7, W0..W7, L0..L7, P0..P7,LAST,RAW]
get the last reading for the name sensor,
LAST: Last received Sensor

RAW: original Data from interface


Attributes
• model (ws2000)
• loglevel
• rain
• altitude

WS300

[EN DE]

Define
define WS300Device WS300 <serial device>
or
define <devname> WS300 [0-9]

The first line is mandatory if you have a WS300 device: it defines the input device with its USB port. The name of this device is fixed and must be WS300Device. It must be the first defined WS300 device.
For each additional device (with number 0 to 9) you have to define another WS300 device, with an arbitrary name. The WS300 device which reports the readings will be defined with the port number 9, an optional KS300 with the port number 8.

Examples:

      define WS300Device  WS300   /dev/ttyUSB1
      define ash2200.1    WS300   0
      define ks300        WS300   8
      define ws300        WS300   9
    


Set
set WS300Device <interval(min.)> <height(m)> <rainvalume(ml)>

Set some WS300 configuration parameters.
Get
N/A

Attributes
• do_not_notify
• model (ws300)
• readingFnAttributes

WS3600

[EN DE]

Defines a weather station, which is queried by means of an external program. That program is executed by FHEM and is expected to deliver the data at stdout in the format of a WS3600 series weather station (details see below).

Define
define <name> WS3600 "<wsreaderprog> [<options>]" [<interval>]



<wsreaderprog>

full path to the executable which queries the weatherstation (for WS3600 series fetch3600 should be used)

<options>

options for <wsreaderprog>, if necessary

<interval>

this optional parameter is the time between subsequent calls to <wsreaderprog>. It defaults to 60s.


Supported Stations are:

• WS3600 series weather station (Europe Supplies, technotrade, etc; refer to Wetterstationen.info (german) for details on this model) with fetch3600 from the toolchain open3600). Fetch3600 delivers the current readings line by line as reading-value-pairs. These are read periodically and translated into more readable names for FHEM by the module WS3600.pm.
• WS2300 with toolchain open2300, because it is rather similar to the WS3600.
• WS1080 (and other stations which come with the EasyWeather windows application) with fowsr (version 2.0 or above)

Currently, it is expected that the WS is attached to the local computer and <wsreaderprog> is run locally. Basically the executable called needs to supply on stdout an output similar to what fetch3600 returns; how to implement a "networked setup" is left as an excercise to the reader.
For the records, this is an output of fetch3600:


Date 14-Nov-2009
Time 10:50:22
Ti 22.8
Timin 20.8
Timax 27.9
TTimin 10:27
DTimin 15-10-2009
TTimax 23:31
DTimax 20-08-2009
To 14.2
Tomin -0.4
Tomax 35.6
TTomin 07:03
DTomin 15-10-2009
TTomax 16:52
DTomax 20-08-2009
DP 9.2
DPmin -2.2
DPmax 20.3
TDPmin 07:03
DDPmin 15-10-2009
TDPmax 11:58
DDPmax 20-08-2009
RHi 48
RHimin 32
RHimax 57
TRHimin 17:03
DRHimin 21-10-2009
TRHimax 22:24
DRHimax 07-10-2009
RHo 72
RHomin 27
RHomax 96
TRHomin 16:41
DRHomin 20-08-2009
TRHomax 06:28
DRHomax 02-11-2009
WS 0.0
DIRtext WSW
DIR0 247.5
DIR1 247.5
DIR2 247.5
DIR3 247.5
DIR4 247.5
DIR5 247.5
WC 14.2
WCmin -0.4
WCmax 35.6
TWCmin 07:03
DWCmin 15-10-2009
TWCmax 16:52
DWCmax 20-08-2009
WSmin 0.0
WSmax 25.6
TWSmin 10:44
DWSmin 14-11-2009
TWSmax 19:08
DWSmax 24-09-2009
R1h 0.00
R1hmax 24.34
TR1hmax 22:34
DR1hmax 07-10-2009
R24h 0.00
R24hmax 55.42
TR24hmax 07:11
DR24hmax 08-10-2009
R1w 29.00
R1wmax 95.83
TR1wmax 00:00
DR1wmax 12-10-2009
R1m 117.58
R1mmax 117.58
TR1mmax 00:00
DR1mmax 01-11-2009
Rtot 3028.70
TRtot 03:29
DRtot 18-09-2005
RP 992.200
AP 995.900
RPmin 970.300
RPmax 1020.000
TRPmin 05:25
DRPmin 04-11-2009
TRPmax 09:19
DRPmax 11-09-2009
Tendency Falling
Forecast Cloudy

The following extensions are also supported now:


IL 0.0
UV 8
Forecast Rain at times, worse later
ZCode U

There is no expectation on the readings received from the fetch3600 binary; so, in essence, if you have a similar setup (unsupported, attached weather station and a means to get it's reading into an output similar to above's), you should be able to use WS3600.pm with a custom written script to interface FHEM with your station as well. WS3600.pm only recognizes the above readings (and translates these into, e. g., Temp-inside for Ti for use within FHEM), other lines are silently dropped on the floor. Note: To step down the number of readings date and time records will now be merged to one reading containing date and time. This now also allows records with merged date / time values delivered from <wsreaderprog> - detected by prefix DT (e.g. Date + Time --> DTime, DRPmin + TRPmin --> DTRPmin and so on).
fetch3600 is available as binary for the Windows OS as well, but operation under that OS isn't tested yet.

Examples:
define myWS3600 W3600 /usr/local/bin/fetch360
define myWS1080 W3600 "/usr/local/bin/fowsr -c" 300



Set
N/A

Get
N/A

Attributes
• model     WS3600, WS2300, WS1080, WS3080 (not used for anything, yet)

WS980

[EN DE]

WS980 - Requests weather data locally from WS980WiFi weather stations

Define

define <name> WS980 [IP] [INTERVAL]

[IP] Optional: The IP of the WS980WiFi. If no IP is given, the station is auto-discovered.
[INTERVAL] Optional: The interval in seconds to request updates, default: 30 seconds.

Example:

define ws980wifi WS980 192.168.2.177 60

This statement creates an WS980 instance with the name ws980wifi with the IP 192.168.2.177.
With an interval of 60 seconds the weather information are requested.

Readings
• temperatureInside [°C]
  The IN-temperature at the display.
• temperature [°C]
  The temperature measured by the outdoor probe.
• dewPoint [°C]
  The dew-point calculated by the weather station.
• windChill [°C]
  The wind-chill calculated by the weather station.
• heatIndex [°C]
  The heat-index calculated by the weather station.
• humidityInside [%]
  The IN-humidity at the display.
• humidity [%]
  The humidity measured by the outdoor probe.
• pressureAbs [hPa]
  The absolute pressure measured by the outdoor probe.
• pressureRel [hPa]
  The relative pressure measured by the outdoor probe. This only differs from pressureAbs if you have an offset configured in your weather station.
• pressureRel_calculated [hPa]
  The relative pressure calculated using the QFF forumula based on temperature, pressureAbs, altitude and humidity.
• windDirection [°]
  The wind-direction measured by the outdoor probe.
• wind [m/s]
  The wind-seed measured by the outdoor probe.
• windGusts [m/s]
  The speed of wind-gusts measured by the outdoor probe.
• rainRate [mm]
  The current rain-rate measured by the outdoor probe.
• rainPerDay [mm]
  The rain-rate per day measured by the outdoor probe.
• rainPerWeek [mm]
  The rain-rate per week measured by the outdoor probe.
• rainPerMonth [mm]
  The rain-rate per month measured by the outdoor probe.
• rainPerYear [mm]
  The rain-rate per year measured by the outdoor probe.
• rainTotal [mm]
  The total rain-rate measured by the outdoor probe.
• rain24h [mm]
  The amount of rain in the last 24h. This value is calculated from rainTotal and is updated once per hour. In the first 24h, the amunt is displayed in "()" and shows the count of hours recorded already.
• brightness [lux]
  The brightness measured by the outdoor probe.
• uv [uW/m²]
  The raw UV-values measured by the outdoor probe.
• uvIndex [0-15]
  The UV-Index calculated by the weather station.

Set
• update
  manually update current weather data

Attributes
• attr <name> altitude <height>
  Specifies the mean sea level in meters. Default is 0. Used to calculate the pressureRel_calculated-reading. If unset, the altitude from global is used.
• attr <name> connection <Keep-Alive|Close>
  Keep-Alive: The connection to the WS980 is kept open as long as possible. Reconnect is only done if necessary. Keep-Alive is default and a good setting in most cases.
  Close: The connection is opened on-the-fly and closed directly after doing requests. Close should only be used if you have multiple clients connection to your WS980 which might cause frequent read-timeouts. ConnectionState will display disconnected most of the time, this is OK!
• attr <name> invalidValues <updateReading|skip|skipAndLog>
  updateReading: The reading will be set to n/a when an invalid value is received. updateReading is default.
  skip: Invalid values will silently be skipped, the corresponding reading will not be updated.
  skipAndLog: Invalid values will be logged, and the corresponding reading will not be updated.
  
• attr <name> events <Configuration>|<Configuration>|...
  Allows to configure custom events based on the readings of this instance.
  <Configuration> must have the form: NAME:READING<LIMIT,HYSTERESIS or NAME:READING>LIMIT,HYSTERESIS.
  • NAME: The name used for the reading and the event. To reduce the possibility of collisions with existing readings, the Name of the reading will always be prefixed with 'is'.
  • READING:The name of the reading which will be compared to LIMIT to set the resulting event to 0 or 1.
  • < or >: For '<' the reading-value must be less than the LIMIT to result in 1, for '>' the reading-value must be above LIMIT to result in 1.
  • LIMIT: The value which will be compared to the READINGs current value.
  • HYSTERESIS: The hysteresis-value is used to reduce fast flipping of 0 and 1.
  Configurations can be separated by either "|" or newline. All whitespace will be removed when parsing events.
  Examples:
  
  attr <name> events dusk:brightness<30,20
  A new reading isDusk will be autogenerated with possible values 0 or 1. As soon as the brightness drops below 30lux, isDusk will switch to 1. The hystereses value of 20 means, that isDusk will switch back to 0 only after either the brightness has reached 50lux (30+20) or the brightness dropped below 10lux (30-20) and then rises above 30lux again.
  attr <name> brightSunlight:brightness>80000,5000
  A new reading isBrightSunlight will be autogenerated with possible values 0 or 1. As soon as the brightness rises above 80000lux, isBrightSunlight will switch to 1. The hystereses value of 5000 means, that isBrightSunlight will switch back to 0 only after either the brightness has dropped below 75000lux or the brightness was above 85000lux and then drops below 80000lux again.
  You can concatenate as many Configurations with '|' as you like. For example:
  attr <name> dusk:brightness<30,20|brightSunlight:brightness>80000,5000
  
  
• attr <name> requests current todayMax ...
  A comma or space separated list of values to requests. If empty, all known values are requested.
  Valid values: firmware, current, todayMax, todayMin, historyMax, historyMin.
• attr <name> showRawBuffer 1
  used for development: show raw data received from the WS980WiFi
• attr <name> silentReconnect 1
  If set to 1, then it will set the loglevel for connect- and reconnect-messages to 2 instead of 1
• attr <name> unit_temperature <unit>
  set the unit used for temperature-readings. Default: °C
• attr <name> unit_pressure <unit>
  set the unit used for pressure-readings. Default: hPa
• attr <name> unit_wind <unit>
  set the unit used for wind-readings. Default: m/s
• attr <name> unit_rain <unit>
  set the unit used for rain-readings. Default: mm
• attr <name> unit_light <unit>
  set the unit used for brightness-readings. Default: lux
• attr <name> disable 1
  disables this WS980-instance

WUup

[EN DE]

Define

define <name> WUup <stationId> <password>

This module provides connection to www.wunderground.com
to send data from your own weather station.



Set-Commands

• update - send data to Weather Underground


Get-Commands


- not implemented -



Attributes


• readingFnAttributes
• interval - Interval (seconds) to send data to www.wunderground.com. Will be adjusted to 300 (which is the default) if set to a value lower than 3.
  If lower than 300, RapidFire mode will be used.
• disable - disables the module
• disabledForIntervals
• unit_windspeed - change the units of your windspeed readings (m/s or km/h)
• unit_solarradiation - change the units of your solarradiation readings (lux or W/m²)
• round - round values to this number of decimals for calculation (default 4)
• wu.... - Attribute name corresponding to parameter name from api. Each of these attributes contains information about weather data to be sent in format sensorName:readingName
  Example: attr WUup wutempf outside:temperature will define the attribute wutempf and
  reading "temperature" from device "outside" will be sent to network as parameter "tempf" (which indicates current temperature)
  Units get converted to angloamerican system automatically (°C -> °F; km/h(m/s) -> mph; mm -> in; hPa -> inHg)
  
  The following information is supported:
  • winddir - instantaneous wind direction (0-360) [°]
  • windspeedmph - instantaneous wind speed ·[mph]
  • windgustmph - current wind gust, using software specific time period [mph]
  • windgustdir - current wind direction, using software specific time period [°]
  • windspdmph_avg2m - 2 minute average wind speed [mph]
  • winddir_avg2m - 2 minute average wind direction [°]
  • windgustmph_10m - past 10 minutes wind gust [mph]
  • windgustdir_10m - past 10 minutes wind gust direction [°]
  • humidity - outdoor humidity (0-100) [%]
  • dewptf- outdoor dewpoint [°F]
  • tempf - outdoor temperature [°F]
  • rainin - rain over the past hour -- the accumulated rainfall in the past 60 min [in]
  • dailyrainin - rain so far today in local time [in]
  • baromin - barometric pressure [inHg]
  • soiltempf - soil temperature [°F]
  • soilmoisture - soil moisture [%]
  • solarradiation - solar radiation[W/m²]
  • UV - [index]
  • AqPM2.5 - PM2.5 mass [µg/m³]
  • AqPM10 - PM10 mass [µg/m³]


Readings/Events:


• data - data string transmitted to www.wunderground.com
• response - response string received from server


Notes


• Find complete api description here
• Have fun!

WWO

[EN DE]

Define
define <name> WWO <location> <apikey>

Defines a virtual device for WWO forecasts.

A WWO device periodically gathers current and forecast weather conditions from worldweatheronline.com (the free api version)
You need to signup at http://developer.worldweatheronline.com to get an apikey)

The parameter location is the WOEID (WHERE-ON-EARTH-ID), go to http://www.worldweatheronline.com to find it out for your valid location.

The natural language in which the forecast information appears is english.

The interval is set to update the values every hour.

Examples:

      define MyWeather WWO Berlin,Germany
     

The module provides one additional function WWOAsHtml. The function return the HTML code for a vertically arranged weather forecast.

Example:

      define MyWeatherWeblink weblink htmlCode { WWOAsHtml("MyWeather") }
    


Set
set <name> update

Forces the retrieval of the weather data. The next automatic retrieval is scheduled to occur interval seconds later.



Get
get <name> <reading>

Valid readings and their meaning (? can be one of 0, 1, 2, 3, 4, 5 and stands for today, tomorrow, etc. - with 'fc?_' or without! - without is meaning 'current condition'):


cloudcover	cloudcover in percent
current_date_time	last update of forecast on server
fc?_date	date of the forecast condition - not valid without 'fc?'
fc?_icon	name of the forecasticon
fc?_precipMM	preciption for day
fc?_tempMaxC	forecasted daily high in degrees centigrade
fc?_tempMaxF	forecasted daily high in degrees fahrenheit
fc?_tempMinC	forecasted daily low in degrees centigrade
fc?_tempMinF	forecasted daily low in degrees fahrenheit
fc?_weatherCode	weathercode
fc?_weatherDesc	short weather desciption
fc?_weatherIconUrl	full url to the weathericonfile
fc?_winddir16Point	winddirection with 16 points
fc?_winddirDegree	windirection in degrees
fc?_winddirection	winddirection
fc?_windspeedKmph	windspeed in km/h
fc?_windspeedMiles	windspeed in miles/h
humidity	current humidity in %
localObsDateTime	local time of observation
observation_time	time of observation
pressure	air pressure in hPa
query	returns the queried location
temperature	current temperature in degrees centigrade
visibility	current visibilit in km


Attributes
• readingFnAttributes

Watches

[EN DE]

The module Watches provides watches in different styles as Device. The module is a JavaScript application that runs on a client (browser) and not on the FHEM server. Attributes and readings are read asynchronously from the server and possibly also written, but only if the application is currently running in the browser.
The user can influence the design of the watches via attributes.
The clocks are based on scripts of these pages:
modern watch, Station clock, Digital display

A device of the model Digital can also be used as stopwatch, countdown timer or universal text display (for sixteen segment mode see attribute digitalSegmentType).
As time source the client (browser time) as well as the FHEM server can be set (attribute timeSource).

Define
define <name> Watches [Modern | Station | Digital]



Modern	: creates an analog clock with a modern design
Station	: creates a station clock
Digital	: creates a digital display (clock, (CountDown)stop watch, static time display or text)




Set
• alarmSet <hh> <mm> <ss>
  Sets the alarm time in the format hh hours, mm minutes and ss seconds.
  If the time reaches the defined value, an event of the reading "alarmed" is triggered.
  This set command is only available for digital stopwatches.
  
  
  Example
  set <name> alarmSet 0 30 10
  
  


• alarmDel
  Clears the set alarm time and its status.
  This set command is only available for digital stopwatches.
  


• countDownInit <hh> <mm> <ss> | <seconds>
  Sets the start time of a countdown stopwatch. The format can be <hh> hours, <mm> minutes and <ss> seconds or alternatively only one entry in seconds.
  This set command is only available with a digital countdown stopwatch.
  
  
  Examples
  set <name> countDownInit 0 30 10
  set <name> countDownInit 3600
  
  


• displayTextSet
  Sets the text to be displayed.
  This set command is only available for a digital segment display with "digitalDisplayPattern = text".
  (default: blank display)
  
  Note:
  The displayable characters depend on the attribute "digitalSegmentType".
  With the (default) seven-segment display, only numbers, hyphen, underscore and the letters A, b, C, d, E, F, H, L, n, o, P, r, t, U and Y are displayed. In addition to numbers, short texts such as "Error", "HELP", "run" or "PLAY" can also be displayed.
  For text display it is recommended to set the sixteen segment display with the attribute "digitalSegmentType" !


• displayTextDel
  Deletes the display text.
  This set command is only available for a digital segment display with "digitalDisplayPattern = text".
  


• reset
  Stops the stopwatch (if running) and clears all specific readings or resets it to initialized.
  This set command is only available for digital stopwatches.
  


• resume
  Resumes counting a stopped stopwatch.
  This set command is only available for digital stopwatches.
  


• start
  Starts the stopwatch.
  This set command is only available for digital stopwatches.
  


• stop
  Stop the stopwatch. The achieved time is retained.
  This set command is only available for digital stopwatches.
  


• textTicker on | off
  Switches the ticker mode of a text display (see attribute digitalDisplayPattern) on or off.
  (default: off)


• time <hh> <mm> <ss>
  Sets a static time display with hh hours, mm minutes and ss seconds.
  This set command is only available for a digital clock with static time display.
  
  
  Example
  set <name> time 8 15 3



Get
N/A

Attributes


• controlButtonSize
  Changes the size of the control buttons if the clock type has control buttons.


• disable
  Activates/deactivates the Device.


• hideButtons
  Hides the control buttons if the watch type has control buttons.


• hideDisplayName
  Hides the Device/Alias name (link to detail view).


• htmlattr
  Additional HTML tags to resize the clock / display.
  
  
  Example:
  attr <name> htmlattr width="125" height="125"
  


• timeAsReading
  If set, a displayed time is written to the reading currtime.


• timeSource
  Selects the time source. The local client time (browser) or the FHEM server time can be displayed.
  This setting is not relevant for (countdown) stopwatches.
  [default: client]


The following attributes must be set specifically for a clock type.

Model: Modern


• modernColorBackground
  Background color of the clock.


• modernColorFace
  Colouring of the dial.


• modernColorFigure
  Colour of the numbers on the dial and the pointer axle cover.


• modernColorHand
  Colour of the watch hands.


• modernColorRing
  Colour of the dial frame.


• modernColorRingEdge
  Colour of the outer ring of the dial frame.



Model: Station


• stationBody
  Type of watch case.


• stationBoss
  Type and colour of the pointer axle cover.


• stationHourHand
  Type of hour hand.


• stationMinuteHand
  Type of minute hand.


• stationMinuteHandBehavoir
  Behavior of the minute hand.


• stationSecondHand
  Type of second hand.


• stationSecondHandBehavoir
  Behavior of the second hand.


• stationStrokeDial
  Selection of the dial.



Model: Digital


• digitalBorderDistance
  Left and right distance of the digital text display from the background edge.
  (default: 8)


• digitalColorBackground
  Digital clock background color.


• digitalColorDigits
  Color of the bar display in a digital watch.


• digitalDigitAngle
  Adjusts the tilt angle of the displayed characters.
  (default: 9)


• digitalDigitDistance
  Adjusts the character spacing.
  (default: 2)


• digitalDigitHeight
  Adjusts the character height.
  (default: 20)


• digitalDigitWidth
  Adjusts the character width.
  (default: 12)


• digitalDisplayPattern [countdownwatch | staticwatch | stopwatch | text | watch]
  Switching the digital display between a clock (default), a stopwatch, static time display or text display. The text to be displayed in text display mode can be defined with
  set <name> displayText.
  
  Note: For text display it is recommended to set the attribute "digitalSegmentType" to "16".
  
  

  countdownwatch	: CountDown Stopwatch
  staticwatch	: static time display
  stopwatch	: Stopwatch
  text	: Display of a definable text
  watch	: Watch

  
  
  
• digitalSegmentDistance
  Defines the distance between the segments.
  (default: 0.5)


• digitalSegmentType
  Switches the segment number of the digital display.
  (default: 7)


• digitalSegmentWidth
  Changes the width of the individual segments.
  (default: 1.5)


• digitalTextDigitNumber <Quantity>
  If <Quantity> > 0, the number of digits of a text display (digitalDisplayPattern = text) is fixed. If <Quantity> = 0 or not set, the setting is made automatically. In this case an adaptation is made of the character size to the number depending on the set display size (see htmlattr).
  (default: 0)

WaterCalculator

[EN DE]

The WaterCalculator Module calculates the water consumption and costs of one or more water meters. It is not a counter module itself but it requires a regular expression (regex or regexp) in order to know where to retrieve the continously increasing counter value of one or more mechanical or electronic water meter. The function of the sub-counter for garden water has not been implemented yet. Therefore the sewage water cost needs to be taken into account. As soon the module has been defined within the fhem.cfg, the module reacts on every event of the specified counter like myOWDEVICE:counter.* etc. The WaterCalculator module provides several current, historical, statistical values around with respect to one or more water meter and creates respective readings. To avoid waiting for max. 12 months to have realistic values, the readings <DestinationDevice>_<SourceCounterReading>_CounterDay1st, <DestinationDevice>_<SourceCounterReading>_CounterMonth1st, <DestinationDevice>_<SourceCounterReading>_CounterYear1st and <DestinationDevice>_<SourceCounterReading>_CounterMeter1st must be corrected with real values by using the setreading - command. These real values may be found on the last water bill. Otherwise it will take 24h for the daily, 30days for the monthly and up to 12 month for the yearly values to become realistic. Intervalls smaller than 10s will be discarded to avoid peaks due to fhem blockages (e.g. DbLog - reducelog).




Define

define <name> WaterCalculator <regex>

<name> : The name of the calculation device. (E.g.: "myWaterCalculator")

<regex> : A valid regular expression (also known as regex or regexp) of the event where the counter can be found

Example:define myWaterCalculator WaterCalculator myWaterCounter:countersA.*




Set

The set - function sets individual values for example to correct values after power loss etc. The set - function works for readings which have been stored in the CalculatorDevice and to update the Offset. The Readings being stored in the Counter - Device need to be changed individially with the set - command. The command "SyncCounter" will calculate and update the Offset. Just enter the value of your mechanical Reader.




Get

The get - function just returns the individual value of the reading. The get - function works only for readings which have been stored in the CalculatorDevice. The Readings being stored in the Counter - Device need to be read individially with get - command.




Attributes

If the below mentioned attributes have not been pre-defined completly beforehand, the program will create the WaterCalculator specific attributes with default values. In addition the global attributes e.g. room can be used.

BasicPricePerAnnum : A valid float number for basic annual fee in the chosen currency for the water supply to the home. The value is provided by your local water supplier and is shown on your water bill. For UK and US users it may known under "standing charge". Please make sure it is based on one year! The default value is 0.00

Currency : One of the pre-defined list of currency symbols [€,£,$]. The default value is €

disable : Disables the current module. The module will not react on any events described in the regular expression. The default value is 0 = enabled.

WaterCounterOffset : A valid float number of the water Consumption difference = offset (not the difference of the counter ticks!) between the value shown on the mechanic meter for the water consumption and the calculated water consumption of the counting device. The value for this offset will be calculated as follows WOffset = WMechanical - WModule The default value is 0.00

WaterCubicPerCounts : A valid float number of water consumption in qm per counting ticks. The value is given by the mechanical trigger of the mechanical water meter. E.g. WaterCubicPerCounts = 0.001 means each count is a thousandth of one qm (=liter). The default value is 1 (= the counter is already providing qm)

WaterPricePerCubic : A valid float number for water Consumption price in the chosen currency per qm. The sewage water cost needs to be taken into account.The value is provided by your local water supplier and is shown on your water bill. The default value is 2.00

MonthlyPayment : A valid float number for monthly advance payments in the chosen currency towards the water supplier. The default value is 0.00

MonthOfAnnualReading : A valid integer number for the month when the mechanical water meter reading is performed every year. The default value is 5 (May)

ReadingDestination : One of the pre-defined list for the destination of the calculated readings: [CalculatorDevice,CounterDevice]. The CalculatorDevice is the device which has been created with this module. The CounterDevice is the Device which is reading the mechanical Water-meter. The default value is CalculatorDevice - Therefore the readings will be written into this device.

WFRUnit : One value of the pre-defined list: l/min (liter/minute), m³/min (cubicmeter/minute), m³/h (cubicmeter/hour). It defines which unit shall be used and devides the water flow rate accordingly. The default value is l/min (liter/minute).

DecimalPlace : A valid integer number for the number of decimal places taken into account. The default value is 3.




Readings

As soon the device has been able to read at least 2 times the counter, it automatically will create a set of readings: The placeholder <DestinationDevice> is the device which has been chosen in the attribute ReadingDestination above. This will not appear if CalculatorDevice has been chosen. The placeholder <SourceCounterReading> is the reading based on the defined regular expression where the counting ticks are coming from.

<DestinationDevice>_<SourceCounterReading>_CounterCurrent	: Current indicated total water consumption as shown on mechanical water meter. Correct Offset-attribute if not identical.
<DestinationDevice>_<SourceCounterReading>_CounterDay1st	: The first meter reading after midnight.
<DestinationDevice>_<SourceCounterReading>_CounterDayLast	: The last meter reading of the previous day.
<DestinationDevice>_<SourceCounterReading>_CounterMonth1st	: The first meter reading after midnight of the first day of the month.
<DestinationDevice>_<SourceCounterReading>_CounterMonthLast	: The last meter reading of the previous month.
<DestinationDevice>_<SourceCounterReading>_CounterMeter1st	: The first meter reading after midnight of the first day of the month where the mechanical meter is read by the Water supplier.
<DestinationDevice>_<SourceCounterReading>_CounterMeterLast	: The last meter reading of the previous meter reading year.
<DestinationDevice>_<SourceCounterReading>_CounterYear1st	: The first meter reading after midnight of the first day of the year.
<DestinationDevice>_<SourceCounterReading>_CounterYearLast	: The last meter reading of the previous year.
<DestinationDevice>_<SourceCounterReading>_ConsumptionCostDayLast	: Consumption costs of the last day.
<DestinationDevice>_<SourceCounterReading>_ConsumptionCostMeterLast	: Consumption costs in the chosen currency of the last water meter period.
<DestinationDevice>_<SourceCounterReading>_ConsumptionCostMonthLast	: Consumption costs in the chosen currency of the last month.
<DestinationDevice>_<SourceCounterReading>_ConsumptionCostYearLast	: Consumption costs of the last calendar year.
<DestinationDevice>_<SourceCounterReading>_ConsumptionCostDay	: Consumption costs in the chosen currency since the beginning of the current day.
<DestinationDevice>_<SourceCounterReading>_ConsumptionCostMeter	: Consumption costs in the chosen currency since the beginning of the month of where the last water meter reading has been performed by the Water supplier.
<DestinationDevice>_<SourceCounterReading>_ConsumptionCostMonth	: Consumption costs in the chosen currency since the beginning of the current month.
<DestinationDevice>_<SourceCounterReading>_ConsumptionCostYear	: Consumption costs in the chosen currency since the beginning of the current year.
<DestinationDevice>_<SourceCounterReading>_ConsumptionDay	: Consumption in qm since the beginning of the current day (midnight).
<DestinationDevice>_<SourceCounterReading>_ConsumptionDayLast	: Total Consumption in qm of the last day.
<DestinationDevice>_<SourceCounterReading>_ConsumptionMeter	: Consumption in qm since the beginning of the month of where the last Water-meter reading has been performed by the Water supplier.
<DestinationDevice>_<SourceCounterReading>_ConsumptionMeterLast	: Total Consumption in qm of the last Water-meter reading period.
<DestinationDevice>_<SourceCounterReading>_ConsumptionMonth	: Consumption in qm since the beginning of the current month (midnight of the first).
<DestinationDevice>_<SourceCounterReading>_ConsumptionMonthLast	: Total Consumption in qm of the last month.
<DestinationDevice>_<SourceCounterReading>_ConsumptionYear	: Consumption in qm since the beginning of the current year (midnight of the first).
<DestinationDevice>_<SourceCounterReading>_ConsumptionYearLast	: Total Consumption in qm of the last calendar year.
<DestinationDevice>_<SourceCounterReading>_FinanceReserve	: Financial Reserve based on the advanced payments done on the first of every month towards the water supplier. With negative values, an additional payment is to be expected.
<DestinationDevice>_<SourceCounterReading>_MonthMeterReading	: Number of month since last meter reading. The month when the reading occured is the first month = 1.
<DestinationDevice>_<SourceCounterReading>_WFRCurrent	: Current water flow rate. (water flow rate based on current and previous measurement.)
<DestinationDevice>_<SourceCounterReading>_WFRDayAver	: Average water flow rate since midnight.
<DestinationDevice>_<SourceCounterReading>_WFRDayMax	: Maximum water flow rate peak since midnight.
<DestinationDevice>_<SourceCounterReading>_WFRDayMin	: Minimum water flow rate peak since midnight.

Weather

[EN DE]

Note: you need the JSON perl module. Use apt-get install libjson-perl on Debian and derivatives.

The Weather module works with various weather APIs:

• DarkSky (web site, standard)
• OpenWeatherMap (web site)
• Wunderground (web site)

Such a virtual Weather device periodically gathers current and forecast weather conditions from the chosen weather API.



Define




define <name> Weather [API=<API>[,<apioptions>]] [apikey=<apikey>] [location=<location>] [interval=<interval>] [lang=<lang>]

The parameters have the following meanings:


API	name of the weather API, e.g. DarkSkyAPI
apioptions	indivual options for the chosen API
apikey	key for the chosen API
location	location for the weather forecast; e.g. coordinates, a town name or an ID, depending on the chosen API
interval	duration in seconds between updates
lang	language of the forecast: de, en, pl, fr, it or nl

A very simple definition is:

define <name> Weather apikey=<DarkSkyAPISecretKey>

This uses the Dark Sky API with an individual key that you need to retrieve from the Dark Sky web site.

Examples:

      define Forecast Weather apikey=987498ghjgf864
      define MyWeather Weather API=OpenWeatherMapAPI,cachemaxage:600 apikey=09878945fdskv876 location=52.4545,13.4545 interval=3600 lang=de
      define  Weather API=wundergroundAPI,stationId:IHAUIDELB111 apikey=ed64ccc80f004556a4e3456567800b6324a
    

API-specific documentation follows.

Dark Sky

API	DarkSkyAPI
apioptions	cachemaxage:<cachemaxage> duration in seconds to retrieve the forecast from the cache instead from the API
location	<latitude,longitude> geographic coordinates in degrees of the location for which the weather is forecast; if missing, the values of the attributes of the global device are taken, if these exist.

OpenWeatherMap

API	OpenWeatherMapAPI
apioptions	cachemaxage:<cachemaxage> duration in seconds to retrieve the forecast from the cache instead from the API	version:<version> API version which should be used. 2.5 by default, 3.0 is still possible but only with an additional subscription	endpoint:onecall only to test whether the API key which not officially for onecall is not supported yet onecall via API version 2.5. IMPORTANT!!! apioption version must not be set to 3.0
location	<latitude,longitude> geographic coordinates in degrees of the location for which the weather is forecast; if missing, the values of the attributes of the global device are taken, if these exist.

Wunderground

API	wundergroundAPI
apioptions	cachemaxage:<cachemaxage> duration in seconds to retrieve the forecast from the cache instead from the API stationId:ID-Num Station ID of the station to be read.
location	<latitude,longitude> geographic coordinates in degrees of the location for which the weather is forecast; if missing, the values of the attributes of the global device are taken, if these exist.

The module provides four additional functions WeatherAsHtml, WeatherAsHtmlV, WeatherAsHtmlH and WeatherAsHtmlD. The former two functions are identical: they return the HTML code for a vertically arranged weather forecast. The third function returns the HTML code for a horizontally arranged weather forecast. The latter function dynamically picks the orientation depending on wether a smallscreen style is set (vertical layout) or not (horizontal layout). Each version accepts an additional paramter to limit the numer of icons to display.

Example:

      define MyWeatherWeblink weblink htmlCode { WeatherAsHtmlH("MyWeather","h",10) }
    




Set

• set <name> update
  
  Forces the retrieval of the weather data. The next automatic retrieval is scheduled to occur interval seconds later.
• set <name> newLocation latitude,longitude
  
  set a new temporary location. the value pair Latitude Longitude is separated by a comma. if no value is entered (empty value), the location detected by definition is automatically taken.
  
  



Get

get <name> <reading>

Valid readings and their meaning (? can be one of 1, 2, 3, 4, 5 and stands for today, tomorrow, etc.):


.license	license of the API provider, if available
city	name of town returned for location
code	current condition code
condition	current condition
current_date_time	last update of forecast on server
fc?_code	forecast condition code
fc?_condition	forecast condition
fc?_day_of_week	day of week for day +?
fc?_high_c	forecasted daily high in degrees centigrade
fc?_icon	forecast icon
fc?_low_c	forecasted daily low in degrees centigrade
humidity	current humidity in %
icon	relative path for current icon
pressure	air pressure in hPa
pressure_trend	air pressure trend (0= steady, 1= rising, 2= falling)
pressure_trend_txt	textual representation of air pressure trend
pressure_trend_sym	symbolic representation of air pressure trend
temperature	current temperature in degrees centigrade
temp_c	current temperature in degrees centigrade
temp_f	current temperature in degrees Fahrenheit
visibility	visibility in km
wind	wind speed in km/h
wind_chill	wind chill in degrees centigrade
wind_condition	wind direction and speed
wind_direction	direction wind comes from in degrees (0 = north wind)
wind_speed	same as wind


The weekday of the forecast will be in the language of your FHEM system. Enter {$ENV{LANG}} into the FHEM command line to verify. If nothing is displayed or you see an unexpected language setting, add export LANG=de_DE.UTF-8 or something similar to your FHEM start script, restart FHEM and check again. If you get a locale warning when starting FHEM the required language pack might be missing. It can be installed depending on your OS and your preferences (e.g. dpkg-reconfigure locales, apt-get install language-pack-de or something similar).
Depending on the chosen API, other readings can be shown as well. The meaning of these readings can be determined from the API provider's documentation.



Attributes

• disable - disables the retrieval of weather data - the timer runs according to schedule, though no data is requested from the API.
• readingFnAttributes
• forecast - hourly/daily, display of forecast data.
• forecastLimit - Number of forecast data records which should be written as a reading.
• alerts - 0/1 should alert messages be written similar to Unwetterwarnung

WeekdayTimer

Define
define <name> WeekdayTimer <device> [<language>] [weekdays] <profile> [<command>|<condition>]

to set a weekly profile for <device>

You can define different switchingtimes for every day.
The new parameter is sent to the <device> automatically with

set <device> <para>

If you have defined a <condition>, this condition will be evaluated in the daily evaluation of the switching times. If false, no switching times will be set for this day. To force a re-evaluation, you may e.g. use the "enable" or "WDT_Params" commands
Alternatively you may define an own perl command with <command> that will be avaluated at each switchingtime.
<command> or <condition> are optional, if no explicit <command> is set, the command will be taken from commandTemplate attribute.

The following parameter are defined:

device
The device to switch at the given time.
language
Specifies the language used for definition and profiles. de,en,fr,nl are possible. The parameter is optional.
weekdays
Specifies the days for all timer in the WeekdayTimer. The parameter is optional. For details see the weekdays part in profile.
profile
Define the weekly profile. All timings are separated by space. A switchingtime can be defined in two ways: the classic definition or via the use of a weekprofile (see below, only temperature profiles can be set). Example for a classic definition:


[<weekdays>|]<time>|<parameter>

weekdays: optional, if not set every day of the week is used.
NOTE: It's highly recommended to not set weekdays if you just want your WeekdayTimer to switch all week long. Especially notations like "78" or "$we!$we" are contraproductive!

Otherwise you can define a day with its number or its shortname.

• 0,su sunday
• 1,mo monday
• 2,tu tuesday
• 3,we wednesday
• 4 ...
• 7,$we weekend ($we)
• 8,!$we weekday (!$we)

It is possible to define $we or !$we in daylist to easily allow weekend an holiday. $we !$we are coded as 7 8, when using a numeric daylist.
Note: $we will use general IsWe() function to determine $we handling for today and tomorrow. The complete daylist for all other days will reflect the results of holiday devices listed as holiday2we devices in global, including weekEnd and noWeekEnd (see global - holiday2we attribute).

time:define the time to switch, format: HH:MM:[SS](HH in 24 hour format) or a Perlfunction like {sunrise_abs()}. Within the {} you can use the variable $date(epoch) to get the exact switchingtimes of the week. Example: {sunrise_abs_dat($date)}

parameter:the parameter to be set, using any text value like on, off, dim30%, eco or comfort - whatever your device understands.
NOTE: Use ":" to replace blanks in parameter and escape ":" in case you need it. So e.g. on-till:06\:00 will be a valid parameter.

NOTE: When using $we in combination with regular weekdays (from 0-6), switchingtimes may be combined. If you want $we to be given priority when true, add a "|w" at the end of the respective profile:


[<weekdays>|]<time>|<parameter>|w


Example for a weekprofile definition:


weekprofile:<weekprofile-device-name>


Example for a weekprofile definition using sunday profile for all $we days, giving exclusive priority to the $we profile:


weekprofile:<weekprofile-device-name>:true

NOTE: only temperature profiles can be set via weekprofile, but they have the advantage of possible updates from weekprofile side (including the use of so-called topics) or via the command: set <device> weekprofile <weekprofile-device:topic:profile>

command
If no condition is set, all the rest is interpreted as a command. Perl-code is setting up by the well-known Block with {}.
Note: if a command is defined only this command is executed. In case of executing a "set desired-temp" command, you must define the hole command part explicitly by yourself.
If no explicit command is provided, commandTemplate attribute will indicate the command; this may be a simple set $NAME $EVENT or some variation wrt. to the device beeing recognized as heating type (see WDT_eventMap for even more options!). The following parameters are replaced:

1. $NAME => the device to switch
2. $EVENT => the new parameter (e.g. a temperature)
condition
if a condition is defined you must declare this with () and a valid perl-code.
The return value must be boolean.
The parameters $NAME and $EVENT will also be interpreted. If condition is provided and evaluation (at switchingtime) returns "0", the parameter will not be set, next check will be done as soon as next switchingtime is reached.

Examples:

define shutter WeekdayTimer bath 12345|05:20|up 12345|20:30|down
Mo-Fr are setting the shutter at 05:20 to up, and at 20:30 down.

define heatingBath WeekdayTimer bath 07:00|16 Mo,Tu,Th-Fr|16:00|18.5 20:00|eco {fhem("set dummy on"); fhem("set $NAME desired-temp $EVENT");}
At the given times and weekdays only(!) the command will be executed.

define dimmer WeekdayTimer livingRoom Sa-Su,We|07:00|dim30% Sa-Su,We|21:00|dim90% (ReadingsVal("WeAreThere", "state", "no") eq "yes")
The dimmer is only set to dimXX% if the dummy variable WeAreThere is "yes"(not a real live example).

If you want to have set all WeekdayTimer their current value (e.g. after a temperature lowering phase holidays) you can call the function WeekdayTimer_SetParm("WD-device") or WeekdayTimer_SetAllParms().
To limit the affected WeekdayTimer devices to a subset of all of your WeekdayTimers, use the WDT_Group attribute and WeekdayTimer_SetAllParms("").
This offers the same functionality than set wd WDT_Params WDT_Group This call can be automatically coupled to a dummy by a notify:
define dummyNotify notify Dummy:. * {WeekdayTimer_SetAllParms()}


Some definitions without comment:

        define wd    Weekdaytimer  device de         7|23:35|25        34|23:30|22 23:30|16 23:15|22     8|23:45|16
        define wd    Weekdaytimer  device de         fr,$we|23:35|25   34|23:30|22 23:30|16 23:15|22    12|23:45|16
        define wd    Weekdaytimer  device de         20:35|25          34|14:30|22 21:30|16 21:15|22    12|23:00|16

        define wd    Weekdaytimer  device de         mo-so, $we|{sunrise_abs_dat($date)}|on       mo-so, $we|{sunset_abs_dat($date)}|off
        define wd    Weekdaytimer  device de         mo-so,!$we|{sunrise_abs_dat($date)}|aus      mo-so,!$we|{sunset_abs_dat($date)}|aus

        define wd    Weekdaytimer  device de         {sunrise_abs_dat($date)}|19           {sunset_abs_dat($date)}|21
        define wd    Weekdaytimer  device de         22:35|25  23:00|16
        

The daylist can be given globaly for the whole Weekdaytimer:

        define wd    Weekdaytimer device de  !$we     09:00|19  (function("Ein"))
        define wd    Weekdaytimer device de   $we     09:00|19  (function("Ein"))
        define wd    Weekdaytimer device de           09:00|19  (function("exit"))
        define wd    Weekdaytimer device de   57      09:00|19  (function("exit"))
        define wd    Weekdaytimer device de  fr,$we   09:00|19  (function("exit"))
        

Set

set <name> <value>

where value is one of:


    disable               # disables the WeekdayTimer
    enable                # enables  the WeekdayTimer, switching times will be recaltulated. 
    WDT_Params [one of: single, WDT_Group or all]
    weekprofile <weekprofile-device:topic:profile>

You may especially use enable in case one of your global holiday2we devices has changed since 5 seconds past midnight.

Examples:
set wd disable
set wd enable
set wd WDT_Params WDT_Group
set wd weekprofile myWeekprofiles:holiday:livingrooms


• The WDT_Params function can be used to reapply the current switching value to the device, all WDT devices with identical WDT_Group attribute or all WeekdayTimer devices; delay conditions will be obeyed, for non-heating type devices, switchInThePast has to be set.

NOTES on weekprofile usage:


• The weekprofile set will only be successfull, if the <weekprofile-device> is part of the definition of the WeekdayTimer, the mentionned device exists and it provides data for the <topic:profile> combination. If you haven't activated the "topic" feature in the weekprofile device, use "default" as topic.
• Once you set a weekprofile for any weekprofile device, you'll find the values set in the reading named "weekprofiles"; for each weekprofile device there's an entry with the set triplett.
• As WeekdayTimer will recalculate the switching times for each day a few seconds after midnight, 10 minutes pas midnight will be used as a first switching time for weekpofile usage.
• This set is the way the weekprofile module uses to update a WeekdayTimer device. So aforementioned WeekdayTimer command
  set wd weekprofile myWeekprofiles:holiday:livingrooms
  is aequivalent to weekprofile command
  set myWeekprofiles send_to_device holiday:livingrooms wd
  
• Although it's possible to use more than one weekprofile device in a WeekdayTimer, this is explicitly not recommended unless you are exactly knowing what you are doing.
• Note: The userattr weekprofile will automatically be added to the list and can't be removed. The attribute itself is intended to be set to the corresponding profile name (no topic name, just the second part behind the ":") in your weekprofile device allowing easy change using the topic feature.
Get
N/A

Attributes
• delayedExecutionCond
  defines a delay Function. When returning true, the switching of the device is delayed until the function returns a false value. The behavior is the same as if one of the WDT_delayedExecutionDevices returns "open".
  Example:

  attr wd delayedExecutionCond isDelayed("$WEEKDAYTIMER","$TIME","$NAME","$EVENT")

  The parameters $WEEKDAYTIMER (timer name), $TIME, $NAME (device name) and $EVENT will be replaced at runtime by the correct value.
  Note: If the function returns "1" or "true", state of the WeekdayTimer will be "open window", other return values will be used as values for state.
  Example of a function:

  sub isDelayed($$$$) {
         my($wdt, $tim, $nam, $event ) = @_;
         my $theSunIsStillshining = ...
         return ($tim eq "16:30" && $theSunIsStillshining) ;
      }

• commandTemplate
  If no explicit command is provided, you may change change the indicated defaults here (see also WDT_eventMap for even more options on how to modify command or $EVENT).


• WDT_delayedExecutionDevices
  May contain a space separated list of devices (atm. only window sensors are supported). When one of them states to be open (typical reading names and values are known) the aktual switch is delayed, until either the window is closed or the next switching time is reached (this one will also be delayed). This is especially intended to prevent heating commands while windows are opened.


• WDT_Group
  Used to generate groups of WeekdayTimer devices to be switched together in case one of them is set to WDT_Params with the WDT_Group modifier, e.g. set wd WDT_Params WDT_Group.
  This originally was intended to allow Heating_Control devices to be migrated to WeekdayTimer by offering an alternative to the former Heating_Control_SetAllTemps() functionality.


• WDT_sendDelay
  This will add some seconds to each of the switching timers to avoid collissions in RF traffic, especially, when weekprofile option is used and e.g. a topic change may affect not only a single target device but many or a single profile is used for many devices.
  Make sure, the effective switch time for day's last switch is still taking place before midnight, otherwise it may not be executed at all!


• WDT_eventMap
  This will translate parameters from the profile to a different command. Syntax is (space separated): "<parameter>:<new command>", spaces have to be replaced by "+".
  Example:
  attr wd WDT_eventMap 22.0:dtp20+01 12.0:dtp20+02 18.0:dtp20+03
  Notes:
  
  • New command will be addressed directly to the device, especially commandTemplate content will be ignored. So e.g. if commandTemplate is set to set $NAME desired-temp $EVENT, parameter 22.0 will lead to set $NAME dtp20 01.
  • When using Perl command syntax for command, $EVENT will be replaced by the new command.


• switchInThePast
  defines that the depending device will be switched in the past in definition and startup phase when the device is not recognized as a heating. Heatings are always switched in the past.


• disable
• loglevel
• event-on-update-reading
• event-on-change-reading
• stateFormat

WifiLight

[EN DE]

The module controls a large number of different "no name" LED types and provide a consistent interface.

Following types will be supported:

type / bridge	type	note	define signature
Milight RGB first generation	E27, stripe controller	*(1,2,a,C)	RGB bridge-V2|3
Milight RGBW1 first generation	RGBW stripe controller	*(1,2,a)	RGBW1 bridge-V2|3
Milight Dual White	E14, E27, GU10, stripe controller, Downlight	*(1,2,b,W,nK)	White bridge-V2|3
Milight RGBW2 second generation	E14, E27, GU10, stripe controller, Downlight	*(2,b,CW,S20)	RGBW2 bridge-V3
LW12 first generation (SSID LEDNet...)	RGB stripe controller		RGB LW12
LW12HX (SSID HX...)	RGB stripe controller		RGB LW12HX
LW12FC (SSID FC...)	RGB stripe controller		RGB LW12FC
LD316 in RGB mode	E27		RGB LD316
LD316 in RGBW mode	E27	*(S20)	RGBW LD316
LD316A in RGBW mode	E27	*(S20)	RGBW LD316A
LD382 in RGB mode	RGB stripe controller		RGB LD382
LD382 in RGBW mode	RGBW stripe controller		RGBW LD382
LD382A (FW 1.0.6+) in RGB mode	RGB stripe controller		RGB LD382
LD382A (FW 1.0.6+) in RGBW mode	RGBW stripe controller		RGBW LD382
SENGLED	E27 bulb with build-in WLAN repeater		White Sengled
SUNRICHER with RGBW	Controller	*(!!!)	RGBW Sunricher

(1) milght brigbe V2, V3, V4
(2) milight bridge V3, V4
(a) one group per bridge
(b) four independent group per bridge
(nK) no color temp support (Kelvin)
(C) pure color
(W) pure white
(CW) pure Color or pure white
(S20) Saturation <20: switch to pure white channel
(!!!) EXPERIMENTAL


Color Colors can be specified in RGB or HSV color space. Color in color space "HSV" are completely and generally more intuitive than RGB. H (HUE: 0..360) are the basic color in a color wheel. Red is at 0 ° Green at 120 ° Blue at 240 ° S (Saturation: 0..100) stands for the saturation of the color. A saturation of 100 means the color is "pure" or completely saturated. Blue, for example, with 100% saturation corresponds to RGB # 0000FF. V (Value: 0..100) indicates the brightness. A value of 50 states that "half brightness".

Color: HSV compared to RGB

Normally, a color may be expressed in the HSV color space as well as in RGB color space.

Colors in the HSV color space usually seem more understandable. To move a Green in the HSV color space a little more toward CYAN, simply increase the HUE value (angle) slightly. In RGB color space, the same task is less intuitive to achieve by increasing blue.

Differences become clear in Transitions however. In order to dim BLUE up the HSV Transitions 240,100,0 -> 240,100,100 would be used. To slowly dim RED (brightness 0) to BLUE the Transition in the HSV color space is 0,100,0 -> 240,100,100. In RGB color space (# 000000 -> # 0000FF) can not distinguish between the two versions. Here (correctly, but probably differently than intended) would appear in both cases, a white (brightness 0) as an initial value.

Define

• define <name> WifiLight <LED type> <bridgetype>:<IP|FQDN>

  example

  defines a milight RGBW2 (bulb or LED stripe controller) on a milight bridge version 3 or 4. The LED is allocated to a maximum of 4 groups available per bridge in order of definition:
  define wz.licht.decke WifiLight RGBW2 bridge-V3:192.168.178.142

  defines a LD382A Controller with RGBW stripe:
  define wz.licht.decke WifiLight RGBW LD382A:192.168.178.142

  defines a LD382A Controller with RGB stripe:
  define wz.licht.decke WifiLight RGB LD382A:192.168.178.142

  WifiLight has a "color calibration". Ideally, a calibration should be performed every time after a lamp change or after definition.

Set

• set <name> on [ramp]

  Turns on the device. It is either chosen 100% White or the color defined by the attribute "default color".

  Advanced options:

  • ramp

• set <name> off [ramp]

  Turns of the device.

  Advanced options:

  • ramp

• set <name> dimup

  Increases the brightness by a fixed amount. The attribute "dimStep" or the default "7" is applied.
  This command is useful to increase particularly the brightness by a wall switch or a remote control.

  Advanced options:

  • none

• set <name> dimdown

  Decreases the brightness by a fixed amount. The attribute "dimStep" or the default "7" is applied.
  This command is useful to reduce particularly the brightness by a wall switch or a remote control.

  Advanced options:

  • none

• set <name> dim level [ramp] [q]

  Sets the brightness to the specified level (0..100). This command also maintains the preset color even with "dim 0" (off) and then "dim xx" (turned on) at. Therefore, it represents an alternative form to "off" / "on". The latter would always choose the "default color".

  Advanced options:

  • ramp

  Flags:

  • q

• set <name> HSV H,S,V [ramp] [s|l|q] [event]

  Sets the color in the HSV color space. If the ramp is specified (as a time in seconds), the module calculates a soft color transition from the current color to the newly set.

  For example, sets a saturated blue with half brightness:
  set wz.licht.decke HSV 240,100,50

  Advanced options:

  • ramp

  Flags:

  • s l q event

• set <name> RGB RRGGBB [ramp] [l|s|q] [event]

  Sets the color in the RGB color space.

  Advanced options:

  • ramp

  Flags:

  • s l q event

Meaning of Flags

Certain commands (set) can be marked with special flags.
• ramp:
  Time in seconds for a soft color or brightness transition. The soft transition starts at the currently visible color and is calculated for the specified.
• s:
  (short, default). A smooth transition to another color is carried out in the "color wheel" on the shortest path. A transition from red to green lead by the shortest route through yellow.
• l:
  (long). A smooth transition to another color is carried out in the "color wheel" on the "long" way. A transition from red to green then leads across magenta, blue, and cyan.
• q:
  (queue). Commands with this flag are cached in an internal queue and will not run before the currently running soft transitions have been processed. Commands without the flag will be processed immediately. In this case all running transitions are stopped immediately and the queue will be cleared.
• event:
  designator ([A-Za-z_0-9])

  WifiLight creates, when using this flag, during transitions to another color messages (events) in the form:

  WifiLight <NAME> programm: <EVENT> <XX>.

  <EVENT> is the designator as specified in the flag.
  <XX> is the progress (percentage) of the transition.
  

  Depending on the total duration of the transition, the values from 0 to 100 will not completely go through but for 0% and 100% is guaranteed always a event. To these events can then be reacted within a notify or DOIF to (for example):

  • increase the volume of a radio when a lamp is turned on in the morning slowly
  • A color transition can be restarted in a notify if it is complete (loop it, even complex transitions)
  • Other light sources can be synchronized by individually created color transitions.

color calibration

WifiLight supports two different types of color calibrations:

Correction of saturated colors

background:

YELLOW, for example, is defined as a mixture of red and green light in equal parts. Depending on the LED and control used the green channel may be much more luminous. If the red and green LEDs are each fully driven, GREEN predominates in this mixture and the desired YELLOW would get a distinct green tint. In this example, no yellow would be generated (corresponding to 60 ° in the "color wheel") for HSV 60,100,100. Instead GREEN would be generated with yellow tinge, perhaps corresponding to an estimated color angle of 80 °. The required correction for yellow would therefore minus 20° (60° target - 80° result = -20° correction). YELLOW may have to be corrected as to -20 °. Possible values per correction point are +/- 29 °.

procedure:

The correction of the full color is controlled by the attribute "color cast". Here 6 (comma separated) values are specified in the range from -29 to 29. These values are in accordance with the angle correction for red (0 °), yellow (60 °), green (120 °), cyan (180 °), blue (240 °) and magenta (300 °). First, the deviation of the mixed colors (60 ° / 180 ° / 300 °) should be determined as in the above example, and stored in the attribute. Following the primary colors (0 ° / 120 ° / 240 °) should be corrected so that the smooth transitions between adjacent pure colors appear as linear as possible. This process may need to be repeated iteratively multiple times until the result is harmonious.

White Balance

background:

Some bulbs produce white light by mixing the RGB channels (for example, LW12). Depending on the light intensity of the RGB channels of the LED strips used, the result is different. One or two colors dominate. In addition, there are various types of white light. Cold light has a higher proportion of blue. In Central Europe mostly warm white light is used for light sources. This has a high red and low blue component.

WifiLight offers the possibility for mixed RGB white to adapt the composition. The adjustment is carried out via the attribute "white point". The attribute expects a value between 0 and 1 (decimal point with) and the three colors are separated by a comma for each of the three RGB channels.

procedure:

A value of "1,1,1" sets all the three channels to 100% each. Assuming that the blue component of the white light should be reduced, a value of "1,1,0.5" sets the third channel (BLUE) in white on 0.5 according to 50%. Before doing a white balance correction the adjusment of the saturated color should be completed.

Attribute

• attr <name> colorCast <R,Y,G,C,B,M>

  color calibration of saturated colors. R(ed), Y(ellow), G(reen), C(yan), B(lue), M(agenta) in the range of +/- 29 (degrees)

• attr <name> defaultColor <H,S,V>

  Specify the light color in HSV which is selected at "on". Default is white.

• attr <name> defaultRamp <0 bis X>

  Time in seconds. If this attribute is set, a smooth transition is always implicitly generated if no ramp in the set is indicated.

• attr <name> dimStep <0 bis 100>

  Value by which the brightness at dim up and dim-down is changed. Default is "7"

• attr <name> gamma <X.X>

  The human eye perceives brightness changes very differently to (logarithmic). At low output brightness even a small change in brightness is perceived as very strong and on the other side strong changes are needed at high luminance. Therefore, a logarithmic correction of brightness increase of lamps is necessary so that the increase is found to be uniform. Some controllers perform this correction internally. In other cases it is necessary to store this correction in the module. A gamma value of 1.0 (default) results in a linear output values. Values less than 1.0 lead to a logarithmic correction.

• attr <name> whitePoint <R,G,B>

  color calibration for mixed RGB white light.

• attr <name> readingFnAttributes

Colored device-icon for FhemWeb

To activate a colored icon for FhemWeb the following attribute must be set:

• attr <name> devStateIcon {Color_devStateIcon(ReadingsVal($name,"RGB","000000"))}

Colorpicker for FhemWeb

In order for the Color Picker can be used in FhemWeb following attributes need to be set:

• attr <name> webCmd RGB
• attr <name> widgetOverride RGB:colorpicker,RGB

Wunderground

[EN DE]

This module gets weather data and forecast from Weather Underground weather service.

Define

define <name> Wunderground <api-key> <query>

Example:

define WUweather Wunderground d123ab11bb2c3456 EDDF
define WUweather Wunderground d123ab11bb2c3456 pws:IBAYERNM70
define WUweather Wunderground d123ab11bb2c3456 Germany/Berlin






Set
• update - refresh data


Attributes
• pollInterval - Set regular polling interval in seconds (default=300)
• wu_bestfct - Use Weather Undergrond Best Forecast for forecast (default=1)
• wu_features - One or more of the data features to be fetched (default=astronomy,conditions,forecast)
• wu_lang - Returns the API response in the specified language (default=en)
• wu_pws - Use personal weather stations for conditions (default=1)

X10

[EN DE]

Define
define <name> X10 <model> <housecode> <unitcode>

Defines an X10 device via its model, housecode and unitcode.

Notes:
• <model> is one of
  • lm12: lamp module, dimmable
  • lm15: lamp module, not dimmable
  • am12: appliance module, not dimmable
  • tm12: tranceiver module, not dimmable. Its unitcode is 1.
  Model determines whether a dim command is reasonable to be sent or not.
• <housecode> ranges from A to P.
• <unitcode> ranges from 1 to 16.

Examples:
define lamp1 X10 lm12 N 10
define pump X10 am12 B 7
define lamp2 X10 lm15 N 11


Set
set <name> <value> [<argument>]

where value is one of:


    dimdown            # requires argument, see the note
    dimup              # requires argument, see the note
    off
    on
    on-till            # Special, see the note
    on-till-overnight  # Special, see the note
    off-till           # Special, see the note
    off-till-overnight # Special, see the note
    on-for-timer       # Special, see the note
    off-for-timer      # Special, see the note
    

Examples:
set lamp1 dimup 10
set lamp1,lamp2 off
set pump off
set lamp2 on-till 19:59
set lamp2 on-for-timer 00:02:30
set lamp2 on-for-timer 150


Notes:
• Only switching and dimming are supported by now.
• Dimming is valid only for a dimmable device as specified by the model argument in its define statement.
• An X10 device has 210 discrete brightness levels. If you use a X10 sender, e.g. a remote control or a wall switch to dim, a brightness step is 100%/210.
• dimdown and dimup take a number in the range from 0 to 22 as argument. It is assumed that argument 1 is a 1% brightness change (microdim) and arguments 2 to 22 are 10%..100% brightness changes. The meaning of argument 0 is unclear.
• This currently leads to some confusion in the logs as the dimdown and dimup codes are logged with different meaning of the arguments depending on whether the commands were sent from the PC or from a remote control or a wall switch.
• dimdown and dimup from on and off states may have unexpected results. This seems to be a feature of the X10 devices.
• on-till requires an absolute time in the "at" format (HH:MM[:SS]) or { <perl code> }, where the perl code returns a time specification). If the current time is greater than the specified time, then the command is ignored, else an "on" command is generated, and for the given "till-time" an off command is scheduleld via the at command. off-till invert the conditions above.
• on-till-overnight or off-till-overnight the specified time is not compared to the current time.
• on-for-timer or off-for-timer requires a relative time in the "at" format (HH:MM[:SS]) or { <perl code> }, where the perl code returns a time specification) or seconds.

Get
N/A

Attributes
• do_not_notify
• dummy
• showtime
• model (lm12,lm15,am12,tm13)
• IODev


• eventMap

Xiaomi BTLE Sensor

[EN DE]

XiaomiBTLESens - Retrieves data from a Xiaomi BTLE Sensor
With this module it is possible to read the data from a sensor and to set it as reading.
Gatttool and hcitool is required to use this modul. (apt-get install bluez)

Define

define <name> XiaomiBTLESens <BT-MAC>

Example:

define Weihnachtskaktus XiaomiBTLESens C4:7C:8D:62:42:6F


This statement creates a XiaomiBTLESens with the name Weihnachtskaktus and the Bluetooth Mac C4:7C:8D:62:42:6F.
After the device has been created and the model attribut is set, the current data of the Xiaomi BTLE Sensor is automatically read from the device.


Readings
• state - Status of the flower sensor or error message if any errors.
• batteryState - current battery state dependent on batteryLevel.
• batteryPercent - current battery level in percent.
• fertility - Values for the fertilizer content
• firmware - current device firmware
• lux - current light intensity
• moisture - current moisture content
• temperature - current temperature


Set
• devicename - set a devicename
• resetBatteryTimestamp - when the battery was changed




Get
• sensorData - retrieves the current data of the Xiaomi sensor
• devicename - fetch devicename
• firmware - fetch firmware




Attributes
• disable - disables the device
• disabledForIntervals - disable device for interval time (13:00-18:30 or 13:00-18:30 22:00-23:00)
• interval - interval in seconds for statusRequest
• minFertility - min fertility value for low warn event
• hciDevice - select bluetooth dongle device
• model - set model type
• maxFertility - max fertility value for High warn event
• minMoisture - min moisture value for low warn event
• maxMoisture - max moisture value for High warn event
• minTemp - min temperature value for low warn event
• maxTemp - max temperature value for high warn event
• minlux - min lux value for low warn event
• maxlux - max lux value for high warn event
  Event Example for min/max Value's: 2017-03-16 11:08:05 XiaomiBTLESens Dracaena minMoisture low
  Event Example for min/max Value's: 2017-03-16 11:08:06 XiaomiBTLESens Dracaena maxTemp high
• sshHost - FQD-Name or IP of ssh remote system / you must configure your ssh system for certificate authentication. For better handling you can config ssh Client with .ssh/config file
• batteryFirmwareAge - how old can the reading befor fetch new data
• blockingCallLoglevel - Blocking.pm Loglevel for BlockingCall Logoutput

XiaomiDevice

[EN DE]

This modul connects to the Xiaomi Vacuums, Air Purifiers, Humidifiers, Fans and a few other devices.

Required Perl Libraries:
Via the package manager, install libjson-perl, libdigest-md5-perl, libcrypt-cbc-perl, libcrypt-ecb-perl
Via CPAN install Crypt::Cipher::AES or Crypt::Rijndael_PP

Define
define <name> XiaomiDevice <ip> [<token>]
Example: define vacuum XiaomiDevice 192.168.178.123 12345678901234567890123456789012
Example: define airpurifier XiaomiDevice 192.168.178.123
 
• ip
  Local IP of the device


• token
  Token of the device (mandatory for VacuumCleaner)



Get
• data
  Manually trigger data update


• settings
  Manually read settings


• clean_summary
  Manually read clean summary data



Set
• reconnect
  Reconnect the device


• wifi_setup <ssid> <password> <uid>
  WiFi setup: SSID, PASSWORD and Xiaomi User ID are needed for MiHome use


• start (VacuumCleaner)
  Start cleaning


• spot (VacuumCleaner)
  Start spot cleaning


• zone pointA1,pointA2,pointA3,pointA4,count [pointB1,pointB2,pointB3,pointB4,count](VacuumCleaner)
  Start zone cleaning (enter points for one or more valid zones)


• pause (VacuumCleaner)
  Pause cleaning


• resume (VacuumCleaner)
  Resume zoned cleaning when paused


• stop (VacuumCleaner)
  Stop cleaning


• charge (VacuumCleaner)
  Return to dock


• goto pointX,pointY (VacuumCleaner)
  Go to point X/Y (needs to be valid on the map)


• save_map ?,pointX,pointY (VacuumCleaner)
  Save exclusion lines/zones (needs to be valid on the map)
  e.g.: 1,26353,26920,27314,26042 0,25375,26490,25884,26490,25884,25860,25375,25860


• start_edit_map (VacuumCleaner)
  Start editing the map


• locate (VacuumCleaner)
  Locate the vacuum cleaner


• fan_power [1..100] (VacuumCleaner)
  Set suction power. (Quiet=38, Balanced=60, Turbo=77, Full Speed=90)


• remotecontrol start/stop (VacuumCleaner)
  Start or stop remote control mode


• move direction velocity [time] or left/right (VacuumCleaner/Fan)
  Move the vacuum in remotecontrol mode
  direction: -100..100
  velocity: 0..100
  time: time in ms (default=1000)


• reset_consumable filter/mainbrush/sidebrush/sensors (VacuumCleaner)
  Reset the consumables


• timer hh:mm days (VacuumCleaner)
  Set a new timer


• timerN on/off/delete (VacuumCleaner)
  Enable, disable or delete an existing timer


• timerN_time hh:mm (VacuumCleaner)
  Change the time for an existing timer


• timerN_days days (VacuumCleaner)
  Change the days for an existing timer


• dnd_enabled (VacuumCleaner)
  Enable/disable DND mode


• dnd_start hh:mm (VacuumCleaner)
  Set DND start time


• dnd_end hh:mm (VacuumCleaner)
  Set DND end time


• on / off (AirPurifier/Humidifier/Fan)
  Turn the device on or off


• mode (AirPurifier/Humidifier/Fan)
  Set the device mode
  AirPurifier: auto,silent,favorite
  Humidifier: silent,medium,high,auto
  Fan: straight,natural,sleep
  


• favorite (AirPurifier)
  Set the speed for favorite mode (0..16)


• preset (AirPurifier)
  Set a preset from attribute preset ('mode auto')


• buzzer (AirPurifier/Humidifier/Fan)
  Set the buzzer (on,off)


• led (AirPurifier/Humidifier/Fan)
  Set the LED (on,bright,dim,off)


• child_lock (AirPurifier/Humidifier/Fan)
  Set the child lock (on,off)


• turbo (AirPurifier)
  Set the turbo mode (on,off)


• limit_hum (Humidifier)
  Set the target humidity (30..90%) for mode "auto"


• dry (Humidifier)
  Set the dry mode (on,off)



Readings
• state
  Current state
  


• fan_power (VacuumCleaner)
  Fan power in %
  


• error_code (VacuumCleaner)
  Error code
  


• event (VacuumCleaner)
  Last event (e.g., bin_full)
  


• consumables_X (VacuumCleaner)
  Consumables time remaining in %
  


• dnd (VacuumCleaner)
  Current DND mode state
  


• X_clean_area (VacuumCleaner)
  Area cleaned in m²
  


• X_clean_time (VacuumCleaner)
  Time cleaned in h
  


• total_cleans (VacuumCleaner)
  Total number of cleaning cycles
  


• serial_number (VacuumCleaner)
  Serial number of the vacuum
  


• timerN_X (VacuumCleaner)
  Timer details
  


• pm25 (AirPurifier)
  PM2.5 value in µg/m³
  


• pm25_average (AirPurifier)
  Average PM2.5 value in µg/m³
  


• temperature (AirPurifier/Humidifier/Fan)
  Temperature in ˚C
  


• humidity (AirPurifier/Humidifier/Fan)
  Humidity in %
  


• speed (AirPurifier/Humidifier/Fan)
  Fan speed in rpm
  


• usage (AirPurifier)
  Usage time in h
  


• filter_volume (AirPurifier)
  Total air volume in m³
  


• filter (AirPurifier)
  Filter life in %
  


• load_power (PowerPlug)
  Power consumption in W
  


• limit_hum (Humidifier)
  Upper humidity limit for mode "auto"
  


• dry (Humidifier)
  Current Drymode state
  


• depth (Humidifier)
  Current %-level in watertank
  



Attributes
• subType
  VacuumCleaner / AirPurifier / AirPurifier3H / SmartFan / SmartFan1X / SmartFan1C / SmartFanFA1 / TowerFanP9 / Humidifier / EvpHumidifier / HumidifierMJJSQ / RiceCooker / PowerPlug / SmartLamp


• disable
  Disables the module


• intervalData
  Interval for data update (min 10 sec)


• intervalSettings
  Interval for settings update (min 60 sec)


• preset (AirPurifier)
  Custom preset for dynamic mode changes (defaults to 'mode auto')


• point_names point1:[X,Y] point2:[X,Y] (VacuumCleaner)
  Custom named presets for points


• zone_names combinedzone:[X1,Y1,X2,Y2,times],[X1,Y1,X2,Y2,times] zone:[X1,Y1,X2,Y2,times] (VacuumCleaner)
  Custom named presets for cleaning zones


• map_names line_and_area:[1,X1,Y1,X2,Y2],[0,X1,Y1,X2,Y2,X3,Y3,X4,Y4] (VacuumCleaner)
  Custom named presets for exclusion maps

xmllist

[EN DE]

xmllist [devspec]

Returns an XML tree of device definitions. devspec is optional, and restricts the list of devices if specified.

Example:
fhem> xmllist
<FHZINFO>

<internal_LIST>

<internal name="global" state="internal" sets="" attrs="room configfile logfile ...">

<INT key="DEF" value="<no definition>"/>
<INT key="NR" value="0"/>
<INT key="STATE" value="internal"/>

[...]

YAAHM

[EN DE]

Yet Another Auto Home Module to set up a cyclic processing of commands (daily, weekly, monthly, yearly profile)

Usage

See German Wiki page


Define

define <name> YAAHM
Defines the YAAHM system.

Notes:
• This module uses the global attribute language to determine its output data
  (default: EN=english). For German output set attr global language DE.
• This module needs the JSON package

Set

• set <name> time <timeevent>
  Set the current house time (event), i.e. one of several values:
  • (after|before) midnight | [before|after] sunrise | [before|after] sunset are calculated from astronomical data (±offset). These values vary from day to day, only the offset can be specified in the daily profile.
  • morning | noon | afternoon | evening | night are fixed time events specified in the daily profile. The time phase between events morning and night is called daytime, the time phase between events night and morning is called nighttime
  • wakeup|sleep are time events specified in the weekly default profiles Wakeup and Sleep, i.e. the value may change from day to day.
  The actual changes to certain devices are made by the functions in the command field, or by an external timeHelper function.
• set <name> manualnext <timernumber> <time>
set <name> manualnext <timername> <time>
  For the weekly timer identified by its number (starting at 0) or its name, set the next ring time manually. The time specification <time>must be in the format hh:mm, or "off", or "default".
  • If the time specification <time> is later than the current time, it will be used for today. If it is earlier than the current time, it will be used tomorrow.
  • If the time specification is "off", the next pending waketime will be ignored.
  • If the time specification id "default", the manual waketime is removed and the value from the weekly schedule will be used.
• set <name> mode normal | party | absence | donotdisturb
  Set the current house mode, i.e. one of several values:
  • normal - normal daily and weekly time profiles apply
  • party - can be used in the timeHelper function to suppress certain actions, like e.g. those that set the house (security) state to secured or the house time event to night.
  • absence - can be used in the timeHelper function to suppress certain actions. Valid until manual mode change
  • donotodisturb - can be used in the timeHelper function to suppress certain actions. Valid until manual mode change
  House modes are valid until manual mode change. If the attribute modeAuto is set (see below), mode will change automatically at certain time events. The actual changes to certain devices are made by an external modeHelper function.
• set <name> state unsecured | secured | protected | guarded
  Set house (security) state, i.e. one of several values:
  • unsecured - Example: doors etc.
  • secured - Example: doors etc. are locked, windows may not be open
  • protected - Example: doors etc. are locked, windows may not be open, alarm system is armed
  • guarded - Example: doors etc. are locked, windows may not be open, alarm is armed, a periodic house check is run and a simulation as well
  House (security) states are valid until manual change. If the attribute stateAuto is set (see below), state will change automatically at certain times. The actual changes to certain devices are made by an external stateHelper function. If these external devices are in their proper state for a particular house (security) state can be checked automatically, see the attribute stateDevices
• set <name> checkstate 0|5|10
  Check the house (security) state for each of the devices defined in the stateDevices attribute in 0, 5 or 10 seconds from now
• set <name> correctstate
  Try to correct the house (security) state, by issueing a FHEM command set <device> <targetstate> for each of the devices defined in the stateDevices attribute and not in the proper state for the given house (security) state
• set <name> createWeekly <string>
  Create a new weekly profile <string>
• set <name> deleteWeekly <string>
  Delete the weekly profile <string>
• set <name> initialize
  Restart the internal timers
• set <name> locked|unlocked
  Set the lockstate of the yaahm module to locked (i.e., yaahm setups may not be changed) resp. unlocked (i.e., yaahm setups may be changed>)
• set <name> save|restore
  Manually save/restore the complete profile data to/from the external file YAAHMFILE (save done automatically at each timer start, restore at FHEM start)

Get

• get <name> next <timernumber>
get <name> next <timername>
  For the weekly timer identified by its number (starting at 0) or its name, get the next ring time in a format suitable for text devices.
• get <name> sayNext <timernumber>
get <name> sayNext <timername>
  For the weekly timer identified by its number (starting at 0) or its name, get the next ring time in a format suitable for speech devices.
• get <name> version
  Display the version of the module
• get <name> template
  Return an (empty) perl subroutine for the helper functions

Attributes

• attr <name> linkname <string>
  Name for yaahm web link, default: Profile
• attr <name> hiddenroom <string>
  Room name for hidden yaahm room (containing only the YAAHM device), default: ProfileRoom
• attr <name> lockstate locked|unlocked
  locked means that yaahm setups may not be changed, unlocked means that yaahm setups may be changed
• attr <name> simulation 0|1
  a value of 1 means that commands issued directly on the device as "set ... " will not be executed, but only simulated. Does not prevent the button click commands from the interactive web page to be executed.
• attr <name> noicons 0|1
  when set to 1, animated icons are suppressed
• attr <name> modecolor[0|1|2|3] color
  four color specifications to signal the modes normal (default #53f3c7), party (default #8bfa56), absence (default #ff9458), donotodisturb (default #fd5777),
• attr <name> statecolor[0|1|2|3] color
  four color specifications to signal the states unsecured (default #53f3c7), secured (default #ff9458), protected (default #f554e2) and guarded (default #fd5777)
• attr <name> timeHelper <name of perl program>
  name of a perl function that is called at each time step of the daily profile and for the two default weekly profiles
• attr <name> modeHelper <name of perl program>
  name of a perl function that is called at every change of the house mode
• attr <name> modeAuto 0|1
  If this attribute is set to 1, the house mode changes automatically at certain time events.
  • On time (event) sleep or morning, party mode will be reset to normal mode.
  • On time (event) wakeup, absence mode will be reset to normal mode.
  • On any time (event), donotdisturb mode will be reset to normal mode.
• attr <name> sunrise SunRise|AstroTwilightMorning|NauticTwilightMorning|CivilTwilightMorning|CustomTwilightMorning
attr <name> sunset SunSet|AstroTwilightEvening|NauticTwilightEvening|CivilTwilightEvening|CustomTwilightEvening
  Use different definitions for sunset and sunrise, see Module Astro
• attr <name> norepeat 0|1
  if set to 1, repeated executions of wakeup, sleep and other timer events from the weekly programme will be suppressed.
• attr <name> stateDevices (<device>:<state-unsecured>:<state-secured>:<state-protected>:<state-guarded>,)*
  comma separated list of devices and their state in each of the house (security) states. Each of the listed devices will be checked in the interval given by the stateInterval attribute for its proper state, and a stateWarning function will be called if it is not in the proper state.
• attr <name> stateInterval <integer>
  interval in minutes for checking all stateDevices for their proper state according of the house (security) state. Default 60 minutes.
• attr <name> stateWarning <name of perl program>
  name of a perl function that is called as stateWarning('device','desired state','actual state')if a device is not in the desired state.
• attr <name> stateHelper <name of perl program>
  name of a perl function that is called as stateHelper('event') at every change of the house (security) state
• attr <name> stateAuto 0|1
  If this attribute is set to 1, the house state changes automatically if certain modes are set or at certain time events
  • If leaving party mode and time event sleep, and currently in (security) state unsecured, the state will change to secured.
  • If in normal mode and time event sleep or night, and currently in (security) state unsecured, the state will change to secured.
• attr <name> deviceActions <comma-separated list of virtual device actions>
  list of virtual device actions that yaahm is performing, e.g. roller_up, roller_down etc.
• attr <name> holidayDevices <comma-separated list of devices>
  list of devices that provide holiday information. The devices may be holiday devices or Calendar devices
• attr <name> vacationDevices <comma-separated list of devices>
  list of devices that provide vacation information. The devices may be holiday devices or Calendar devices
• attr <name> specialDevices <comma-separated list of devices>
  list of devices that provide special date information (like e.g. garbage collection). The devices may be holiday devices or Calendar devices

YAMAHA_AVR

[EN DE]

Define

define <name> YAMAHA_AVR <ip-address> [<zone>] [<status_interval>]

define <name> YAMAHA_AVR <ip-address> [<zone>] [<off_status_interval>] [<on_status_interval>]

This module controls AV receiver from Yamaha via network connection. You are able to power your AV reveiver on and off, query it's power state, select the input (HDMI, AV, AirPlay, internet radio, Tuner, ...), select the volume or mute/unmute the volume.

Defining a YAMAHA_AVR device will schedule an internal task (interval can be set with optional parameter <status_interval> in seconds, if not set, the value is 30 seconds), which periodically reads the status of the AV receiver (power state, selected input, volume and mute status) and triggers notify/filelog commands.

Different status update intervals depending on the power state can be given also. If two intervals are given in the define statement, the first interval statement stands for the status update interval in seconds in case the device is off, absent or any other non-normal state. The second interval statement is used when the device is on. Example:


define AV_Receiver YAMAHA_AVR 192.168.0.10

# With custom status interval of 60 seconds
define AV_Receiver YAMAHA_AVR 192.168.0.10 mainzone 60

# With custom "off"-interval of 60 seconds and "on"-interval of 10 seconds
define AV_Receiver YAMAHA_AVR 192.168.0.10 mainzone 60 10


Zone Selection

If your receiver supports zone selection (e.g. RX-V671, RX-V673,... and the AVANTAGE series) you can select the zone which should be controlled. The RX-V3xx and RX-V4xx series for example just have a "Main Zone" (which is the whole receiver itself). In general you have the following possibilities for the parameter <zone> (depending on your receiver model).


• mainzone - this is the main zone (standard)
• zone2 - The second zone (Zone 2)
• zone3 - The third zone (Zone 3)
• zone4 - The fourth zone (Zone 4)

Depending on your receiver model you have not all inputs available on these different zones. The module just offers the real available inputs.

Example:


define AV_Receiver YAMAHA_AVR 192.168.0.10     # If no zone is specified, the "Main Zone" will be used.
attr AV_Receiver YAMAHA_AVR room Livingroom

# Define the second zone
define AV_Receiver_Zone2 YAMAHA_AVR 192.168.0.10 zone2
attr AV_Receiver_Zone2 room Bedroom


For each Zone you will need an own YAMAHA_AVR device, which can be assigned to a different room. Each zone can be controlled separatly from all other available zones.



Set

set <name> <command> [<parameter>]

Currently, the following commands are defined; the available inputs are depending on the used receiver. The module only offers the real available inputs and scenes. The following input commands are just an example and can differ.


• on   -   powers on the device
• off   -   shuts down the device
• input hdm1,hdmX,...   -   selects the input channel (only the real available inputs were given)
• scene scene1,sceneX   -   select the scene
• volume 0...100 [direct]   -   set the volume level in percentage. If you use "direct" as second argument, no volume smoothing is used (if activated) for this volume change. In this case, the volume will be set immediatly.
• volumeStraight -80...15 [direct]   -   set the volume level in decibel. If you use "direct" as second argument, no volume smoothing is used (if activated) for this volume change. In this case, the volume will be set immediatly.
• volumeUp [0-100] [direct]   -   increases the volume level by 5% or the value of attribute volumeSteps (optional the increasing level can be given as argument, which will be used instead). If you use "direct" as second argument, no volume smoothing is used (if activated) for this volume change. In this case, the volume will be set immediatly.
• volumeDown [0-100] [direct]   -   decreases the volume level by 5% or the value of attribute volumeSteps (optional the decreasing level can be given as argument, which will be used instead). If you use "direct" as second argument, no volume smoothing is used (if activated) for this volume change. In this case, the volume will be set immediatly.
• hdmiOut1 on|off   -   controls the HDMI output 1
• hdmiOut2 on|off   -   controls the HDMI output 2
• mute on|off|toggle   -   activates volume mute
• bass [-6...6] step 0.5 (main zone), [-10...10] step 2 (other zones), [-10...10] step 1 (other zones, DSP models)   -   set bass tone level in decibel
• treble [-6...6] step 0.5 (main zone), [-10...10] step 2 (other zones), [-10...10] step 1 (other zones, DSP models)   -   set treble tone level in decibel
• dsp hallinmunich,hallinvienna,...   -   sets the DSP mode to the given preset
• enhancer on|off   -   controls the internal sound enhancer
• 3dCinemaDsp auto|off   -   controls the CINEMA DSP 3D mode
• adaptiveDrc auto|off   -   controls the Adaptive DRC
• partyMode on|off   -  controls the party mode. In Main Zone the whole party mode is enabled/disabled system wide. In each zone executed, it enables/disables the current zone from party mode.
• navigateListMenu <item1>/<item2>/.../<itemN>   -   select a specific item within a menu structure. for menu-based inputs (e.g. Net Radio, USB, Server, ...) only. See chapter Automatic Menu Navigation for further details and examples.
• tunerFrequency <frequency> [AM|FM]   -   sets the tuner frequency. The first argument is the frequency, second parameter is optional to set the tuner band (AM or FM, default: FM). Depending which tuner band you select, the frequency is given in kHz (AM band) or MHz (FM band). If the second parameter is not set, the FM band will be used. This command can be used even the current input is not "tuner", the new frequency is set and will be played, when the tuner gets active next time.
• tunerFrequencyBand FM|DAB   -   controls the used tuner frequency band ("FM" for analog frequency modulation or "DAB" for digital audio broadcasting. Only available if device supports DAB. On devices using an analog tuner, the frequency band (AM/FM) can be changed via set command "tunerFrequency".
data-pattern="preset.*">
• preset 1...40   -   selects a saved preset of the currently selected input.
• presetUp   -   selects the next preset of the currently selected input.
• presetDown   -   selects the previous preset of the currently selected input.
• straight on|off   -   bypasses the internal codec converter and plays the original sound codec
• direct on|off   -   bypasses all internal sound enhancement features and plays the sound straight directly
• sleep off,30min,60min,...,last   -   activates the internal sleep timer
• shuffle on,off   -   activates the shuffle mode on the current input
• surroundDecoder dolbypl,...   -   set the surround decoder. Only the available decoders were given if the device supports the configuration of the surround decoder.
• extraBass off,auto   -   controls the extra bass. Only available if supported by the device.
• ypaoVolume off,auto   -   controls the YPAO volume. Only available if supported by the device.
• displayBrightness -4...0   -   controls brightness reduction of the front display. Only available if supported by the device.
• repeat one,all,off   -   activates the repeat mode on the current input for one or all titles
• pause   -   pause playback on current input
• play   -   start playback on current input
• stop   -   stop playback on current input
• skip reverse,forward   -   skip track on current input
• statusRequest   -   requests the current status of the device
• remoteControl up,down,...   -   sends remote control commands as listed below


Remote control (not in all zones available, depending on your model)


Cursor Selection:


remoteControl up
remoteControl down
remoteControl left
remoteControl right
remoteControl enter
remoteControl return



Menu Selection:


remoteControl setup
remoteControl option
remoteControl display



Tuner Control:


remoteControl tunerPresetUp
remoteControl tunerPresetDown



The button names are the same as on your remote control.

Automatic Menu Navigation (only for menu based inputs like Net Radio, Server, USB, ...)


For menu based inputs you have to select a specific item out of a complex menu structure to start playing music. Mostly you want to start automatic playback for a specific internet radio (input: Net Radio) or similar, where you have to navigate through several menu and submenu items.

To automate such a complex menu navigation, you can use the set command "navigateListMenu". As Parameter you give a menu path of the desired item you want to select. YAMAHA_AVR will go through the menu and selects all menu items given as parameter from left to right. All menu items are separated by a forward slash (/).

So here are some examples: Receiver's current input is "netradio":


set <name> navigateListMenu Countries/Australia/All Stations/1Radio.FM
set <name> navigateListMenu Bookmarks/Favorites/1LIVE

If you want to turn on your receiver and immediatly select a specific internet radio you may use:


set <name> on ; set <name> volume 20 direct ; set <name> input netradio ; set <name> navigateListMenu Bookmarks/Favorites/1LIVE

# for regular execution to a specific time using the at module
define turn_on_Radio_morning at *08:00 set <name> on ; set <name> volume 20 direct ; set <name> input netradio ; set <name> navigateListMenu Countries/Australia/All Stations/1Radio.FM

define turn_on_Radio_evening at *17:00 set <name> on ; set <name> volume 20 direct ; set <name> input netradio ; set <name> navigateListMenu Bookmarks/Favorites/1LIVE

Receiver's current input is "server" (network DLNA shares):


set <name> navigateListMenu NAS/Music/Sort By Artist/Alicia Keys/Songs in A Minor/Fallin

The exact menu structure depends on your own configuration and network devices who provide content. Each menu item name has not to be provided fully. Each item name will be treated as keyword search. That means, if any menu item contains the given item name, it will be selected, for example:


Your real menu path you want to select looks like this: Bookmarks => Favorites => foo:BAR 70's-90's [[HITS]]

The last item has many non-word characters, that can cause you trouble in some situations. But you don't have to use the full name to select this entry. It's enough to use a specific part of the item name, that only exists in this one particular item. So to select this item you can use for instance the following set command:

set <name> navigateListMenu Bookmarks/Favorites/foo:BAR

This works, even without giving the full item name (foo:BAR 70's-90's [[HITS]]).

This also allows you to pare down long item names to shorter versions. The shorter version must be still unique enough to identify the right item. The first item in the list (from top to bottom), that contains the given keyword, will be selected.



Get

get <name> <reading>

Currently, the get command only returns the reading values. For a specific list of possible values, see section "Generated Readings/Events".


Attributes
• do_not_notify
• disabledForIntervals
• readingFnAttributes


• requestTimeout
  Optional attribute change the response timeout in seconds for all queries to the receiver.
  
  Possible values: 1-5 seconds. Default value is 4 seconds.



• disable Optional attribute to disable the internal cyclic status update of the receiver. Manual status updates via statusRequest command is still possible.
  
  Possible values: 0 => perform cyclic status update, 1 => don't perform cyclic status updates.



• volumeSmoothChange
  Optional attribute to activate a smooth volume change.
  
  Possible values: 0 => off , 1 => on



• volumeSmoothSteps
  Optional attribute to define the number of volume changes between the current and the desired volume. Default value is 5 steps



• volumeSteps
  Optional attribute to define the default increasing and decreasing level for the volumeUp and volumeDown set command. Default value is 5%



• volumeMax
  Optional attribute to set an upper limit in percentage for volume changes. If the user tries to change the volume to a higher level than configured with this attribute, the volume will not exceed this limit.
  
  Possible values: 0-100%. Default value is 100% (no limitation)




Generated Readings/Events:

• 3dCinemaDsp - The status of the CINEMA DSP 3D mode (can be "auto" or "off")
• adaptiveDrc - The status of the Adaptive DRC (can be "auto" or "off")
• bass Reports the current bass tone level of the receiver or zone in decibel values (between -6 and 6 dB (mainzone) and -10 and 10 dB (other zones)
• direct - indicates if all sound enhancement features are bypassed or not ("on" => all features are bypassed, "off" => sound enhancement features are used).
• dsp - The current selected DSP mode for sound output
• displayBrightness - indicates the brightness reduction of the front display (-4 is the maximum reduction, 0 means no reduction; only available if supported by the device).
• enhancer - The status of the internal sound enhancer (can be "on" or "off")
• extraBass - The status of the extra bass (can be "auto" or "off", only available if supported by the device)
• input - The selected input source according to the FHEM input commands
• inputName - The input description as seen on the receiver display
• hdmiOut1 - The status of the HDMI output 1 (can be "on" or "off")
• hdmiOut2 - The status of the HDMI output 2 (can be "on" or "off")
• mute - Reports the mute status of the receiver or zone (can be "on" or "off")
• newFirmware - indicates if a firmware update is available (can be "available" or "unavailable"; only available for RX-Vx71, RX-Vx73, RX-Ax10 or RX-Ax20)
• power - Reports the power status of the receiver or zone (can be "on" or "off")
• presence - Reports the presence status of the receiver or zone (can be "absent" or "present"). In case of an absent device, it cannot be controlled via FHEM anymore.
• partyMode - indicates if the party mode is enabled/disabled for the whole device (in main zone) or if the current zone is enabled for party mode (other zones than main zone)
• sleep - indicates if the internal sleep timer is activated or not.
• straight - indicates if the internal sound codec converter is bypassed or not (can be "on" or "off")
• state - Reports the current power state and an absence of the device (can be "on", "off" or "absent")
• surroundDecoder - Reports the selected surround decoder in case of "Surround Decoder" is used as active DSP
• tunerFrequency - the current tuner frequency in kHz (AM band) or MHz (FM band)
• tunerFrequencyBand - the current tuner band (AM, FM or DAB if supported)
• treble Reports the current treble tone level of the receiver or zone in decibel values (between -6 and 6 dB (mainzone) and -10 and 10 dB (other zones)
• volume - Reports the current volume level of the receiver or zone in percentage values (between 0 and 100 %)
• volumeStraight - Reports the current volume level of the receiver or zone in decibel values (between -80.5 and +15.5 dB)
• ypaoVolume - The status of the YPAO valume (can be "auto" or "off", only available if supported by the device)

Input dependent Readings/Events:


• currentChannel - Number of the input channel (SIRIUS only)
• currentStation - Station name of the current radio station (available only on TUNER, HD RADIO, NET RADIO or PANDORA)
• currentStationFrequency - The tuner frequency of the current station (only available on Tuner or HD Radio)
• currentAlbum - Album name of the current song
• currentArtist - Artist name of the current song
• currentTitle - Title of the current song
• playStatus - indicates if the input plays music or not
• shuffle - indicates the shuffle status for the current input
• repeat - indicates the repeat status for the current input

Implementator's note

The module is only usable if you activate "Network Standby" on your receiver. Otherwise it is not possible to communicate with the receiver when it is turned off.

YAMAHA_BD

[EN DE]

Define
define <name> YAMAHA_BD <ip-address> [<status_interval>]

define <name> YAMAHA_BD <ip-address> [<off_status_interval>] [<on_status_interval>]

This module controls Blu-Ray players from Yamaha via network connection. You are able to switch your player on and off, query it's power state, control the playback, open and close the tray and send all remote control commands.

Defining a YAMAHA_BD device will schedule an internal task (interval can be set with optional parameter <status_interval> in seconds, if not set, the value is 30 seconds), which periodically reads the status of the player (power state, current disc, tray status,...) and triggers notify/filelog commands.

Different status update intervals depending on the power state can be given also. If two intervals are given to the define statement, the first interval statement represents the status update interval in seconds in case the device is off, absent or any other non-normal state. The second interval statement is used when the device is on. Example:


define BD_Player YAMAHA_BD 192.168.0.10

# With custom status interval of 60 seconds
define BD_Player YAMAHA_BD 192.168.0.10 60

# With custom "off"-interval of 60 seconds and "on"-interval of 10 seconds
define BD_Player YAMAHA_BD 192.168.0.10 60 10


Set
set <name> <command> [<parameter>]

Currently, the following commands are defined.


• on   -   powers on the device
• off   -   shuts down the device
• tray open,close   -   open or close the disc tray
• statusRequest   -   requests the current status of the device
• remoteControl up,down,...   -   sends remote control commands as listed in the following chapter

Playback control commands
• play   -   start playing the current media
• pause   -   pause the current media playback
• stop   -   stop the current media playback
• skip forward,reverse   -   skip the current track or chapter
• fast forward,reverse   -   fast forward or reverse playback
• slow forward,reverse   -   slow forward or reverse playback
• trickPlay normal,repeatChapter,repeatTitle,...   -   controls the Trick-Play features


Remote control


The following commands are available:

Number Buttons (0-9):


remoteControl 0
remoteControl 1
remoteControl 2
...
remoteControl 9



Cursor Selection:


remoteControl up
remoteControl down
remoteControl left
remoteControl right
remoteControl enter
remoteControl return



Menu Selection:


remoteControl OSDonScreen
remoteControl OSDstatus
remoteControl popupMenu
remoteControl topMenu
remoteControl setup
remoteControl home
remoteControl clear



Color Buttons:


remoteControl red
remoteControl green
remoteControl yellow
remoteControl blue



Play Control Buttons:


remoteControl program
remoteControl search
remoteControl repeat
remoteControl repeat-AB
remoteControl subtitle
remoteControl audio
remoteControl angle
remoteControl pictureInPicture
remoteControl secondAudio
remoteControl secondVideo



The button names are the same as on your remote control.


Get
get <name> <reading>

Currently, the get command only returns the reading values. For a specific list of possible values, see section "Generated Readings/Events".


Attributes
• do_not_notify
• readingFnAttributes


• disable
Optional attribute to disable the internal cyclic status update of the player. Manual status updates via statusRequest command is still possible.

Possible values: 0 => perform cyclic status update, 1 => don't perform cyclic status updates.


• request-timeout
Optional attribute change the response timeout in seconds for all queries to the player.

Possible values: 1-5 seconds. Default value is 4 seconds.


Generated Readings/Events:

• input - The current playback source (e.g. "DISC", "USB", "Network", "YouTube", ...)
• discType - The current type of disc, which is inserted (e.g. "No Disc", "CD", "DVD", "BD", ...)
• contentType - The current type of content, which is played (e.g. "audio", "video", "photo" or "no contents")
• error - indicates an hardware error of the player (can be "none", "fan error" or "usb overcurrent")
• power - Reports the power status of the player or zone (can be "on" or "off")
• presence - Reports the presence status of the player or zone (can be "absent" or "present"). In case of an absent device, it cannot be controlled via FHEM anymore.
• trayStatus - The disc tray status (can be "open" or "close")
• trickPlay - The current trickPlay mode
• state - Reports the current power state and an absence of the device (can be "on", "off" or "absent")


Input dependent Readings/Events:

• currentChapter - Number of the current DVD/BD Chapter (only at DVD/BD's)
• currentMedia - Name of the current file (only at USB)
• currentTrack - Number of the current CD-Audio title (only at CD-Audio)
• currentTitle - Number of the current title (only at DVD/BD's)
• playTimeCurrent - current timecode of played media
• playTimeTotal - the total time of the current movie (only at DVD/BD's)
• playStatus - indicates if the player plays media or not (can be "play", "pause", "stop", "fast fwd", "fast rev", "slow fwd", "slow rev")
• totalTracks - The number of total tracks on inserted CD-Audio

Implementator's note

• Some older models (e.g. BD-S671) cannot be controlled over networked by delivery. A firmware update is neccessary to control these models via FHEM. In general it is always recommended to use the latest firmware.
• The module is only usable if you activate "Network Control" on your player. Otherwise it is not possible to communicate with the player.

YAMAHA_MC

[EN DE]

Provides control for YAMAHA_MC

Notes
• Requirements: perl module JSON lately. There is reduced functionality if it is not installed, but the module will work with basic functions. Use "cpan install JSON" or operating system's package manager to install JSON Modul. Depending on your os the required package is named: libjson-perl or perl-JSON. Futher needed packages :


• sudo apt-get install libjson-perl
• sudo apt-get install libmp3-info-perl
• sudo apt-get install -y libnet-upnp-perl
• perl -MCPAN -e 'install MP3::Info'

This module controls musiccast devices from Yamaha via network connection. You are able to power your device on and off (=standby only), query it's power state, select the input (AirPlay, internet radio, Tuner, ...), select the volume or mute/unmute the volume.

Defining a YAMAHA_MC device will schedule an internal task (interval can be set with optional parameter <status_interval_on> and <status_interval_off> in seconds, if not set, the value is 60 seconds), which periodically reads the status of the musiccast device (power state, selected input, volume and mute status) and triggers notify/filelog commands.

Different status update intervals depending on the power state can be given also. If two intervals are given in the define statement, the first interval statement stands for the status update interval in seconds in case the device is off, absent or any other non-normal state. The second interval statement is used when the device is on.

Define

define <name> YAMAHA_MC <ip_address|fqdn> [<port>] [<off_status_interval>] [<on_status_interval>]


Mandatory:

<name>
Specifies a device name of your choise.
eg. WX030xx

<ip_address|fqdn>
Specifies device IP address or hostname.
eg. 172.16.4.100
eg. wx030.your.domain.net

Mandatory

<port>
Specifies your http port to be used. Default: 80
eg. 88

<off_status_interval> Specifies time in seconds the status of the device is polled when it is turned off. Default: 60
eg. 88

<on_status_interval>
Specifies time in seconds the status of the device is polled when it is turned on. Default: 60
eg. 88


Define Examples:

• define wx030 YAMAHA_MC 192.168.0.100 80 60 60

Set set <name> <command> [<parameter>]

Currently, the following commands are defined; the available inputs are depending on the used device. The module only offers the real available inputs. The following input commands are just an example and can differ.


• on   -   powers on the device
• off   -   set the device in standby, real shutdown not possible
+
• toggle   -   Toggle between power on and standby
+
• power on|standby|toggle   -   powers on the device or sets it to standby
• input hdm1,hdmX,...   -   selects the input channel (only the real available inputs were given)
• volume 0...100 [direct]   -   set the volume level in percentage. If you use "direct" as second argument, no volume smoothing is used (if activated) for this volume change. In this case, the volume will be set immediatly.
• volumeUp   -   increases the volume level by the value of attribute volumeSteps
• volumeDown   -   decreases the volume level by the value of attribute volumeSteps
• mute on|off|toggle   -   activates volume mute
• setSpeakerA on|off|toggle   -   turns on/off speakers on A only possible if supported by device
• setSpeakerB on|off|toggle   -   turns on/off speakers on B only possible if supported by device
• navigateListMenu [item1]/[item2]/.../[itemN]   -   select a specific item within a menu structure. for menu-based inputs (e.g. Net Radio, USB, Server, ...) only. See chapter Automatic Menu Navigation for further details and examples.
• sleep off,30min,60min,...,last   -   activates the internal sleep timer
• pause   -   pause playback on current input
• play   -   start playback on current input
• stop   -   stop playback on current input
• skip reverse,forward   -   skip track on current input
• statusRequest   -   requests the current status of the device
• getMenuItems   -   requests the current menu information and fills the menulist for selection in selectMenuItem
• getMenu   -   requests the current menu information
• selectMenu   -   selects one menu item of the current menu by index, starts with 0
• selectMenuItem   -   selects one menu item of the current menu by current menu list items, use getMenuItems before
• selectPlayMenu   -   selects one menu item of the current menu to play by index, starts with 0
• selectPlayMenuItem   -   selects one menu item of the current menu to play by current menu list items, use getMenuItems before
• returnMenu   -   go back one level in current menu structure
• TurnFavNetRadioChannelOn   -   go to the menu defined by index in attribute pathToFavoritesNetRadio and play the favourite channel defined in FavoriteNetRadioChannel
• NetRadioNextFavChannel   -   go to the menu defined by index in attribute pathToFavoritesNetRadio and play the next channel in menu list
• NetRadioPrevFavChannel   -   go to the menu defined by index in attribute pathToFavoritesNetRadio and play the previous channel in menu list
• getNetworkStatus   -   requests the current network info like network_name, wlan and wlan strength
• getLocationInfo   -   requests the current location info like zones
• getPlayInfo   -   requests the current playback info of the device like play status
• toggleRepeat   -   toggles the Repeat Function in netusb Mode
• toggleShuffle   -   toggles the Shuffle Function in netusb Mode
• getDeviceInfo   -   requests the current device info of the device like model_name, firmware, device_id
• getFeatures   -   requests the general status of the device, creates the possible inputs
• getFuncStatus   -   requests the general functions of the device, creates the possible speakers/headphone
• getStatus   -   requests the general status of the device, updates volume, current_input, mute tc.
• statusRequest   -   requests the current status of the device


Menu Navigation (only for menu based inputs like Net Radio, Server, USB, ...)

For menu based inputs you have to select a specific item out of a complex menu structure to start playing music. Mostly you want to start automatic playback for a specific internet radio (input: Net Radio) or similar, where you have to navigate through several menu and submenu items and at least play one item in the list items. The exact menu structure depends on your own configuration and network devices who provide content.

To ease such a complex menu navigation, you can use the following commands :

1. "navigateListMenu". As Parameter you give the index in the current menu of the desired item you want to select - starting with index=0. so you need to know your menu sttructure, you could see this on yamaha musiccast app. You may go through the menu and selects all menu items given as parameter from left to right.



2. "navigateListMenu". As Parameter you give the index in the current menu of the desired item you want to select - starting with index=0. so you need to know your menu sttructure, you could see this on yamaha musiccast app. You may go through the menu and selects all menu items given as parameter from left to right.



Get
get <name> <reading>

Currently, the get command only returns the reading values. For a specific list of possible values, see section "Generated Readings/Events".


Attributes
• do_not_notify
• disabledForIntervals
• readingFnAttributes


• request-timeout
Optional attribute change the response timeout in seconds for all queries to the musiccast device.

Possible values: 1-5 seconds and 10 seconds. Default value is 4 seconds.


• disable
Optional attribute to disable the internal cyclic status update of the musiccast device. Manual status updates via statusRequest command is still possible.

Possible values: 0 => perform cyclic status update, 1 => don't perform cyclic status updates.




• volumeSteps
Optional attribute to define the default increasing and decreasing level for the volumeUp and volumeDown set command. Default value is 3



• menuNameFavoritesNetRadio
Optional attribute to set the name of netradio Menu where the personal favourite channels are stored. Is for faster setting channel up and down



• pathToFavoritesNetRadio
Neccessary attribute if you want to use set commands NetRadioNextFavChannel, NetRadioPrevFavChannel and TurnFavNetRadioChannelOn for personal favourite channels.



• FavoriteNetRadioChannel
Neccessary attribute if you want to use TurnFavNetRadioChannelOn. This is the channel number of your most favourite channel in your list of personal favourite channels. Starts with channel 0.



• eventProcessing
Optional attribute to enable the udp listener. Status updates will be pushed from musiccast device to fhem via UDP events.

Possible values: 0 => disable event processing, 1 => enable event processing

YAMAHA_NP

[EN DE]

Define


define <name> YAMAHA_NP <ip–address> [<status_interval>]

Alternatively with different two off/on interval definitions (default is 30 seconds).

define <name> YAMAHA_NP <ip–address> [<off_status_interval>] [<on_status_interval>]

This FHEM module controls a Yamaha Network Player (such as MCR–N560, MCR–N560D, CRX–N560, CRX–N560D, CD–N500 or NP–S2000) connected to local network.
Devices implementing the communication protocol of the Yamaha Network Player App for i*S and Andr*id might also work.

Example:


define NP_Player YAMAHA_NP 192.168.0.15
attr NP_player webCmd input:selectStream:volume

# With custom status interval of 60 seconds
define NP_Player YAMAHA_NP 192.168.0.15 60
attr NP_player webCmd input:selectStream:volume

# With custom "off"–interval of 60 seconds and "on"–interval of 10 seconds
define NP_Player YAMAHA_NP 192.168.0.15 60 10
attr NP_player webCmd input:selectStream:volume

Set

set <name> <command> [<parameter>]

Note: Commands and parameters are case–sensitive. The module provides available inputs depending on the connected device. Commands are context–sensitive depending on the current input or action.


Available commands:


• CDTray – open/close the CD tray.
• checkForNewFirmware – Checks for firmware updates. The result is stored in 'Internals' und 'deviceInfo'.
• clockUpdate – updates the system clock with current time. The local time information is taken from the FHEM server.
• dimmer < 1..3 > – Sets the display brightness.
• directPlay < input:Stream Level 1,Stream Level 2,... > – allows direct stream selection e.g. CD:1, DAB:1, netradio:Bookmarks,SWR3 (case–sensitive)
• favoriteDefine < name:input[,Stream Level 1,Stream Level 2,...] > – defines and stores a favorite stream e.g. CoolSong:CD,1 (predefined favorites are the available inputs)
• favoriteDelete < name > – deletes a favorite stream
• favoritePlay < name > – plays a favorite stream
• friendlyName < name > – sets network player's friendly name (network name). String must be between 1 and 15 characters.
• input [<parameter>] – selects the input channel. The inputs are read dynamically from the device. Available inputs can be set (e.g. cd, tuner, aux1, aux2, ...).
• mute [on|off] – activates/deactivates muting
• off – shuts down the device
• on – powers on the device
• player [<parameter>] – sets player related commands
• play – play
• stop – stop
• pause – pause
• next – next item
• prev – previous item
• playMode [<parameter>] – sets player mode shuffle or repeat
• shuffleAll – Set shuffle mode
• shuffleOff – Remove shuffle mode
• repeatOff – Set repeat mode Off
• repeatOne – Set repeat mode One
• repeatAll – Set repeat mode All
• selectStream – direct context–sensitive stream selection depending on the input and available streams. Available streams are read out from device automatically. Depending on the number, this may take some time... (Limited to 999 list entries.) (see also 'maxPlayerLineItems' attribute
• soundBalance <-10..10> – Set balance
• soundEnhancer [on|off] – Music Enhancer on|off
• soundEqLow <-10..10> – Set EQ Low band
• soundEqMid <-10..10> – Set EQ Mid band
• soundEqHigh <-10..10> – Set EQ High band
• sleep [off|30min|60min|90min|120min] – activates the internal sleep timer
• standbyMode [eco|normal] – set the standby mode
• statusRequest [<parameter>] – requests the current status of the device
• basicStatus – requests the basic status such as volume input etc.
• playerStatus – requests the player status such as play status, song info, artist info etc.
• standbyMode – requests the standby mode information
• systemConfig – requests the system configuration
• tunerStatus – requests the tuner status such as FM frequency, preset number, DAB information etc.
• timerStatus – requests device's internal wake–up timer status
• networkInfo – requests device's network related information such as IP, Gateway, MAC address etc.
• timerSet – configures the timer according to timerHour, timerMinute, timerRepeat, timerVolume attributes that must be set before. This command does not switch on the timer. → 'timer on'.)
• timer [on|off] – sets device's internal wake–up timer.
  (Note: The timer will be activated according to the last stored timer parameters in the device. In order to modify please use the 'timerSet' command.)
• tunerFMFrequency [87.50 ... 108.00] – Sets the FM frequency. The value must be 87.50 ... 108.00 including the decimal point ('.') with two following decimals. Otherwise the value will be ignored. Available if input was set to FM.
• volume [0...100] – set the volume level in %
• volumeStraight [<VOL_MIN>...<VOL_MAX>] – set the volume as used and displayed in the device. <VOL_MIN> and <VOL_MAX> are read and set from the device automatically.
• volumeUp [<VOL_MIN>...<VOL_MAX>] – increases the volume by one device's absolute step. <VOL_MIN> and <VOL_MAX> are read and set from the device automatically.
• volumeDown [<VOL_MIN>...<VOL_MAX>] – increases the volume by one device's absolute step. <VOL_MIN> and <VOL_MAX> are read and set from the device automatically.

Get
get <name> <reading>

The 'get' command returns reading values. Readings are context–sensitive depending on the current input or action taken.


Attributes


• .DABList – (internal) attribute used for DAB preset storage.
• .favoriteList – (internal) attribute used for favorites storage.
• autoUpdatePlayerReadings – optional attribute for auto refresh of player related readings (default is 1).
• autoUpdatePlayerlistReadings – optional attribute for auto scanning of the playerlist content (default is 1). (Due to the playerlist information transfer concept this function might slow down the reaction time of the Yamaha App when used at the same time.)
• autoUpdateTunerReadings – optional attribute for auto refresh of tuner related readings (default is 1).
• directPlaySleepNetradio – optional attribute to define a sleep time between two netradio requests to the vTuner server while using the directPlay command. Increase in case of slow internet connection (default is 5 seconds).
• directPlaySleepServer – optional attribute to define a sleep time between two multimedia server requests while using the directPlay command. Increase in case of slow server connection (default is 2 seconds).
• disable – optional attribute to disable the internal cyclic status update of the NP. Manual status updates via statusRequest command is still possible. Possible values: 0 → perform cyclic status update, 1 → don't perform cyclic status updates (default is 1).
• do_not_notify
• maxPlayerListItems – optional attribute to limit the max number of player list items (default is 999).
• readingFnAttributes


• requestTimeout – optional attribute change the response timeout in seconds for all queries to the receiver. Possible values: 1...5 seconds (default value is 4).
• searchAttempts – optional attribute used by the directPlay command defining the max. number of finding the provided directory content tries before giving up. Possible values: 15...100 (default is 15).
• smoothVolumeChange – optional attribute for smooth volume change (significantly more Ethernet traffic is generated during volume change if set to 1) (default is 1).
• timerHour [0...23] – sets hour of device's internal wake–up timer
• timerMinute [0...59] – sets minutes of device's internal wake–up timer
• timerRepeat [once|every] – sets repetition mode of device's internal wake–up timer
• timerVolume [<VOL_MIN>...<VOL_MAX>] – sets volume of device's internal wake–up timer.


Readings


General readings:


• deviceInfo – Reports device specific grouped information such as uuid, ip address, etc.
• favoriteList – Reports stored favorites
• reading [reading] – Reports readings values


• .volumeStraightMax – device specific maximum volume
• .volumeStraightMin – device specific minimum volume
• .volumeStraightStep – device specific volume in/decrement step
• audioSource – consolidated audio stream information with currently selected input, player status (if used) and volume muting information (off|reading status...|input [(play|stop|pause[, muted])]])
• directPlay – status of directPlay command
• input – currently selected input
• mute – mute status on/off
• power – current device status on/off
• presence – presence status of the device (present|absent)
• selectStream – status of the selectStream command
• sleep – sleep timer value (off|30 min|60 min|90 min|120 min)
• soundEqLow – Balance value
• soundEnhancer – Music Enhancer on|off
• soundEqLow – Equalizer value Low band
• soundEqMid – Equalizer value Mid band
• soundEqHigh – Equalizer value High band
• standbyMode – status of the standby mode (normal|eco)
• state – current state information (on|off)
• volume – relative volume (0...100)
• volumeStraight – device specific absolute volume [<VOL_MIN>...<VOL_MAX>]

Player related readings:


• playerAlbumArtFormat – Reports the album art format (if available) of the currently played audio
• playerAlbumArtID – Reports the album art ID (if available) of the currently played audio
• playerAlbumArtURL – Reports the album art url (if available) of the currently played audio. The URL points to the network player
• playerDeviceType – Reports the device type (ipod|msc)
• playerIpodMode – Reports the Ipod Mode (normal|off)
• playerAlbum – Reports the album (if available) of the currently played audio
• playerArtist – Reports the artist (if available) of the currently played audio
• playerSong – Reports the song name (if available) of the currently played audio
• playerPlayTime – Reports the play time of the currently played audio (HH:MM:SS)
• playerTrackNb – Reports the track number of the currently played audio
• playerPlaybackInfo – Reports current player state (play|stop|pause)
• playerRepeat – Reports the Repeat Mode (one|all|off)
• playerShuffle – Reports the Shuffle Mode (on|off)
• playerTotalTracks – Reports the total number of tracks for playing

Player list (menu) related readings:


• listItem_XXX – Reports the content of the device's current directory. Prefix 'c_' indicates a container (directory), prefix 'i_' an item (audio file/stream). Number of lines can be limited by the attribute 'maxPlayerLineItems' (default is 999).
• lvlX_ – Reports the hierarchical directory tree level.

Tuner related readings:


• listItem_XXX – Reports the stored presets.
• tunerBand – Reports the tuner band (DAB|FM)


• DAB
• tunerDABStation – (DAB|DAB+), Channel: (value), Ensemble: (name)
• tunerDABSignal – (Frequency), (Signal quality), (Bitrate), (Mono|Stereo)
• tunerInfo1 – DAB program service
• tunerPreset – (Preset number DAB Frequency Station) or '–' if not stored as preset
• tunerStation – DAB Station Name


• FM
• tunerFrequency – FM frequency
• tunerInfo1 – FM station name
• tunerInfo2_A – Additional RDS information A
• tunerInfo2_A – Additional RDS information B
• tunerPreset – (Preset number FM Frequency Station) or '–' if not stored as preset

Timer related readings:


• timer – current timer status (on|off)
• timerRepeat – timer repeat mode (once|every)
• timerStartTime – timer start time HH:MM
• timerVolume – timer volume [<VOL_MIN>...<VOL_MAX>]

ZM_Monitor

[EN DE]

Define

define <name> ZM_Monitor <ZM-Monitor ID>

This is usually called by autocreate and triggered by the ZoneMinder IODevice.

Set

• alarmState
  Puts a monitor into alarm state or out of alarm state via the ZoneMinder trigger port. Can also take one or both of cause="xxx" notes="xxx" parameters
• monitorFunction
  Sets the operating mode of a Monitor in ZoneMinder via the ZoneMinder API.
• motionDetectionEnabled
  Enables or disables monitor detection of a monitor via ZoneMinder API.
• text
  Allows you to set a text for a Timestamp's %Q portion in ZoneMinder via the ZoneMinder trigger port.

Attributes

• showLiveStreamInDetail
  If set to 1, a live-stream of the current monitor will be shown on top of the FHEMWEB detail page.

Readings

• alert
  The alert state.
• eventImageUrl
  Link to the first image of the latest event recording, based on the ZM-Host parameter used in the device definition.
• eventStreamUrl
  Link to the latest event recording, based on the ZM-Host parameter used in the device definition.
• lastEventId
  ID of the latest event in ZoneMinder.
• lastEventTimestamp
  Timestamp of the latest event from ZoneMinder.
• monitorFunction
  Current operation mode of the monitor.
• motionDetectionEnabled
  Equals the 'enabled' setting in ZoneMinder. Allows you to put the monitor into a more passive state (according to ZoneMinder documentation).
• pubEventImageUrl
  Link to the first image of the latest event recording, based on the publicAddress attribute used in the ZoneMinder device.
• pubEventStreamUrl
  Link to the latest event recording, based on the publicAddress attribute used in the ZoneMinder device.
• pubImageUrl
  Link to the current live image, based on the publicAddress attribute used in the ZoneMinder device.
• pubStreamUrlLink to the live-stream, based on the publicAddress attribute used in the ZoneMinder device.
  
• streamReplayBuffer
  Taken from the ZoneMinder configuration. Used for the buffer parameter of stream URLs.
• streamUrl
  Link to the live-stream, based on the ZM-Host parameter used in the device definition.

ZWCUL

[EN DE]

This module serves a CUL in ZWave mode (starting from culfw version 1.66), which is attached via USB or TCP/IP, and enables the use of ZWave devices (see also the ZWave module).

Define
define <name> ZWCUL <device> <homeId> <ctrlId>

Since the DevIo module is used to open the device, you can also use devices connected via TCP/IP. See this paragraph on device naming details.
Example:
define ZWCUL_1 ZWCUL /dev/cu.usbmodemfa141@9600 12345678 01

If the homeId is set to 00000000, then culfw will enter monitor mode, i.e. no acks for received messages will be sent, and no homeId filtering will be done.

Set
• reopen
  First close and then open the device. Used for debugging purposes.
• led [on|off|blink]
  Set the LED on the CUL.
• raw
  send a raw string to culfw
• addNode [on|onSec|off]
  Activate (or deactivate) inclusion mode. The CUL will switch to dataRate 9600 until terminating this mode with off, or a node is included. If onSec is specified, the ZWCUL networkKey ist set, and the device supports the SECURITY class, then a secure inclusion is attempted.
• addNodeId <decimalNodeId>
  Activate inclusion mode, and assign decimalNodeId to the next node. To deactivate this mode, use addNode off. Note: addNode won't work for a FHEM2FHEM:RAW attached ZWCUL, use addNodeId instead
• removeNode [onNw|on|off]
  Activate (or deactivate) exclusion mode. Like with addNode, the CUL will switch temporarily to dataRate 9600, potentially missing some packets sent on higher dataRates. Note: the corresponding fhem device have to be deleted manually.

Get
• homeId
  return the homeId and the ctrlId of the controller.
• nodeInfo
  return node specific information. Needed by developers only.
• raw
  Send raw data to the controller.

Attributes
• dataRate [40k|100k|9600]
  specify the data rate.
• dummy
• do_not_notify
• model
• disable
• networkKey
• intruderMode
  In monitor mode (see above) events are not dispatched to the ZWave module per default. Setting this attribute will allow to get decoded messages, and to send commands to devices not included by this controller.
• verbose
  If the verbose attribute of this device (not global!) is set to 5 or higher, then detailed logging of the RF message will be done.

Generated events: TODO

ZWDongle

[EN DE]

This module serves a ZWave dongle, which is attached via USB or TCP/IP, and enables the use of ZWave devices (see also the ZWave module). It was tested wit a Goodway WD6001, but since the protocol is standardized, it should work with other devices too. A notable exception is the USB device from Merten.

Define
define <name> ZWDongle <device>

Upon initial connection the module will get the homeId of the attached device. Since the DevIo module is used to open the device, you can also use devices connected via TCP/IP. See this paragraph on device naming details.
Example:
define zwdongle_1 ZWDongle /dev/cu.PL2303-000014FA@115200


Set
• addNode on|onNw|onSec|onNwSec|off
  Activate (or deactivate) inclusion mode. The controller (i.e. the dongle) will accept inclusion (i.e. pairing/learning) requests only while in this mode. After activating inclusion mode usually you have to press a switch three times within 1.5 seconds on the node to be included into the network of the controller. If autocreate is active, a fhem device will be created after inclusion. "on" activates standard inclusion. "onNw" activates network wide inclusion (only SDK 4.5-4.9, SDK 6.x and above).
  If onSec/onNwSec is specified, the ZWDongle networkKey ist set, and the device supports the SECURITY class, then a secure inclusion is attempted.
• backupCreate 16k|32k|64k|128k|256k
  read out the NVRAM of the ZWDongle, and store it in a file called <ZWDongle_Name>.bin in the modpath folder. Since the size of the NVRAM is currently unknown to FHEM, you have to specify the size. The ZWave.me ZME_UZB1 Stick seems to have 256k of NVRAM. Note: writing the file takes some time, usually about 10s for each 64k (and significantly longer on Windows), and FHEM is blocked during this time.
• backupRestore
  Restore the file created by backupCreate. Restoring the file takes about the same time as saving it, and FHEM is blocked during this time. Note / Important: this function is not yet tested for older devices using the MEMORY functions.
• clearStatistics
  clear network statistics.
• controllerChange on|stop|stopFailed
  Add a controller to the current network and transfer role as primary to it. Invoking controller is converted to secondary.
  stop: stop controllerChange
  stopFailed: stop controllerChange and report an error
• createNewPrimary on|stop|stopFailed
  Add a controller to the current network as a replacement for an old primary. Command can be invoked only by a secondary configured as basic SUC
  stop: stop createNewPrimary
  stopFailed: stop createNewPrimary and report an error
• createNode <device>
  createNodeSec <device>
  Request the class information for the specified node, and create a FHEM device upon reception of the answer. Used to create FHEM devices for nodes included with another software or if the fhem.cfg got lost. For the node id see the get nodeList command below. Note: the node must be "alive", i.e. for battery based devices you have to press the "wakeup" button 1-2 seconds before entering this command in FHEM.
  <device> is either device name or decimal nodeId.
  createNodeSec assumes a secure inclusion, see the comments for "addNode onSec" for details.
• factoryReset yes
  Reset controller to default state. Erase all node and routing infos, assign a new random homeId. To control a device it must be re-included and re-configured.
  !Use this with care AND only if You know what You do!
  Note: the corresponding FHEM devices have to be deleted manually.
• learnMode on|onNw|disable
  Add or remove controller to/from an other network. Assign a homeId, nodeId and receive/store nodeList and routing infos.
• removeFailedNode <device>
  Remove non-responding node -that must be on the failed node list- from the routing table in controller. Instead, always use removeNode if possible. Note: the corresponding FHEM device have to be deleted manually.
  <device> is either device name or decimal nodeId.
• removeNode onNw|on|off
  Activate (or deactivate) exclusion mode. "on" activates standard exclusion. "onNw" activates network wide exclusion (only SDK 4.5-4.9, SDK 6.x and above). Note: the corresponding FHEM device have to be deleted manually.
• reopen
  First close and then open the device. Used for debugging purposes.
• replaceFailedNode <device>
  Replace a non-responding node with a new one. The non-responding node must be on the failed node list.
  <device> is either device name or decimal nodeId.
• routeFor <device> <hop1> <hop2> <hop3> <hop4> <speed>
  set priority routing for <device>. <device> and <hopN> are either device name or decimal nodeId or 0 for unused.
  <speed>: 1=9,6kbps; 2=40kbps; 3=100kbps
• sendNIF <device>
  Send NIF to the specified <device>. <device> is either device name or decimal nodeId.
• sucNodeId <decimal nodeId> <sucState> <capabilities>
  Configure a controller node to be a SUC/SIS or not.
  <nodeId>: decimal nodeId to be SUC/SIS
  <sucState>: 0 = deactivate; 1 = activate
  <capabilities>: 0 = basic SUC; 1 = SIS
• sucRequestUpdate <decimal nodeId of SUC/SIS>
  Request network updates from SUC/SIS. Primary do not need it.
• sucSendNodeId <decimal nodeId>
  Send SUC/SIS nodeId to the specified decimal controller nodeId.

Get
• homeId
  return the six hex-digit homeId of the controller.
• backgroundRSSI
  query the measured RSSI on the Z-Wave network
• caps, ctrlCaps, version
  return different controller specific information. Needed by developers only.
• isFailedNode <device>
  return if a node is stored in the failed node list. <device> is either device name or decimal nodeId.
• neighborList [excludeDead] [onlyRep] <device>
  return neighborList of the <device>.
  <device> is either device name or decimal nodeId.
  With onlyRep the result will include only nodes with repeater functionality.
• nodeInfo <device>
  return node specific information. <device> is either device name or decimal nodeId.
• nodeList
  return the list of included nodenames or UNKNOWN_id (decimal id), if there is no corresponding device in FHEM. Can be used to recreate FHEM-nodes with the createNode command.
• random <N>
  request <N> random bytes from the controller.
• raw <hex>
  Send raw data <hex> to the controller. Developer only.
• routeFor <device>
  request priority routing for <device>. <device> is either device name or decimal nodeId.
• statistics
  return the current network statistics.
• sucNodeId
  return the currently registered decimal SUC nodeId.

Attributes
• dummy
• do_not_notify
• model
• disable
• helpSites
  Comma separated list of Help Sites to get device pictures from or to show a link to in the detailed window. Valid values are pepper and alliance.
• homeId
  Stores the homeId of the dongle. Is a workaround for some buggy dongles, wich sometimes report a wrong/nonexisten homeId (Forum #35126)
• networkKey
  Needed for secure inclusion, hex string with length of 32
• neighborListPos
  Used by the "Show neighbor map" function in the FHEMWEB ZWDongle detail screen to store the position of the box.
• neighborListFmt
  Used by the "Show neighbor map" function in the FHEMWEB ZWDongle detail screen. The value is a perl hash, specifiying the values for the keys txt, img and title. In the value each word is replaced by the corresponding Internal, Reading or Attribute of the device, if there is one to replace. Default is
  { txt=>"NAME", img=>"IMAGE", title=>"Time to ack: timeToAck" }
• showSetInState
  If the attribute is set to 1, and a user issues a set command to a ZWave device, then the state of the ZWave device will be changed to set_<cmd> first, and after the ACK from the device is received, to <cmd>. E.g.: Issuing the command on changes the state first to set_on, and after the device ack is received, to on. This is analoguos to the CUL_HM module. Default for this attribute is 0.
• setReadingOnAck
  If the attribute is set to 1, and a set command with an argument is issued to a ZWave device, then a reading with the same name will be updated upon reception of the corresponding ZWave ACK radio telegram.

Generated events:

General
• UNDEFINED ZWave_${type6}_$id ZWave $homeId $id $classes
• ZW_APPLICATION_UPDATE addDone $nodeId
• ZW_APPLICATION_UPDATE deleteDone $nodeId
• ZW_APPLICATION_UPDATE sudId $nodeId

addNode
• ZW_ADD_NODE_TO_NETWORK [learnReady|nodeFound|slave|controller| done|failed]

clearStatistics
• CLEAR_NETWORK_STATS ok

controllerChange
• ZW_CONTROLLER_CHANGE [learnReady|nodeFound|controller|done|failed]

createNewPrimary
• ZW_CREATE_NEW_PRIMARY [learnReady|nodeFound|controller|done|failed]

factoryReset
• ZW_SET_DEFAULT [done]

learnMode
• ZW_SET_LEARN_MODE [started|done|failed|deleted]

neighborUpdate
• ZW_REQUEST_NODE_NEIGHBOR_UPDATE [started|done|failed]

removeFailedNode
• ZW_REMOVE_FAILED_NODE_ID [failedNodeRemoveStarted|notPrimaryController|noCallbackFunction| failedNodeNotFound|failedNodeRemoveProcessBusy| failedNodeRemoveFail|nodeOk|nodeRemoved|nodeNotRemoved]

removeNode
• ZW_REMOVE_NODE_FROM_NETWORK [learnReady|nodeFound|slave|controller|done|failed]

replaceFailedNode
• ZW_REPLACE_FAILED_NODE [failedNodeRemoveStarted|notPrimaryController|noCallbackFunction| failedNodeNotFound|failedNodeRemoveProcessBusy| failedNodeRemoveFail|nodeOk|failedNodeReplace| failedNodeReplaceDone|failedNodeRemoveFailed]

routeFor
• ZW_SET_PRIORITY_ROUTE node $nodeId result $nr

sucNetworkUpdate
• ZW_REQUEST_NETWORK_UPDATE [started|selfOrNoSUC|done|abort|wait|diabled| overflow]

sucNodeId
• ZW_SET_SUC_NODE_ID [ok|failed|callbackSucceeded|callbackFailed]

sucRouteAdd
• ZW_ASSIGN_SUC_RETURN_ROUTE [started|alreadyActive|transmitOk| transmitNoAck|transmitFail|transmitNotIdle| transmitNoRoute]

sucRouteDel
• ZW_DELETE_SUC_RETURN_ROUTE [started|alreadyActive|transmitOk| transmitNoAck|transmitFail|transmitNotIdle| transmitNoRoute]

sucSendNodeId
• ZW_SEND_SUC_ID [started|alreadyActive|transmitOk| transmitNoAck|transmitFail|transmitNotIdle| transmitNoRoute]

ZWave

This module is used to control ZWave devices via FHEM, see www.z-wave.com for details for this device family. The full specification of ZWave command classes can be found here: https://www.silabs.com/wireless/z-wave/specification. This module is a client of the ZWDongle module, which is directly attached to the controller via USB or TCP/IP. To use the SECURITY features, the Crypt-Rijndael perl module is needed.

Define
define <name> ZWave <homeId> <id> [classes]

<homeId> is the homeId of the controller node, and id is the id of the slave node in the network of this controller.
classes is a hex-list of ZWave device classes. This argument is usually specified by autocreate when creating a device. If you wish to manually create a device, use the classes attribute instead, see below for details. Defining a ZWave device the first time is usually done by autocreate.
Example:
define lamp ZWave 00ce2074 9
attr lamp classes SWITCH_BINARY BASIC MANUFACTURER_SPECIFIC VERSION SWITCH_ALL ASSOCIATION METER CONFIGURATION ALARM


Note: the sets/gets/generated events of a given node depend on the classes supported by this node. If a node supports 3 classes, then the union of these sets/gets/events will be available for this node.
Commands for battery operated nodes will be queued internally, and sent when the node sends a message. Answers to get commands appear then as events, the corresponding readings will be updated.

Set

Notes:
• devices with on/off functionality support the set extensions.
• A set command does not automatically update the corresponding reading, you have to execute a get for this purpose. This can be automatically done via a notify, although this is not recommended in all cases.


All
• neighborUpdate
  Requests controller to update its routing table which is based on slave's neighbor list. The update may take significant time to complete. With the event "done" or "failed" ZWDongle will notify the end of the update process. To read node's neighbor list see neighborList get below.
• returnRouteAdd <decimal nodeId>
  Assign up to 4 static return routes to the routing/enhanced slave to allow direct communication to <decimal nodeId>. (experts only)
• returnRouteDel
  Delete all static return routes. (experts only)
• sucRouteAdd
  Inform the routing/enhanced slave of the presence of a SUC/SIS. Assign up to 4 static return routes to SUC/SIS.
• sucRouteDel
  Delete static return routes to SUC/SIS node.


Class ALARM
• alarmnotification <alarmType> (on|off)
  Enable (on) or disable (off) the sending of unsolicited reports for the alarm type <alarmType>. A list of supported alarm types of the device can be obtained with the alarmTypeSupported command. The name of the alarm type is case insensitive. Sending of an unsolicited notification only works for associated nodes, broadcasting is not allowed, so associations have to be set up. This command is specified in version 2.
• Note:
  The name of the class ALARM was renamed to NOTIFICATION in version 3 of the Zwave specification. Due to backward compatibility reasons the class will be always referenced as ALARM in FHEM, regardless of the version.


Class ASSOCIATION
• associationAdd groupId nodeId ...
  Add the specified list of nodeIds to the association group groupId.
  Note: upon creating a FHEM-device for the first time FHEM will automatically add the controller to the first association group of the node corresponding to the FHEM device, i.e it issues a "set name associationAdd 1 controllerNodeId"
• associationDel groupId nodeId ...
  Remove the specified list of nodeIds from the association group groupId.


Class BASIC
• basicValue value
  Send value (0-255) to this device. The interpretation is device dependent, e.g. for a SWITCH_BINARY device 0 is off and anything else is on.
• basicValue value
  Alias for basicValue, to make mapping from the incoming events easier.


Class BARRIER_OPERATOR
• barrierClose
  start closing the barrier.
• barrierOpen
  start opening the barrier.


Class BASIC_WINDOW_COVERING
• coveringClose
  Starts closing the window cover. Moving stops if blinds are fully closed or a coveringStop command was issued.
• coveringOpen
  Starts opening the window cover. Moving stops if blinds are fully open or a coveringStop command was issued.
• coveringStop
  Stop moving the window cover. Blinds are partially open (closed).


Class CLIMATE_CONTROL_SCHEDULE
• ccs [mon|tue|wed|thu|fri|sat|sun] HH:MM tempDiff HH:MM tempDiff ...
  set the climate control schedule for the given day.
  Up to 9 pairs of HH:MM tempDiff may be specified.
  HH:MM must occur in increasing order. tempDiff is relative to the setpoint temperature, and may be between -12 and 12, with one decimal point, measured in Kelvin (or Centigrade).
  If only a weekday is specified without any time and tempDiff, then the complete schedule for the specified day is removed and marked as unused.
• ccsOverride (no|temporary|permanent) (frost|energy|$tempOffset)
  set the override state
  no: switch the override off
  temporary: override the current schedule only
  permanent: override all schedules
  frost/energy: set override mode to frost protection or energy saving
  $tempOffset: the temperature setback (offset to setpoint) in 1/10 degrees range from -12.8 to 12.0, values will be limited to this range.


Class CLOCK
• clock
  set the clock to the current date/time (no argument required)


Class COLOR_CONTROL
• color colorComponent level colorComponent level ...
  Set the colorComponent(s) to level
  Up to 8 pairs of colorComponent level may be specified.
  colorComponent is a decimal value from 0 to 8:
  0 = warm white, 1 = cold white, 2 = red, 3 = green, 4 = blue, 5 = amber,6 = cyan, 7 = purple, 8 = indexed color
  level is specified with a value from 0 to 255.
• rgb
  Set the color of the device as a 6 digit RGB Value (RRGGBB), each color is specified with a value from 00 to ff.
• wcrgb
  Used for sending warm white, cold white, red, green and blue values to device. Values must be decimal (0 - 255) and separated by blanks.
  set <name> wcrgb 0 255 0 0 0 (setting full cold white)
  


Class CONFIGURATION
• configByte cfgAddress 8bitValue
  configWord cfgAddress 16bitValue
  configLong cfgAddress 32bitValue
  Send a configuration value for the parameter cfgAddress. cfgAddress and value are node specific.
  Note: if the model is set (see MANUFACTURER_SPECIFIC get), then more specific config commands are available.
• configDefault cfgAddress
  Reset the configuration parameter for the cfgAddress parameter to its default value. See the device documentation to determine this value.


Class DOOR_LOCK, V2
• doorLockOperation DOOR_LOCK_MODE
  Set the operation mode of the door lock.
  DOOR_LOCK_MODE:
  open = Door unsecured
  close = Door secured
  00 = Door unsecured
  01 = Door unsecured with timeout
  10 = Door unsecured for inside door handles
  11 = Door unsecured for inside door handles with timeout
  20 = Door unsecured for outside door handles
  21 = Door unsecured for outside door handles with timeout
  FF = Door secured
  Note: open/close can be used as an alias for 00/FF.
• doorLockConfiguration operationType outsidehandles insidehandles timeoutSeconds
  Set the configuration for the door lock.
  operationType: [constant|timed]
  outsidehandle/insidehandle: 4-bit binary field for handle 1-4, bit=0:handle disabled, bit=1:handle enabled, highest bit is for handle 4, lowest bit for handle 1. Example 0110 0001 = outside handles 3 and 2 are active, inside handle 1 is active
  timeoutSeconds: time out for timed operation (in seconds) [1-15239].


Class FIRMWARE_UPDATE_META_DATA
• fwUpdate <decimal Target> <filename>
  updates specified firmware target with firmware given in filename. The file is searched within the in the modpath/FHEM/firmware/ folder. The supported targets can be requested with the get fwMetaData command. FIRMWARE_UPDATE_MD class version > 3 untested, feedback welcome. FIRMWARE_UPDATE_MD class version > 4 not supported feedback welcome.


Class INDICATOR
• indicatorOn
  switch the indicator on
• indicatorOff
  switch the indicator off
• indicatorDim value
  takes values from 1 to 99. If the indicator does not support dimming, it is interpreted as on.


Class MANUFACTURER_PROPRIETARY
Fibaro FGR(M)-222 only:
• positionBlinds
  drive blinds to position %
• positionSlat
  drive slat to position %

D-Link DCH-Z510, Philio PSE02, Zipato Indoor Siren only:
switch alarm on with selected sound (to stop use: set <device> off)
• alarmEmergencyOn
• alarmFireOn
• alarmAmbulanceOn
• alarmPoliceOn
• alarmDoorchimeOn
• alarmBeepOn


Class METER
• meterReset
  Reset all accumulated meter values.
  Note: see meterSupported command and its output to detect if resetting the value is supported by the device.
  The command will reset ALL accumulated values, it is not possible to choose a single value.
• meterResetToValue type value
  Reset type (one of energy,gas,water,heating,cooling) to the value specified. Only supported by METER version 6.


Class MULTI_CHANNEL
• mcCreateAll
  Create a FHEM device for all channels. This command is executed after inclusion of a new device.


Class MULTI_CHANNEL_ASSOCIATION
• mcaAdd groupId node1 node2 ... 0 node1 endPoint1 node2 endPoint2 ...
  Add a list of node or node:endpoint associations. The latter can be used to create channels on remotes. E.g. to configure the button 1,2,... on the zwave.me remote, use:
  set remote mcaAdd 2 0 1 2
  set remote mcaAdd 3 0 1 3
  ....
  For each button a separate FHEM device will be generated.
• mcaDel groupId node1 node2 ... 0 node1 endPoint1 node2 endPoint2 ...
  delete node or node:endpoint associations. Special cases: just specifying the groupId will delete everything for this groupId. Specifying 0 for groupId will delete all associations.


Class NETWORK_SCHEDULE (SCHEDULE), V1
• schedule ID USER_ID YEAR-MONTH-DAY WDAY ACTIVE_ID DURATION_TYPE HOUR:MINUTE DURATION NUM_REPORTS CMD ... CMD
  Set a schedule for a user. Due to lack of documentation, details for some parameters are not available. Command Class is used together with class USER_CODE.
  
  ID: id of schedule, refer to maximum number of supported schedules reported by the scheduleSupported command.
  USER_ID: id of user, starting from 1 up to the number of supported users, refer also to the USER_CODE class description.
  YEAR-MONTH-DAY: start of schedule in the format yyyy-mm-dd.
  WDAY: weekday, 1=Monday, 7=Sunday.
  ACTIVE_ID: unknown parameter.
  DURATION_TYPE: unknown parameter.
  HOUR:MINUTE: start of schedule in the format hh:mm.
  DURATION: unknown parameter.
  NUM_REPORTS: number of reports to follow, must be 0.
  CMD: command(s) (as hexcode sequence) that the schedule executes, see report of scheduleSupported command for supported command class and mask. A list of space separated commands can be specified.
  
• scheduleRemove ID
  Remove the schedule with the id ID
• scheduleState ID STATE
  Set the STATE of the schedule with the id ID. Description for parameter STATE is not available.


Class NODE_NAMING
• name NAME
  Store NAME in the EEPROM. Note: only ASCII is supported.
• location LOCATION
  Store LOCATION in the EEPROM. Note: only ASCII is supported.


Class SOUND_SWITCH
• toneConfiguration VOLUME DEFAULTNR
  Configure the volume and the default tone. Volume 0 is off, 1..100 is interpreted as 1% to 100%, and 255 restores last volume, if the current is 0. If DEFAULTNR is 0, set only the volume.
• tonePlay TONENUMBER
  Play tone Number TONENUMBER.
• tonePlayDefault
  Play the default tone.
• toneStop
  Stop playing.


Class POWERLEVEL
• Class is only used in an installation or test situation
• powerlevel level timeout/s
  set powerlevel to level [0-9] for timeout/s [1-255].
  level 0=normal, level 1=-1dBm, .., level 9=-9dBm.
• powerlevelTest nodeId level frames
  send number of frames [1-65535] to nodeId with level [0-9].


Class PROTECTION
• protectionOff
  device is unprotected
• protectionOn
  device is protected
• protectionSeq
  device can be operated, if a certain sequence is keyed.
• protectionBytes LocalProtectionByte RFProtectionByte
  for commandclass PROTECTION V2 - see devicemanual for supported protectionmodes


Class SCENE_ACTIVATION
• sceneConfig
  activate settings for a specific scene. Parameters are: sceneId, dimmingDuration (0..255)


Class SCENE_ACTUATOR_CONF
• sceneConfig
  set configuration for a specific scene. Parameters are: sceneId, dimmingDuration, finalValue (0..255)


Class SCENE_CONTROLLER_CONF
• groupConfig
  set configuration for a specific scene. Parameters are: groupId, sceneId, dimmingDuration.


Class SCHEDULE_ENTRY_LOCK, V1, V2, V3
• scheduleEntryLockSet USER_ID ENABLED
  enables or disables schedules for a specified user ID (V1)
  
  USER_ID: id of user, starting from 1 up to the number of supported users, refer also to the USER_CODE class description.
  ENABLED: 0=disabled, 1=enabled
  
• scheduleEntryLockAllSet ENABLED
  enables or disables schedules for all users (V1)
  
  ENABLED: 0=disabled, 1=enabled
  
• scheduleEntryLockWeekDaySet ACTION USER_ID SCHEDULE_ID WEEKDAY STARTTIME ENDTIME
  erase or set a week day schedule for a specified user ID (V1)
  
  ACTION: 0=erase schedule slot, 1=modify the schedule slot for the user
  USER_ID: id of user, starting from 1 up to the number of supported users, refer also to the USER_CODE class description.
  SCHEDULE_ID: schedule slot id (from 1 up to number of supported schedule slots)
  WEEKDAY: day of week, choose one of: "sun","mon","tue","wed","thu","fri","sat"
  STARTTIME: time of schedule start, in the format HH:MM (leading 0 is mandatory)
  ENDTIME: time of schedule end in the format HH:MM (leading 0 is mandatory)
  
• scheduleEntryLockYearDaySet ACTION USER_ID SCHEDULE_ID STARTDATE STARTTIME ENDDATE ENDTIME
  erase or set a year day schedule for a specified user ID (V1)
  
  ACTION: 0=erase schedule slot, 1=modify the schedule slot for the user
  USER_ID: id of user, starting from 1 up to the number of supported users, refer also to the USER_CODE class description.
  SCHEDULE_ID: schedule slot id (from 1 up to number of supported schedule slots)
  STARTDATE: date of schedule start in the format YYYY-MM-DD
  STARTTIME: time of schedule start in the format HH:MM (leading 0 is mandatory)
  ENDDATE: date of schedule end in the format YYYY-MM-DD
  ENDTIME: time of schedule end in the format HH:MM (leading 0 is mandatory)
  
• scheduleEntryLockTimeOffsetSet TZO DST
  set the TZO and DST (V2)
  
  TZO: current local time zone offset in the format (+|-)HH:MM (sign and leading 0 is mandatory)
  DST: daylight saving time offset in the format (+|-)[[m]m]m (sign is mandatory, minutes: 0 to 127, 1-3 digits)
  
• scheduleEntryLockDailyRepeatingSet ACTION USER_ID SCHEDULE_ID WEEKDAYS STARTTIME DURATION
  set a daily repeating schedule for the specified user (V3)
  
  ACTION: 0=erase schedule slot, 1=modify the schedule slot for the user
  USER_ID: id of user, starting from 1 up to the number of supported users, refer also to the USER_CODE class description.
  SCHEDULE_ID: schedule slot id (from 1 up to number of supported schedule slots)
  WEEKDAYS: concatenated string of weekdays (choose from: "sun","mon","tue","wed","thu","fri","sat"); e.g. "montuewedfri" or "satsun", unused days can be specified as "..."
  STARTTIME: time of schedule start in the format HH:MM (leading 0 is mandatory)
  DURATION: duration of schedule in the format HH:MM (leading 0 is mandatory)
  


Class SWITCH_ALL
• swaIncludeNone
  the device does not react to swaOn and swaOff commands
• swaIncludeOff
  the device reacts to the swaOff command but does not react to the swaOn command
• swaIncludeOn
  the device reacts to the swaOn command but does not react to the swaOff command
• swaIncludeOnOff
  the device reacts to the swaOn and swaOff commands
• swaOn
  sends the all on command to the device
• swaOff
  sends the all off command to the device.


Class SWITCH_BINARY
• on
  switch the device on
• off
  switch the device off
• on-for-timer seconds
  off-for-timer seconds
  For version 2 of this class the ZWave implementation of this command is used, else the SetExtensions emulation with a delayed on/off. The native implementation has a second resolution for up to 127 seconds, and a minute resolution up to 7620 seconds (i.e. 127 minutes). The specified value will be rounded to the required resolution and/or limited to the maximum allowed value. If the value has to be changed, then this will be logged in the logfile.
  If the SetExtensions emulation without such limitations is preferred, then the vclasses attribute should be modified.


Class SWITCH_MULTILEVEL
• on, off
  the same as for SWITCH_BINARY.
• dim <value>
  dim/jump to the requested <value> (0..99)
  Note: ZWave defines the range for <value> to 0..99, with 99 representing "on".
• dimUpDown (UP|DOWN) (IGNORE|USE) <startlevel>
  starts dimming up or down, starting at a <startlevel> if USE is specified. If IGNORE is specified, the startlevel will be ignored.
  Note: All keywords must be specified, even in the case of IGNORE. The device SHOULD respect the <startlevel>, however, most devices will ignore the specified startlevel.
• dimUpDownIncDecWithDuration (UP|DOWN|NOMOTION) (IGNORE|USE) <startlevel> <duration> (INC|DEC|NOINCDEC) <stepsize>
  similar to dimUpDownWithDuration, adding support for secondary switch types (e.g. shutter and blind control) (class version V3).
  The dimming/movement of the primary switch type can be inhibited by specifying NOMOTION, so that only the secondary switch type is used. The secondary switch type is controlled by the keywords INC, DEC and NOINCDEC, where NOINCDEC will inhibit the dimming/movement of the secondary switch. If NOINCDEC is used, the <stepsize> must be specified as 0.
  <stepsize> can be 0..99 or 255.
  Note: <stepsize> will be interpreted by the device, most likely to represent a time or position, e.g. to turn blinds.
  <duration> can be 0..7620 seconds (127 minutes). Up to a duration of 127 seconds, the (internal) resolution is 1 second, for longer durations the resolution is 60 seconds.
  Note: A device SHOULD respect the given duration, however, most devices will use their internal default duration and ignore the specified duration.
• dimUpDownWithDuration (up|down) (ignore|use) <startlevel> <duration>
  similar to dimUpDown, adding a <duration> time for the transition (V2)
  <duration> can be 0..7620 seconds (127 minutes). Up to a duration of 127 seconds, the (internal) resolution is 1 second, for longer durations the resolution is 60 seconds.
  Note: A device SHOULD respect the given duration, however, most devices will use their internal default duration and ignore the specified duration.
• dimWithDuration <value> <duration>
  dim to the requested <value> (0..99) in <duration> seconds. (V2)
  <duration> can be 0..7620 seconds (127 minutes). Up to a duration of 127 seconds, the (internal) resolution is 1 second, for longer durations the resolution is 60 seconds.
  Note: A device SHOULD respect the given duration, however, most devices will use their internal default duration and ignore the specified duration.
• stop
  stop dimming/operation


Class THERMOSTAT_FAN_MODE
• fanAutoLow
• fanLow
• fanAutoMedium
• fanMedium
• fanAutoHigh
• fanHigh
  set the fan mode.


Class THERMOSTAT_MODE
• tmOff
• tmHeating
• tmCooling
• tmAuto
• tmFan
• V2:
• tmEnergySaveHeating
• V3:
• tmFullPower
• tmManual
  set the thermostat mode.
• thermostatMode {Off|Heating|Cooling|...}
  just like the above, but in combination with the setReadingOnAck ZWDongle attribute it produces an easier way to check the current state.


Class THERMOSTAT_SETPOINT
• setpointHeating value
  set the thermostat to heat to the given value. The value is an integer in celsius.
  See thermostatSetpointSet for a more enhanced method.
• setpointCooling value
  set the thermostat to cool down to the given value. The value is an integer in celsius.
  See thermostatSetpointSet for a more enhanced method.
• thermostatSetpointSet TEMP [SCALE [TYPE [PREC [SIZE]]]]
  set the setpoint of the thermostat to the given value.
  
  TEMP: setpoint temperature value, by default the value is used with 1 decimal, see PREC
  SCALE: (optional) scale of temperature; [cC]=celsius, [fF]=fahrenheit, defaults to celsius
  TYPE: (optional) setpoint type; [1, 15], defaults to 1=heating
  
  1=heating, 2=cooling, 7=furnance, 8=dryAir, 9=moistAir, 10=autoChangeover, 11=energySaveHeating, 12=energySaveCooling, 13=awayHeating, 14=awayCooling, 15=fullPower
  PREC: (optional) number of decimals to be used, [1-7], defaults Note: optional parameters can be ommitted. To specify an optional parameter, ALL parameters in front of this parameter need to be also specified!
  Note: the number of decimals (defined by PREC) and the number of bytes (defined by SIZE) used for the setpoint influence the usable range for the temperature. Some devices do not support all possible values/combinations for PREC/SIZE.
  
  1 byte: 0 decimals [-128, 127], 1 decimal [-12.8, 12.7], ...
  2 byte: 0 decimals [-32768, 32767], 1 decimal [-3276.8, 3276.7], ...
  4 byte: 0 decimals [-2147483648, 2147483647], ...
  
• desired-temp value
  same as thermostatSetpointSet, used to make life easier for helper-modules


Class TIME, V2
• timeOffset TZO DST_Offset DST_START DST_END
  Set the time offset for the internal clock of the device.
  TZO: Offset of time zone to UTC in format [+|-]hh:mm.
  DST_OFFSET: Offset for daylight saving time (DST) in minutes in the format [+|-]mm.
  DST_START / DST_END: Start and end of daylight saving time in the format MM-DD_HH:00.
  Note: Sign for both offsets must be specified!
  Note: Minutes for DST_START and DST_END must be specified as "00"!


Class TIME_PARAMETERS, V1
• timeParametersGet
  The device request time parameters. Right now the user should define a notify with a "set timeParameters" command.
• timeParameters DATE TIME
  Set the time (UTC) to the internal clock of the device.
  DATE: Date in format YYYY-MM-DD.
  TIME: Time (UTC) in the format hh:mm:ss.
  Note: Time zone offset to UTC must be set with command class TIME.


Class USER_CODE
• userCode id status code
  set code and status for the id n. n ist starting at 1, status is 0 for available (deleted) and 1 for set (occupied). code is a hexadecimal string.


Class WAKE_UP
• wakeupInterval value nodeId
  Set the wakeup interval of battery operated devices to the given value in seconds. Upon wakeup the device sends a wakeup notification to nodeId.
• wakeupNoMoreInformation
  put a battery driven device into sleep mode.

Get


All
• neighborList
  returns the list of neighbors. Provides insights to actual network topology. List includes dead links and non-routing neighbors. Since this information is stored in the dongle, the information will be returned directly even for WAKE_UP devices.


Class ALARM
• alarm <alarmId>
  return the value for the (decimal) alarmId. The value is device specific. This command is specified in version 1 and should only be used with old devices that only support version 1.
• alarmWithType <alarmType>
  return the event for the specified alarm type. This command is specified in version 2.
• alarmWithTypeEvent <alarmType> <eventnumber>
  return the event details for the specified alarm type and eventnumber. This command is specified in version 3. The eventnumber is specific for each alarm type, a list of the supported eventnumbers can be obtained by the "alarmEventSupported" command, refer also to the documentation of the device.
• alarmTypeSupported
  Returns a list of the supported alarm types of the device which are used as parameters in the "alarmWithType" and "alarmWithTypeEvent" commands. This command is specified in version 2.
• alarmEventSupported <alarmType>
  Returns a list of the supported events for the specified alarm type. The number of the events can be used as parameter in the "alarmWithTypeEvent" command. This command is specified in version 3.


Class ASSOCIATION
• association groupId
  return the list of nodeIds in the association group groupId in the form:
  assocGroup_X:Max Y, Nodes id,id...
• associationGroups
  return the number of association groups
  
• associationAll
  request association info for all possible groups.


Class ASSOCIATION_GRP_INFO
• associationGroupName groupId
  return the name of association groups
• associationGroupCmdList groupId
  return Command Classes and Commands that will be sent to associated devices in this group
  


Class BARRIER_OPERATOR
• barrierState
  request state of the barrier.


Class BASIC
• basicStatus
  return the status of the node as basicReport:XY. The value (XY) depends on the node, e.g. a SWITCH_BINARY device reports 00 for off and FF (255) for on. Devices with version 2 (or greater) can return two additional values, the 'target value' and 'duration'. The 'duration' is reported in seconds, as "unknown duration" (value 0xFE = 253) or as "255 (reserved value)" (value 0xFF = 255).


Class BATTERY
• battery
  return the state and charge of the battery, see below the events


CLASS DOOR_LOCK_LOGGING, V1 (deprecated)
• doorLockLoggingRecordsSupported
  Gives back the number of records that can be stored by the device.
• doorLockLoggingRecord n
  Requests and reports the logging record number n.
  You will get a reading with the requested record number, the record status, the event type, user identifier, user's code length and the timestamp of the event in the form of yyyy-mm-dd hh:mm:ss. Although the request does report the user code, the user typed in, it is dropped for security reasons, so it does not get logged in clear text.
  If the report could not get parsed correctly, it does report the raw message.
  The event types can be looked up in the "Software Design Specification - Z-Wave Application Command Class Specification" at page 150 from SIGMA DESIGNS in the version of 2017-07-10.


Class CLIMATE_CONTROL_SCHEDULE
• ccsOverride
  request the climate control schedule override report
• ccs [mon|tue|wed|thu|fri|sat|sun]
  request the climate control schedule for the given day.
• ccsAll
  request the climate control schedule for all days. (runs in background)


Class CLOCK
• clock
  request the clock data


Class COLOR_CONTROL
• ccCapability
  return capabilities.
• ccStatus channelId
  return status of channel ChannelId.


Class CONFIGURATION
• config cfgAddress
  return the value of the configuration parameter cfgAddress. The value is device specific.
  Note: if the model is set (see MANUFACTURER_SPECIFIC get), then more specific config commands are available.
• configAll
  If the model of a device is set, and configuration descriptions are available from the database for this device, then request the value of all known configuration parameters.


Class DOOR_LOCK, V2
• doorLockConfiguration
  Request the configuration report from the door lock.
• doorLockOperation
  Request the operconfiguration report from the door lock.


Class FIRMWARE_UPDATE_META_DATA
• fwMetaData
  Interviews the device about the firmware update capabilities. Generates the reading fwMd which holdes, dependent on the classversion the data about the manufacturer ids, the firmware ids and check sum of the upgradeable targets. More over it holdes the informationif the device is upgradeable und the maximum paylod of a data packed.


Class HRV_STATUS
• hrvStatus
  report the current status (temperature, etc.)
• hrvStatusSupported
  report the supported status fields as a bitfield.


Class INDICATOR
• indicatorStatus
  return the indicator status of the node, as indState:on, indState:off or indState:dim value.


Class MANUFACTURER_PROPRIETARY
• position
  Fibaro FGRM-222 only: return the blinds position and slat angle.


Class MANUFACTURER_SPECIFIC
• model
  return the manufacturer specific id (16bit), the product type (16bit) and the product specific id (16bit).
  Note: if the id combination is found in the user_, fhem_ or openzwave files, more descriptive config commands and help for these commands is available.


Class METER
• meter [scale [export|import]]
  return the meter report for the requested scale.
  Note: protocol V1 does not support the scale parameter, the parameter will be ignored and the default scale will be returned.
  For protocol V2 and higher scale can be specified as integer or text, see the output ot the meterSupported command.
  If the scale parameter is omitted, the default unit will be reported. export/import is only valid for protocol V4 or higher.
• meterSupported
  request the type of the meter, the supported scales and the capability to reset the accumulated value.
  Note: The output contains the decimal numbers of the supported scales that can be used as parameter for the meter command.


Class MULTI_CHANNEL
• mcEndpoints
  return the list of endpoints available, e.g.:
  mcEndpoints: total 2, identical
• mcCapability chid
  return the classes supported by the endpoint/channel chid. If the channel does not exist, create a FHEM node for it. Example:
  mcCapability_02:SWITCH_BINARY
  Note: This is the best way to create the secondary nodes of a MULTI_CHANNEL device. The device is only created for channel 2 or greater.


Class MULTI_CHANNEL_ASSOCIATION
• mca groupid
  return the associations for the groupid. for the syntax of the returned data see the mcaAdd command above.
• mcaAll
  request association info for all possible groupids.


Class NETWORK_SCHEDULE (SCHEDULE), V1
• scheduleSupported
  Request the supported features, e.g. number of supported schedules. Due to the lack of documentation, details for some fields in the report are not available.
• schedule ID
  Request the details for the schedule with the id ID. Due to the lack of documentation, details for some fields in the report are not available.
• scheduleState
  Request the details for the schedule state. Due to the lack of documentation, details for some fields in the report are not available.


Class NODE_NAMING
• name
  Get the name from the EEPROM. Note: only ASCII is supported.
• location
  Get the location from the EEPROM. Note: only ASCII is supported.


Class SOUND_SWITCH
• toneConfiguration
  Request the current configuration.
• toneNumbers
  Request the number of tones supported.
• tonePlay
  Request the tone number being played.


Class POWERLEVEL
• powerlevel
  Get the current powerlevel and remaining time in this level.
• powerlevelTest
  Get the result of last powerlevelTest.


Class PROTECTION
• protection
  returns the protection state. It can be on, off or seq.


Class SCENE_ACTUATOR_CONF
• sceneConfig
  returns the settings for a given scene. Parameter is sceneId


Class SCENE_CONTROLLER_CONF
• groupConfig
  returns the settings for a given group. Parameter is groupId


Class SCHEDULE_ENTRY_LOCK, V1, V2, V3
• scheduleEntryLockTypeSupported
  returns the number of available slots for week day and year day schedules (V1), in V3 the number of available slots for the daily repeating schedule is reported additionally
• scheduleEntryLockWeekDay USER_ID SCHEDULE_ID
  returns the specified week day schedule for the specified user (day of week, start time, end time) (V1)
  
  USER_ID: id of user, starting from 1 up to the number of supported users, refer also to the USER_CODE class description.
  SCHEDULE_ID: schedule slot id (from 1 up to number of supported schedule slots)
  
• scheduleEntryLockYearDay USER_ID SCHEDULE_ID
  returns the specified year day schedule for the specified user (start date, start time, end date, end time) (V1)
  
  USER_ID: id of user, starting from 1 up to the number of supported users, refer also to the USER_CODE class description.
  SCHEDULE_ID: schedule slot id (from 1 up to number of supported schedule slots)
  
• scheduleEntryLockDailyRepeating USER_ID SCHEDULE_ID
  returns the specified daily schedule for the specified user (weekdays, start date, duration) (V3)
  
  USER_ID: id of user, starting from 1 up to the number of supported users, refer also to the USER_CODE class description.
  SCHEDULE_ID: schedule slot id (from 1 up to number of supported schedule slots)
  
• scheduleEntryLockTimeOffset
  returns the time zone offset TZO and the daylight saving time offset (V2)


Class SECURITY
• secSupportedReport
  (internaly used to) request the command classes that are supported with SECURITY
• Notes:
  This class needs the installation of the perl module Crypt::Rijndael and a defined networkkey in the attributes of the ZWDongle device
  Currently a secure inclusion can only be started from the command input with "set <ZWDongle_device_name> addNode [onSec|onNwSec]"
  These commands are only described here for completeness of the documentation, but are not intended for manual usage. These commands will be removed from the interface in future version.


Class SENSOR_ALARM
• alarm alarmType
  return the nodes alarm status of the requested alarmType. 00 = GENERIC, 01 = SMOKE, 02 = CO, 03 = CO2, 04 = HEAT, 05 = WATER, 255 = returns the nodes first supported alarm type.


Class SENSOR_BINARY
• sbStatus
  return the status of the node.


Class SENSOR_MULTILEVEL
• smStatus
  request data from the node (temperature/humidity/etc)


Class SWITCH_ALL
• swaInclude
  return the switch-all mode of the node.


Class SWITCH_BINARY
• swbStatus
  return the status of the node, as state:on or state:off.


Class SWITCH_MULTILEVEL
• swmStatus
  return the status of the node, as state:on, state:off or state:dim value.
• swmSupported
  return the supported switch types (class version 3)


Class THERMOSTAT_FAN_MODE
• fanMode
  request the mode


Class THERMOSTAT_FAN_STATE
• fanMode
  request the state


Class THERMOSTAT_MODE
• thermostatMode
  request the mode


Class THERMOSTAT_OPERATING_STATE
• thermostatOperatingState
  request the operating state


Class THERMOSTAT_SETPOINT
• setpoint [TYPE]
  request the setpoint
  TYPE: (optional) setpoint type; [1, 15], defaults to 1=heating
  
  1=heating, 2=cooling, 7=furnance, 8=dryAir, 9=moistAir, 10=autoChangeover, 11=energySaveHeating, 12=energySaveCooling, 13=awayHeating, 14=awayCooling, 15=fullPower
• thermostatSetpointSupported
  requests the list of supported setpoint types


Class TIME, V2
• time
  Request the (local) time from the internal clock of the device.
• date
  Request the (local) date from the internal clock of the device.
• timeOffset
  Request the report for the time offset and DST settings from the internal clock of the device.


Class TIME_PARAMETERS, V1
• time
  Request the date and time (UTC) from the internal clock of the device.


Class USER_CODE
• userCode n
  request status and code for the id n


Class VERSION
• version
  return the version information of this node in the form:
  Lib A Prot x.y App a.b
• versionClass classId or className
  return the supported command version for the requested class
• versionClassAll
  executes "get devicename versionClass class" for each class from the classes attribute in the background without generating events, and sets the vclasses attribute at the end.


Class WAKE_UP
• wakeupInterval
  return the wakeup interval in seconds, in the form
  wakeupReport:interval seconds target id
• wakeupIntervalCapabilities (V2 only)
  return the wake up interval capabilities in seconds, in the form
  wakeupIntervalCapabilitiesReport:min seconds max seconds default seconds step seconds


Class ZWAVEPLUS_INFO
• zwavePlusInfo
  request the zwavePlusInfo

Attributes
• IODev
• WNMI_delay
  This attribute sets the time delay between the last message sent to an WakeUp device and the sending of the WNMI Message (WakeUpNoMoreInformation) that will set the device to sleep mode. Value is in seconds, subseconds my be specified. Values outside of 0.2-5.0 are probably harmful.
• classes
  This attribute is needed by the ZWave module, as the list of the possible set/get commands depends on it. It contains a space separated list of class names (capital letters).
• disable
• disabledForIntervals
• dummy
• do_not_notify
• dummy
• eventForRaw
  Generate an an additional event for the RAW message. Can be used if someone fears that critical notifies won't work, if FHEM changes the event text after an update.
• extendedAlarmReadings
  Some devices support more than one alarm type, this attribute selects which type of reading is used for the reports of the ALARM (or NOTIFICATION) class:
  A value of "0" selects a combined, single reading ("alarm") for all alarm types of the device. Subsequent reports of different alarm types will overwrite each other. This is the default setting and the former behavior.
  A value of "1" selects separate alarm readings for each alarm type of the device. The readings are named "alarm_<alarmtype>. This can also be selected if only one alarmtype is supported by the device. This reading also contains the status of the alarm notification. For compatibility reasons this is currently not supported with the combined reading.
  A value of "2" selects both of the above and creates the combined and the seperate readings at the same time, this should only be used if really needed as duplicate events are generated.
• generateRouteInfoEvents
  if set (to 1) a timeToCb event with additional information regarding the controller to device communication is generated, after sending data to the device.
  Notes:
  • A controller with SDK 6.60 or higher is required. (tested with UZB1/Razberry firmware 5.27)
  • Additional Information in Silicon Lab documents: "Appl. Programmers Guide" and "Z-Wave Network Installation and maintenance Procedures User Guide"
  • ReadingFnAttributes are not supported for this event.
• ignore
• ignoreDupMsg
  Experimental: if set (to 1), ignore duplicate wakeup messages, or multiple responses to a single get due to missing lowlevel ACK.
• neighborListPos
• noExplorerFrames
  turn off the use of Explorer Frames
• noWakeupForApplicationUpdate
  some devices (notable the Aeotec Multisensor 6) are only awake after an APPLICATION UPDATE telegram for a very short time. If this attribute is set (recommended for the Aeotec Multisensor 6), the WakeUp-Stack is not processed after receiving such a message.
• noUnits
  the meter class generates the reading as "value unit". If this attribute is set to 1, the unit is not part of the reading.
• readingFnAttributes
• secure_classes
  This attribute is the result of the "set DEVICE secSupportedReport" command. It contains a space seperated list of the the command classes that are supported with SECURITY.
• setExtensionsEvent
  If set, the event will contain the command implemented by SetExtensions (e.g. on-for-timer 10), else the executed command (e.g. on).


• setList
  Some devices interpret SENSOR_MULTILEVEL events, e.g. to react to an external temperature sensor. To enable FHEM to send such messages, specify the list of the desired readings, comma separated, with an sml_ prefix. Example:
  attr DEV setList sml_temperature
  set DEV sml_temperature -12.2 C
  The list of available scales can be retreived by specifying ? as scale. If no scale is specified, the first one from this list is used.


• showtime
• vclasses
  This is the result of the "get DEVICE versionClassAll" command, and contains the version information for each of the supported classes.
• useCRC16
  Experimental: if a device supports CRC_16_ENCAP, then add CRC16 to the command. Note: this is not available to SECURITY ENABLED devices, as security has its own CRC.
• useMultiCmd
  Experimental: if a device supports MULTI_CMD and WAKE_UP, then pack multiple get messages on the SendStack into a single MULTI_CMD to save radio transmissions.
• zwaveRoute
  space separated list of (ZWave) device names. They will be used in the given order to route messages from the controller to this device. Specify them in the order from the controller to the device. Do not specify the controller and the device itself, only the routers inbetween. Used only if the IODev is a ZWCUL device.

Generated events:

neighborUpdate
• ZW_REQUEST_NODE_NEIGHBOR_UPDATE [started|done|failed]

returnRouteAdd
• ZW_ASSIGN_RETURN_ROUTE [started|alreadyActive|transmitOk| transmitNoAck|transmitFail|transmitNotIdle| transmitNoRoute]

returnRouteDel
• ZW_DELETE_RETURN_ROUTE [started|alreadyActive|transmitOk| transmitNoAck|transmitFail|transmitNotIdle| transmitNoRoute]

sucRouteAdd
• ZW_ASSIGN_SUC_RETURN_ROUTE [started|alreadyActive|transmitOk| transmitNoAck|transmitFail|transmitNotIdle| transmitNoRoute]

sucRouteDel
• ZW_DELETE_SUC_RETURN_ROUTE [started|alreadyActive|transmitOk| transmitNoAck|transmitFail|transmitNotIdle| transmitNoRoute]

Class ALARM
• Note:
  Depending on the setting of the attribute "extendedAlarmReadings" the generated events differ slightly. With a value of "0" or "2" a combined reading for all alarm types of the device with the name "alarm" will be used. With a value of "1" or "2" separate readings for each supported alarm type will be generated with names "alarm_<alarmType>.
• Devices with class version 1 support: alarm_type_X:level Y
• For higher class versions more detailed events with 100+ different strings in the form alarm:<string> (or alarm_<alarmType>:<string>) are generated.
  For the combined reading, the name of the alarm type is part of the reading event, for separate readings it is part of the reading name.
  If a cleared event can be identified, the string "Event cleared:" is reported before the event details.
  The seperate readings also contain the status of the alarm / notification. For compatibility reasons this is currently not supported with the combined reading.

Class APPLICATION_STATUS
• applicationStatus: [cmdRejected]
• applicationBusy: [tryAgainLater|tryAgainInWaitTimeSeconds| RequestQueued|unknownStatusCode] $waitTime


Class ASSOCIATION
• assocGroup_X:Max Y Nodes A,B,...
• assocGroups:X


Class ASSOCIATION_GRP_INFO
• assocGroupName_X:name
• assocGroupCmdList_X:Class1:Cmd1 Class2:Cmd ...


Class BARRIER_OPERATOR
• barrierState:[ closed | [%] | closing | stopped | opening | open ]


Class BASIC
• basicReport:X (for class version 1)
  basicReport:X target y duration z (for class version 2 or greater)
• basicGet:request
• basicSet:X


Class BASIC_WINDOW_COVERING
• covering:[open|close|stop]


Class BATTERY
• battery:{low|chargelevel %}
• batteryState:{ok|low}
• batteryPercent:<value>


Class CENTRAL_SCENE
• cSceneSet:X
• cSceneDim:X
• cSceneDimEnd:X
• cSceneDouble:X
• cSceneMultiple_N:X
  where N is 3, 4 or 5 (multiple presses)


Class CLIMATE_CONTROL_SCHEDULE
• ccsOverride:[no|temporary|permanent], [frost protection|energy saving|unused]
• ccsChanged:<number>
• ccs_[mon|tue|wed|thu|fri|sat|sun]:HH:MM temp HH:MM temp...


Class CLOCK
• clock:get
• clock:[mon|tue|wed|thu|fri|sat|sun] HH:MM


Class COLOR_CONTROL
• ccCapability:XY
• ccStatus_X:Y
• cc<Col>:Y
  where <col> is one of WarmWhite, ColdWhite, Red, Green, Blue, Amber, Cyan, Purple, Indexed


Class CONFIGURATION
• config_X:Y
  Note: if the model is set (see MANUFACTURER_SPECIFIC get), then more specific config messages are available.


Class DEVICE_RESET_LOCALLY
• deviceResetLocally:yes
  


Class DOOR_LOCK, V2
• doorLockConfiguration: mode: [constant|timed] outsideHandles: $outside_mode(4 bit field) insideHandles: $inside_mode(4 bit field) timeoutSeconds: [not_supported|$seconds]
• doorLockOperation: mode: $mode outsideHandles: $outside_mode(4 bit field) insideHandles: $inside_mode(4 bit field) door: [open|closed] bolt: [locked|unlocked] latch: [open|closed] timeoutSeconds: [not_supported|$time]
  $mode = [unsecured|unsecured_withTimeout|unsecured_inside| unsecured_inside_withTimeout|unsecured_outside| unsecured_outside_withTimeout|secured


Class ENTRY_CONTROL
• entry_control:sequence $seq dataType $dt eventType $et data $data
  where:
  • $dt is one of NA RAW ASCII MD5
  • $et is one of CACHING CACHED_KEYS ENTER DISARM_ALL ARM_ALL ARM_AWAY ARM_HOME EXIT_DELAY ARM_1 ARM_2 ARM_3 ARM_4 ARM_5 ARM_6 RFID BELL FIRE POLICE ALERT_PANIC ALERT_MEDICAL GATE_OPEN GATE_CLOSE LOCK UNLOCK TEST


Class HAIL
• hail:01
  


Class HRV_STATUS
• outdoorTemperature: %0.1f C
• supplyAirTemperature: %0.1f C
• exhaustAirTemperature: %0.1f C
• dischargeAirTemperature: %0.1f C
• indoorTemperature: %0.1f C
• indoorHumidity: %s %
• remainingFilterLife: %s %
• supportedStatus: <list of supported stati>


Class INDICATOR
• indState:[on|off|dim value]


Class MANUFACTURER_PROPRIETARY
• Fibaro FGRM-222 with ReportsType Fibar CC only:
• position:Blind [%] Slat [%]
  (VenetianBlindMode)
• position:[%]
  (RollerBlindMode)


Class MANUFACTURER_SPECIFIC
• modelId:hexValue hexValue hexValue
• model:manufacturerName productName
• modelConfig:configLocation


Class METER
• energy:val [kWh|kVAh|pulseCount|powerFactor|kVar|kVarh]
• gas:val [m3|feet3|pulseCount]
• water:val [m3|feet3|USgallons|pulseCount]
• power:val W
• voltage:val V
• current:val A
• meterSupported:type:[meter_type] scales:[list of supported scales] resetable:[yes|no]


Class MULTI_CHANNEL
• endpoints:total X $dynamic $identical
• mcCapability_X:class1 class2 ...


Class NETWORK_SCHEDULE (SCHEDULE), V1
• schedule_<id>: ID: $schedule_id userID: $user_id sYear: $starting_year sMonth: $starting_month activeID: $active_id sDay: $starting_day sWeekDay: $starting_weekday sHour: $starting_hour durationType: $duration_type sMinute: $starting_minute duration: $duration numReportsToFollow: $number_of_reports_to_follow numCmds: $number_of_commands cmdLen: $length_of_command cmd: $commandsequence(hex)
• scheduleSupported: num: $number_of_supported_schedules startTimeSupport: $start_time_support(6 bit field) fallbackSupport: $fallback_support enableDisableSupport: $ena_dis_support numCCs: $number_of_supported_command_classes overrideTypes: $override_types(7 bit field) overrideSupport: $override_support
• scheduleSupportedCC: CC_<x>: $number_of_command_class CCname_<x>: $name_of_command_class]CCmask_<x>: $mask_for_command(2 bit)


Class NODE_NAMING
• name:NAME
• location:LOCATION


Class SOUND_SWITCH
• toneConfiguration:Volume VOLUME Default DEFAULT
• toneNumbers:NUMBER
• tonePlay:NUMBER


Class POWERLEVEL
• powerlvl:current x remain y
  NOTE: "current 0 remain 0" means normal mode without timeout
• powerlvlTest:node x status y frameAck z
  NOTE: status 0=failed, 1=success (at least one ACK), 2=in progress


Class PROTECTION
• protection:[on|off|seq]


Class SCENE_ACTIVATION
• scene_Id:level finalValue


Class SCENE_ACTUATOR_CONF
• scene_Id:level dimmingDuration finalValue


Class SCENE_CONTROLLER_CONF
• group_Id:scene dimmingDuration


Class SCHEDULE_ENTRY_LOCK
• scheduleEntryLockEntryTypeSupported:WeekDaySlots: $value YearDaySlots: $value
• weekDaySchedule_$userId:userID: $value slotID: $value $weekday $starthour:$startminute $endhour:$endminute
• yearDaySchedule_$userId:userID: $value slotID: $value start: $year-$month-$day $hour:$minute end: $year-$month-$day $hour:$minute
• scheduleEntryLockDailyRepeating_$userId:userID: $value $weekdays $hour:$minute $durationhour:$durationminute
  Note: $weekdays is a concatenated string with weekdaynames ("sun","mon","tue","wed","thu","fri","sat") where inactive weekdays are represented by "...", e.g. montue...wedfri
• scheduleEntryLockTimeOffset:TZO: $sign$hour:$minute DST: $sign$minutes


Class SECURITY
• none
  Note: the class security should work transparent to the sytem and is not intended to generate events


Class SENSOR_ALARM
• alarm_type_X:level Y node $nodeID seconds $seconds


Class SENSOR_BINARY
• SENSORY_BINARY V1:
• state:open
• state:closed
• SENSORY_BINARY V2:
• unknown:[off|on]
• generalPurpose:[off|on]
• smoke:[off|on]
• CO:[off|on]
• CO2:[off|on]
• heat:[off|on]
• water:[off|on]
• freeze:[off|on]
• tamper:[off|on]
• aux:[off|on]
• doorWindow:[off|on]
• tilt:[off|on]
• motion:[off|on]
• glassBreak:[off|on]


Class SENSOR_MULTILEVEL
• temperature $val [C|F]
• generalPurpose $val %
• luminance $val [%|Lux]
• power $val [W|Btu/h]
• humidity $val %
• velocity $val [m/s|mph]
• direction $val
• atmosphericPressure $val [kPa|inchHg]
• barometricPressure $val [kPa|inchHg]
• solarRadiation $val W/m2
• dewpoint $val [C|F]
• rain $val [mm/h|in/h]
• tideLevel $val [m|feet]
• weight $val [kg|pound]
• voltage $val [V|mV]
• current $val [A|mA]
• CO2-level $val ppm
• airFlow $val [m3/h|cfm]
• tankCapacity $val [l|cbm|usgal]
• distance $val [m|cm|feet]
• anglePosition $val [%|relN|relS]
• rotation $val [rpm|Hz]
• waterTemperature $val [C|F]
• soilTemperature $val [C|F]
• seismicIntensity $val [mercalli|EU macroseismic|liedu|shindo]
• seismicMagnitude $val [local|moment|surface wave|body wave]
• ultraviolet $val [UV]
• electricalResistivity $val [ohm]
• electricalConductivity $val [siemens/m]
• loudness $val [dB|dBA]
• moisture $val [%|content|k ohms|water activity]
• frequency $val [Hz|kHz]
• time $val [seconds]
• targetTemperature $val [C|F]
• particulateMatter $val [mol/m3|micro-g/m3]
• formaldehydeLevel $val [mol/m3]
• radonConcentration $val [bq/m3|pCi/L]
• methaneDensity $val [mol/m3]
• volatileOrganicCompound $val [mol/m3]
• carbonMonoxide $val [mol/m3]
• soilHumidity $val [%]
• soilReactivity $val [pH]
• soilSalinity $val [mol/m3]
• heartRate $val [Bpm]
• bloodPressure $val [Systolic mmHg|Diastolic mmHg]
• muscleMass $val [Kg]
• fatMass $val [Kg]
• boneMass $val [Kg]
• totalBodyWater $val [Kg]
• basicMetabolicRate $val [J]
• bodyMassIndex $val [BMI]


Class SWITCH_ALL
• swa:[ none | on | off | on off ]


Class SWITCH_BINARY
• state:on
• state:off
• state:setOn
• state:setOff
• swbState:$current target $target duration [$time seconds|unknown]


Class SWITCH_MULTILEVEL
• state:on
• state:off
• state:setOn
• state:setOff
• state:dim value
• state:swmBeginUp
• state:swmBeginDown
• state:swm [ Decrement | Increment ] [ Up | Down ] Start: $sl Duration: $dur Step: $step
• state:swmEnd
• swmStatus:$value target &target duration $duration


Class THERMOSTAT_FAN_MODE
• fanMode:[ fanAutoLow | fanLow | fanAutoHigh | fanHigh | fanAutoMedium | fanMedium ]


Class THERMOSTAT_FAN_STATE
• fanState:[ off | low | high | medium | circulation | humidityCirc | fanrightLeftCirc | upDownCirc | quietCirc ]


Class THERMOSTAT_MODE
• thermostatMode:[ off | cooling | heating | fanOnly | auto | energySaveHeating | manual | setTmOff | setTmHeating | setTmEnergySaveHeating | setTmManual ]


Class THERMOSTAT_OPERATING_STATE
• thermostatOperatingState:[ idle | heating | cooling | fanOnly | pendingHeat | pendingCooling | ventEconomizer | auxHeating | 2ndStageHeating | 2ndStageCooling | 2ndStageAuxHeat | 3rdStageAuxHeat ]


Class THERMOSTAT_SETPOINT
• setpointTemp:$temp $scale $type
  
  $temp: setpoint temperature with number of decimals as reported by the device
  $scale: [C|F]; C=Celsius scale, F=Fahrenheit scale
  $type: setpoint type, one of:
  
  heating, cooling, furnance, dryAir, moistAir, autoChangeover, energySaveHeating, energySaveCooling, awayHeating, awayCooling, fullPower


Class TIME, V2
• time:$time RTC: [failed|working]
• date:$date
• timeOffset: UTC-Offset: $utco DST-Offset(minutes): $dsto DST-Start: $start DST-End: $end


Class TIME_PARAMETERS, V1
• timeParameters: date: $date time(UTC): $time


Class USER_CODE
• userCode:id x status y code z


Class VERSION
• V1:
• version:Lib A Prot x.y App a.b
• V2:
• version:Lib A Prot x.y App a.b HW B FWCounter C FW c.d
• V1 and V2:
• versionClass_$classId:$version


Class WAKE_UP
• wakeup:notification
• wakeupReport:interval:X target:Y
• wakeupIntervalCapabilitiesReport:min W max X default Y step Z


Class ZWAVEPLUS_INFO
• zwavePlusInfo:version: V role: W node: X installerIcon: Y userIcon: Z

ZoneMinder

[EN DE]

Define

define <name> ZoneMinder <ZM-Host> [<username> <password>]

Defines a ZoneMinder device at the given host address. This allows you to exchange events between ZoneMinder and FHEM. Also providing username and password provides access to ZoneMinder API and more functionality.
Example:
define zm ZoneMinder 10.0.0.100
define zm ZoneMinder 10.0.0.100 fhemApiUser fhemApiPass

Get

• autocreateMonitors
  Queries the ZoneMinder API and autocreates all ZM_Monitor devices that belong to that installation.
• updateMonitorConfig
  Queries the ZoneMinder API and updates the Readings of ZM_Monitor devices (monitorFunction, motionDetectionEnabled, ...)
• calcAuthHash
  Calculates a fresh auth hash. Please note that the hash only changes with every full hour. So, calling this doesn't necessarily change any Readings, depending on the age of the current hash.

Attributes

• apiTimeout <seconds>
  This defines the request timeout in seconds for calls to the ZoneMinder API (right now, only for the login)
• apiVersion
  If you use ZoneMinder 1.32, this must be set to 'post132'
• publicAddress <address>
  This configures public accessibility of your LAN (eg your ddns address). Define a valid URL here, eg https://my.own.domain:2344
• webConsoleContext <path>
  If not set, this defaults to /zm. This is used for building the URL to the ZoneMinder web console.
• usePublicUrlForZmWeb
  If a public address is defined, this setting will use the public address for connecting to ZoneMinder API, instead of trying to use the IP-address.

Readings

• CPU_Load
  The CPU load of the ZoneMinder host. Provides 1, 5 and 15 minutes interval.
• authHash
  The auth hash that allows access to Stream URLs without requiring username or password.
• state
  The current connection state to the ZoneMinder Trigger Port (6802 per default)

alarmclock

[EN DE]

Fhem Modul to set up a Alarmclock

Define
define <name> alarmclock
Example: define Wecker alarmclock


Set

• AlarmTime(1_Monday|2_Tuesday|3_Wednesday|4_Thursday|5_Friday|6_Saturday|7_Sunday|8_Holiday|9_Vacation) HH:MM
  Sets a alarm time for each day.
• AlarmTime_Weekdays HH:MM
  Sets the same alarm time for each working day.
• AlarmTime_Weekend HH:MM
  Sets the same alarm time for Saturday and Sunday.
• AlarmOff (1_Monday|2_Tuesday|3_Wednesday|4_Thursday|5_Friday|6_Saturday|7_Sunday|8_Holiday|9_Vacation|Weekdays|Weekend|All)
  Sets the alarm time of the respective day to off.
• stop (Alarm)
  Stops a running alarm.
• save (Weekprofile_1|Weekprofile_2|Weekprofile_3|Weekprofile_4|Weekprofile_5)
  Save alarm times in a profile.
• load (Weekprofile_1|Weekprofile_2|Weekprofile_3|Weekprofile_4|Weekprofile_5)
  Load alarm times from profile.
• skip (NextAlarm|None)
  Skips the next alarm.
• disable (1|0|)
  Deactivated/Activated the alarmclock.


Attributes
• AlarmRoutine
  A list separated by semicolon (;) which Fhem should run at the alarm time.
  Example: attr <name> AlarmRoutine set Licht on;set Radio on
• AlarmRoutineOff
  A list separated by semicolon (;) which Fhem should execute to terminate the alarm.
  Example: attr <name> AlarmRoutineOff set Licht off;set Radio off
• EventForAlarmOff
  Fhem-event to end the alarm.
  There are 2 possibilities:
  1.Trigger on state.
  <devicename>:<state> Example: attr <name> EventForAlarmOff Taster:off
  2.Trigger on reading.
  <devicename>:<readingname>: <value> Example: attr <name> EventForAlarmOff Taster:cSceneSet: on
  
• EventForSnooze
  Fhem-event to interrupt the alarm.
  The syntax is identical to EventForAlarmOff.
  Example: attr <name> EventForSnooze Taster:cSceneSet: off
  
• SnoozeRoutine
  A list separated by semicolon (;) which Fhem operate to interrupt the running alarm.
  Example: attr <name> SnoozeRoutine set Licht off;set Radio off
• SnoozeTimeInSec
  Time in seconds how long the alarm should be interrupted.
  Example: attr <name> SnoozeTimeInSec 240
  
• PreAlarmRoutine
  A list separated by semicolon (;) which Fhem operate at the pre-alarm.
  Example: attr <name> PreAlarmRoutine set Licht dim 30;set Radio on
• PreAlarmTimeInSec
  Time in seconds between the alarm and the pre-alarm.
  Example: attr <name> PreAlarmTimeInSec 300
  In the example, the PreAlarmRoutine is executed 5 minutes before the regular alarm.
• HardAlarmRoutine
  A list separated by semicolon (;) which is to be executed to force the awakening.
  Example: attr <name> HardAlarmRoutine set Sonos_Schlafzimmer Volume 40;set Licht dim 90
• HardAlarmTimeInSec
  Here you can specify in seconds how long the alarm can "run" until HardAlarmRoutine is started.
  Example: attr <name> HardAlarmTimeInSec 300
• OffRoutine
  A list separated by semicolon (;) which Fhem operate at the OffDefaultTime.
  Example: attr <name> OffRoutine set rr_Florian home;set Heizung on
• OffDefaultTime
  Default time for the OffRoutine.
  Example: attr <name> OffDefaultTime 07:30
• MaxAlarmDurationInSec
  Duration in seconds to stop automatically the running alarm.
  Example: attr <name> MaxAlarmDurationInSec 120
• RepRoutine
  A list separated by semicolon (;) which is to be repeated.
  Example: attr <name> RepRoutine1 set Licht_Schlafzimmer dim 1
• RepRoutineWaitInSec
  Time in seconds between the repetitions from RepRoutine.
  Example: attr <name> RepRoutine1WaitInSec 20
• RepRoutineRepeats
  Number of repetitions of RepRoutine.
  Example: attr <name> RepRoutine1Repeats 15
• RepRoutineMode(Alarm|PreAlarm|off)
  Alarm:Reproutine is started with the alarm.
  PreAlarm:Reproutine is started with the pre-alarm.
  off:Reproutine is deactivated.
• RepRoutineStop(Snooze|off)
  Snooze:Reproutine is stopped with snooze.
  off:Reproutine is not stopped with snooze.
• HolidayDevice
  Name of the holiday device.
  There are 3 possibilities:
  1.holiday device from typ holiday or Calendar.
  <devicename>
  Example: attr <name> HolidayDevice Feiertage
  2.On state of a device.For example a dummy
  <devicename>:<value>
  Example: attr <name> HolidayDevice MyDummy:Holiday
  Here the AlarmTime 8_Holiday takes effect when the state of the dummy has the value Holiday
  3.On a reading of a device.
  <devicename>:<readingname>:<value>
  Example: attr <name> HolidayDevice MyDummy:Today:Holiday
  
• HolidayCheck
  0 disables monitoring the holiday device
  1 activates monitoring
• HolidayDays
  List of days on which the alarmtime 8_Holiday may take effect
  Example: attr <name> HolidayDays 1|2|3|4|5
  Default: 1|2|3|4|5|6|7
• VacationDevice
  Name of the vacation device.
  There are 3 possibilities:
  1.vacation device from typ holiday or Calendar.
  <devicename>
  Example: attr <name> VacationDevice Ferien
  2.On state of a device.For example a dummy
  <devicename>:<value>
  Example: attr <name> VacationDevice MyDummy:Vacation
  Here the AlarmTime 9_Vacation takes effect when the state of the dummy has the value Vacation
  3.On a reading of a device.
  <devicename>:<readingname>:<value>
  Example: attr <name> VacationDevice MyDummy:Today:Vacation
  
• VacationCheck
  0 disables monitoring the vacation device
  1 activates monitoring
• VacationDays
  List of days on which the alarmtime 9_Vacation may take effect
  Example: attr <name> VacationDays 1|2|3|4|5
  Default: 1|2|3|4|5|6|7
• PresenceDevice
  Name of the presence device.
  There are 3 possibilities:
  1.presence device from Typ presence.
  <devicename>
  Example: attr <name> PresenceDevice Presence
  Alarmclock cancel alarm when state is absent
  2.On state of a device.For example a dummy
  <devicename>:<value>
  Example: attr <name> PresenceDevice MyDummy:absent
  Here the Alarmclock cancel alarm when the state of the dummy has the value absent
  3.On a reading of a device.
  <devicename>:<readingname>:<value>
  Example: attr <name> PresenceDevice MyDummy:user:notathome
  
• PresenceCheck
  0 disables monitoring the presence device
  1 activates monitoring
• WeekprofileName
  Optional list with name for storing the week profiles
  Example: attr <name> WeekprofileName MyWeek1,MyWeek2,MyWeek3
  
• disable
  1 disables all alarms
  0 activates this again

alexa

[EN DE]

Module to control the integration of Amazon Alexa devices with FHEM.

Notes:
• JSON has to be installed on the FHEM host.
• HOWTO for public FHEM Connector skill: FHEM_Connector
• HOWTO for privte skills: alexa-fhem
Set
• add
  Adds the device name to alexa-fhem. Will try to send a proacive event to amazon. If this succedes no manual device discovery is needed. If this fails you have to you have to manually start a device discovery for the home automation skill in the amazon alexa app.
• reload [name]
  Reloads the device name or all devices in alexa-fhem. Will try to send a proacive event to amazon. If this succedes no manual device discovery is needed. If this fails you have to you have to manually start a device discovery for the home automation skill in the amazon alexa app.
• createDefaultConfig
  adds the default config for the sshproxy to the existing config file or creates a new config file. sets the alexaFHEM-config attribut if not already set.
• clearProxyCredentials
  clears all stored sshproxy credentials


Get
• customSlotTypes
  Instructs alexa-fhem to write the device specific Custom Slot Types for the Interaction Model configuration to the alexa-fhem console and if possible to the requesting fhem frontend.
• interactionModel
  Get Intent Schema, non device specific Custom Slot Types and Sample Utterances for the Interaction Model configuration.
• skillId
  shows the configured skillId.
Attr
• alexaFHEM-auth
  the user:password combination to use to connect to fhem.
• alexaFHEM-cmd
  The command to use as alexa-fhem.
• alexaFHEM-config
  The config file to use for alexa-fhem.
• alexaFHEM-log
  The log file to use for alexa-fhem. For possible %-wildcards see FileLog.
.
• nrarchive
  see FileLog
.
• alexaFHEM-params
  Additional alexa-fhem cmdline params.
• alexaName
  The name to use for a device with alexa.

The following attributes are only relevant for custom skills:
• alexaRoom
  The room name to use for a device with alexa.
• alexaProactiveEvents
  0 -> don't send proactiveEvents to amazon (default)
  1 -> send proactiveEvents to amazon
  devices that send proactiveEvents to amazon can be used to trigger alexa routines.
  setting alexaProactiveEvents to 0 in the alexa device itself will disable all event reporting for this fhem instance
• articles
  defaults to: der,die,das,den
• prepositions
  defaults to: in,im,in der
• alexaMapping
  maps spoken commands to intents for certain characteristics.
• alexaTypes
  maps spoken device types to ServiceClasses. eg: attr alexa alexaTypes light:licht,lampe,lampen blind:rolladen,jalousie,rollo Outlet:steckdose TemperatureSensor:thermometer LockMechanism:schloss OccupancySensor: anwesenheit
• echoRooms
  maps echo devices to default rooms.
• persons
  maps personIds to names.
• fhemIntents
  maps spoken commands directed to fhem as a whole (i.e. not to specific devices) to events from the alexa device.
• alexaConfirmationLevel
  
• alexaStatusLevel
  
• skillId
  skillId to use for automatic interaction model upload (not yet finished !!!)
Note: changes to attributes of the alexa device will automatically trigger a reconfiguration of alxea-fhem and there is no need to restart the service.

allergy

[EN DE]

This modul provides allergy forecast data for Germany.
It requires the Perl module XML::Simple to be installed

Define
define <name> allergy <zipcode>
Example: define allergydata allergy 12345
 
• zipcode
  German zipcode



Get
• data
  Manually trigger data update



Readings
• city
  Name of the city the forecast is read for


• fcn_total
  Daily maximum levels for all allergens that are not being ignored due to ignoreList
  


• fcn_day_of_week
  Weekday, can be localized through weekdaysFormat
  


• fcn_allergen
  Daily levels for all allergens that are not being ignored due to ignoreList


• date
  Forecast end date from alternative data source



Attributes
• ignoreList
  Comma-separated list of allergen names that are to be ignored during updates and for cumulated day levels calculation


• updateEmpty
  Also update (and keep) level readings for inactive allergens that are otherwise removed


• updateIgnored
  Also update (and keep) level readings for ignored allergens that are otherwise removed


• levelsFormat
  Localize levels by adding them comma separated (default: -,low,moderate,high,extreme)


• weekdaysFormat
  Localize Weekdays by adding them comma separated (default: Sun,Mon,Tue,Wed,Thu,Fr,Sat)


• alternative3Day (Standard: 0|1)
  Alternative data source with 3 day forecast.

allowed

[EN DE]

Define
define <name> allowed <deviceList>

Authorize execution of commands and modification of devices based on the frontend used and/or authenticate users.

If there are multiple instances defined which are valid for a given frontend device, then all authorizations must succeed. For authentication it is sufficient when one of the instances succeeds. The checks are executed in alphabetical order of the allowed instance names.

Note: this module should work as intended, but no guarantee can be given that there is no way to circumvent it.

Examples:
define allowedWEB allowed
attr allowedWEB validFor WEB,WEBphone,WEBtablet
attr allowedWEB basicAuth { "$user:$password" eq "admin:secret" }
attr allowedWEB allowedCommands set,get

define allowedTelnet allowed
attr allowedTelnet validFor telnetPort
attr allowedTelnet password secret



Set
• basicAuth <username> <password>
• password <password>
• globalpassword <password>
  these commands set the corresponding attribute, by computing an SHA256 hash from the arguments and a salt. Note: the perl module Digest::SHA is needed.

Get
N/A

Attributes
• allowedCommands
  A comma separated list of commands allowed from the matching frontend (see validFor).
  If set to an empty list , (i.e. comma only) then no comands are allowed. If set to get,set, then only a "regular" usage is allowed via set and get, but changing any configuration is forbidden.
  


• allowedDevices
  A comma or space separated list of device names which can be manipulated via the matching frontend (see validFor).


• allowedDevicesRegexp
  Regexp to match the devicenames, which can be manipulated. The regexp is prepended with ^ and suffixed with $, as usual.


• allowedIfAuthenticatedByMe
  By default (value is 1), the rules only apply, if the connection was authenticated (via username/password) by this allowed instance. Set the value to 0 to apply the rules anyway, e.g. if this instance has no username or password set.


• basicAuth, basicAuthMsg
  Request a username/password authentication for FHEMWEB access. It can be a base64 encoded string of user:password, an SHA256 hash (which should be set via the corresponding set command) or a perl expression if enclosed in {}, where $user and $password are set, and which returns true if accepted or false if not. Examples:
  attr allowed basicAuth ZmhlbXVzZXI6c2VjcmV0
attr allowed basicAuth SHA256:F87740B5:q8dHeiClaPLaWVsR/rqkzcBhw/JvvwVi4bEwKmJc/Is
attr allowed basicAuth {"$user:$password" eq "fhemuser:secret"}

  If basicAuthMsg is set, it will be displayed in the popup window when requesting the username/password. Note: not all browsers support this feature.
  


• basicAuthExpiry
  allow the basicAuth to be kept valid for a given number of days. So username/password as specified in basicAuth are only requested after a certain period. This is achieved by sending a cookie to the browser that will expire after the given period. Only valid if basicAuth is set.


• disable


• disabledForIntervals


• password
  Specify a password for telnet instances, which has to be entered as the very first string after the connection is established. The same rules apply as for basicAuth, with the expception that there is no user to be specified.
  Note: if this attribute is set, you have to specify a password as the first argument when using fhem.pl in client mode:
  perl fhem.pl localhost:7072 secret "set lamp on"


• globalpassword
  Just like the attribute password, but a password will only required for non-local connections.


• validFor
  A comma separated list of frontend names. Currently supported frontends are all devices connected through the FHEM TCP/IP library, e.g. telnet and FHEMWEB. The allowed instance is only active, if this attribute is set.

apptime

[EN DE]

apptime

apptime provides information about application procedure execution time. It is designed to identify long running jobs causing latency as well as general high CPU usage jobs.

No information about FHEM kernel times and delays will be provided.

Once started, apptime monitors tasks. User may reset counter during operation. apptime adds about 1% CPU load in average to FHEM.

In order to remove apptime, shutdown restart is necessary.

Features

apptime

apptime is started with the its first call and continously monitor operations.
To unload apptime, shutdown restart is necessary.

apptime clear

Reset all counter and start from zero.

apptime pause

Suspend accumulation of data. Data is not cleared.

apptime cont

Continue data collection after pause.

apptime [count|function|average|clear|max|name|total] [all]

Display a table sorted by the field selected.

all will display the complete table while by default only the top lines are printed.

Columns:

name

Name of the entity executing the procedure.

If it is a function called by InternalTimer the name starts with tmr-. By then it gives the name of the function to be called.

function

Procedure name which was executed.

If it is an InternalTimer call it gives its calling parameter.

max

Longest duration measured for this procedure in ms.

count

Number of calls for this procedure.

total

Accumulated duration of this procedure over all calls monitored.

average

Average time a call of this procedure takes.

maxDly

Maximum delay of a timer call to its schedules time. This column is not relevant for non-timer calls.

param Max call

Gives the parameter of the call with the longest duration.

archetype

With an archetype, attributes are transferred to other devices, so called inheritors. The inheritors can be defined according to a given pattern in the archetype and for relations, a certain group of devices.

As this is rather an abstract description that only may be self-explaining for those beeing familiar with concepts of inheritence in programming, here's some examples how archetype can be used:
• transfer attributes (and their values) from an archetype to arbitrary other devices and/or
• new devices (as well within the autocreate process) can be
  • supplied with define and attr commands derived according to patterns
  • supplied with default attribute values
  • initialized with default attribute values and/or Reading-values
• indicate and/or correct differences between actual and desired attribute values


These variables may be used within inheritence instructions:
• $name name of the inheritor
• $room room of the inheritor
• $relation name of the relation
• $SELF name of the archetype

Note: FHEM commands setdefaultattr and template provide partly similar functionality.

Commands

archetype <clean or check>
"clean" will define all inheritors for all relations and process all inheritances to all inheritors with the attributes specified under the attribute attribute.
If the "check" parameter is specified, all outstanding actions are displayed.



Define

define <name> archetype [<devspec>] [<devspec>] [...]
The <devspec> arguments point to all inheritors for this archetype. Make shure there are no conflicting actions described when using more than one archetype pointing to an inheritor. Basically it's recommended to associate each inheritor with just one archetype.
If no <devspec> is specified, it is set to "defined_by=$SELF". This devspec is also always checked, even if it is not specified explicitly.
See the section on device specification for details of the <devspec>.

define <name> archetype derive attributes
If the DEF specifies "derive attributes" it is a special archetype. It derives attributes based on a pattern.
The pattern is described with the actual_. + Attributes.
All devices with all the mandatory attributes of a pattern are listed as inheritors.



Set

• addToAttrList <attribute>
  The command is only possible for an archetype with DEF "derive attributes".
  Add an entry to the userattr of the global device so that it is available to all of the devices.
  This can be useful to derive the alias according to a pattern.


• define inheritors
  Defines an inheritor for all relations according to the pattern:
  
  define <metaNAME> <actualTYPE> [<metaDEF>]
  When an inheritor is defined, it is initialized with the commands specified under the initialize attribute, and the archetype assign thedefined_by attribute to the value $ SELF.
  The relations (metaNAME, metaTYPE and metaDEF) are described in the respective attributes.


• derive attributes
  This command is only availabe for an archetype with DEF "derive attributes".
  Derives all attributes specified under the attributes attribute for all inheritors.


• inheritance
  Inheritance all attributes specified under the attributes attribute for all inheritors. Attribute values will be taken - if available - from the respective actual_.+-attribute, otherwise the value will be taken from the archetype's attribute with the same name.


• import
  Helper funktion to create an archetype.
  • Imports all attributes from the given device as listed in archetype's attributes list.
  • If attributes was not set before, all attributes from the given device will be imported (as actual_.+-attribute) to the archetype; attributes will be filled with a list of the importierted attributes.
  • The values form the attributs will also be imported for further usage in the archetype (marked as optional with the "undef"-prefix).
  Note: While import is running, no values will be forwarded to the inheritors.


• initialize inheritors
  Executes all commands specified under the attributes initialize for all inheritors.


• raw <command>
  Executes the command for all inheritors.



Get

• inheritors
  Displays all inheritors.


• relations
  Displays all relations.


• • pending attributes
    Displays all outstanding attributes specified under the attributes attribute for all inheritors, which do not match the (not optional) attributes of the archetype.
  
  
  • pending inheritors
    Displays all outstanding inheritors, which shall be defined based on the described relations.



Attributes

Notes:
All attributes that can be inherited can be pre-modified with a modifier.
• attr archetype <attribute> undef:<...>
  If undef: preceded, the attribute is not inherited if the inheritors does not already have this attribute (no matter which value it is set to).


• attr archetype <attribute> least[(<seperator>)]:<...>
  If a list is inherited, it can be specified that these elements should be at least present, by prepending the least[(<seperator>)]:.
  If no separator is specified, the space is used as separator.
• attr archetype <attribute> Perl:<...>
attr archetype <attribute> undef,Perl:<...>
  Default behaviour for Perl code in any attribute is: Code will be evaluated and the result will be the value to be set in the inheritor's attribute. (Additional) modifier Perl: will change that so the (unevaluated) Perl code will be used directly as attribute value (e.g. usefull for devStateIcon or stateFormat).




• actual_<attribute> <value>
  <value> can be specified as <text> or {perl code}.
  If the attribute <attribute> becomes inheritance the return value of the attribute actual_<attribute> is replacing the value of the attribute.
  The archetype with DEF "derive attributes" can be used to define patterns.
  Example: actual_alias %captionRoom|room%: %description%[ %index%][%suffix%]
  All terms enclosed in% are attributes. An order can be achieved by |. If an expression is included in [] it is optional.
  The captionRoom, description, index, and suffix expressions are added (e.g.) by addToAttrList.
  Remarks and options:
  • no return value
  If an actual_<attribute> is set, it will be used instead of the identically named <attribute>. If it contains Perl code to be evaluated and evaluation returns no value, no changes will be derived.
  • Filtering
  Extending the attribute names indicates filtering is desired. Syntax is: actual_<attribute>_<index> <FILTER> <value>. This may be helpful to configure devices with more than one channels or different models by a common archetype. If the given filter matches, this will prevent useage of content of actual_<attribute> (and <attribute> as well), even if the evaluation of Perl code will return nothing.
  Example:
  define archHM_CC archetype TYPE=CUL_HM:FILTER=model=(HM-CC-RT-DN|HM-TC-IT-WM-W-EU)
attr archHM_CC attributes devStateIcon icon
attr archHM_CC actual_devStateIcon_RT model=HM-CC-RT-DN:FILTER=chanNo=04 Perl:{devStateIcon_Clima($name)}
attr archHM_CC actual_devStateIcon_WT model=HM-TC-IT-WM-W-EU:FILTER=chanNo=02 Perl:{devStateIcon_Clima($name)}
attr archHM_CC actual_icon hm-cc-rt-dn
attr archHM_CC actual_icon_2 model=HM-TC-IT-WM-W-EU hm-tc-it-wm-w-eu
  • Frontend availability
  actual_<attribute> is a "wildcard" attribute, intended to be set (initially) using FHEM command field. Wrt. to useage of filtering, this is the only way to set this type of attribute, all items from the attributes list will added as actual_<attribute> as well and then can be accessed directly by the regular drop-down menu in FHEMWEB.


• actualTYPE <TYPE>
  Sets the TYPE of the inheritor. The default value is dummy.


• attributes <attribute> [<attribute>] [...]
  Space-separated list of attributes to be inherited. Values of the attributes in the inheritence process will be taken from the attributes with either (lower to higher priority) from
  • attribute with exactly the same name
  • attribute following the name sheme actual_<attribute>
  • attribute following the name sheme actual_<attribute>_<index> in combination with matching filter


• attributesExclude <attribute> [<attribute>] [...]
  A space-separated list of attributes that are not inherited to these inheritors.


• autocreate 0
  If set to 0, the archetype does not automatically inherit attributes to new devices, and inheritors are not created automatically for new relations.
  The default value is 1.


• autoclean_init 1
  If set to 1, the archetype will automatically execute an inherit action after FHEM has startet.
  The default value is 0.


• defined_by <...>
  Auxiliary attribute to recognize by which archetype the device has been defined as inheritor.


• deleteAttributes 1
  If set to 1 and then an attribute is deleted in the archetype, it is also deleted for all inheritors.
  The default value is 0.


• disable 1
  No attributes are inherited and no inheritors are defined.


• initialize <initialize>
  <initialize> can be specified as <text> or {perl code}.
  The <text> or the return of {perl code} must be a list of FHEM commands separated by a semicolon (;). These are used to initialize the inheritors when they are defined.
  Note: This functionality is limited to "relations"!


• metaDEF <metaDEF>
  <metaDEF> can be specified as <text> or {perl code} and describes the structure of the DEF for the inheritors.


• metaNAME <metaNAME>
  <metaNAME> can be specified as <text> or {perl code} and describes the structure of the name for the inheritors.


• readingList <values>
setList <values>
  Both work as same attributes in dummy. They are intented to set initial values for "initialize"-actions that may he handed over to heirs.


• relations <devspec> [<devspec>] [...]
  The relations describes all the relations that exist for this archetype.
  See the section on device specification for details of the <devspec>.


• splitRooms 1
  Returns every room seperatly for each relation in $room.



Examples
The following sample codes can be imported via "Raw definition".


• All plots should be moved to the group "history":

  defmod SVG_archetype archetype TYPE=SVG
  attr SVG_archetype attributes group
  attr SVG_archetype group history
  

• In addition, a weblink should be created for all plots:

  defmod SVG_link_archetype archetype
  attr SVG_link_archetype relations TYPE=SVG
  attr SVG_link_archetype actualTYPE weblink
  attr SVG_link_archetype metaNAME $relation\_link
  attr SVG_link_archetype metaDEF link ?detail=$relation
  attr SVG_link_archetype initialize attr $name room $room;;
  attr SVG_link_archetype group history
  attr SVG_link_archetype attributes group

at

Start an arbitrary FHEM command at a later time.

Define
define <name> at [<timespec>|<datespec>] <command>

<timespec> format: [+][*{N}]<timedet>

The optional + indicates that the specification is relative(i.e. it will be added to the current time).
The optional * indicates that the command should be executed repeatedly.
The optional {N} after the * indicates,that the command should be repeated N-times only.
<timespec> is either HH:MM, HH:MM:SS or {perlfunc()}. perlfunc must return a string in timedet format. Note: {perlfunc()} may not contain any spaces or tabs.
<datespec> is either ISO8601 (YYYY-MM-DDTHH:MM:SS) or number of seconds since 1970 or {perlfunc()}.

Examples:

    # absolute ones:
    define a1 at 17:00:00 set lamp on                            # fhem command
    define a2 at 17:00:00 { Log 1, "Teatime" }                   # Perl command
    define a3 at 17:00:00 "/bin/echo "Teatime" > /dev/console"   # shell command
    define a4 at *17:00:00 set lamp on                           # every day

    # relative ones
    define a5 at +00:00:10 set lamp on                 # switch on in 10 seconds
    define a6 at +00:00:02 set lamp on-for-timer 1     # Blink once in 2 seconds
    define a7 at +*{3}00:00:02 set lamp on-for-timer 1 # Blink 3 times

    # Blink 3 times if the piri sends a command
    define n1 notify piri:on.* define a8 at +*{3}00:00:02 set lamp on-for-timer 1

    # Switch the lamp on from sunset to 11 PM
    define a9 at +*{sunset_rel()} set lamp on
    define a10 at *23:00:00 set lamp off

    # More elegant version, works for sunset > 23:00 too
    define a11 at +*{sunset_rel()} set lamp on-till 23:00

    # Only do this on weekend
    define a12 at +*{sunset_rel()} { fhem("set lamp on-till 23:00") if($we) }

    # Switch lamp1 and lamp2 on from 7:00 till 10 minutes after sunrise
    define a13 at *07:00 set lamp1,lamp2 on-till {sunrise(+600)}

    # Switch the lamp off 2 minutes after sunrise each day
    define a14 at *{sunrise(+120)} set lamp on

    # Switch lamp1 on at sunset, not before 18:00 and not after 21:00
    define a15 at *{sunset(0,"18:00","21:00")} set lamp1 on

    

Notes:

• if no * is specified, then a command will be executed only once, and then the at entry will be deleted. In this case the command will be saved to the statefile (as it considered volatile, i.e. entered by cronjob) and not to the configfile (see the save command.)
• if the current time is greater than the time specified, then the command will be executed tomorrow.
• For even more complex date handling you either have to call fhem from cron or filter the date in a perl expression, see the last example and the section Perl special.
• To execute a FHEM command on every last day of the month,
  the function at_ultimo() can be used as perlfunc for datespec.
  define at_ultimo at *{at_ultimo()} set lamp1 off
  This will create an at device which will be executed at 23:59:00 on the last day of month.
  at_ultimo() can take additional parameters to specify an other time on this day
  define at_ultimo at *{at_ultimo(12,34,56)} set lamp1 off
  This will create an at device which will be executed at 12:34:56 on the last day of month.
  


Set
• modifyTimeSpec <timespec>
  Change the execution time. Note: the N-times repetition is ignored. It is intended to be used in combination with webCmd, for an easier modification from the room overview in FHEMWEB.
• inactive
  Inactivates the current device. Note the slight difference to the disable attribute: using set inactive the state is automatically saved to the statefile on shutdown, there is no explicit save necesary.
  This command is intended to be used by scripts to temporarily deactivate the at.
  The concurrent setting of the disable attribute is not recommended.
• active
  Activates the current device (see inactive).
• execNow
  Execute the command associated with the at. The execution of a relative at is not affected by this command.
• skip_next
  skip the next execution. Just like the attribute with the same name, but better suited for webCmd.
• setList
  space separated list of user-defined commands. When executing such a command, a reading with the same name is set to the arguments of the command.
  Can be used in scenarios like:
  define wakeUp at *07:30 set Light on-for-timer [$SELF:duration]
attr wakeUp setList duration:60,120,180

Get
N/A

Attributes
• alignTime
  Applies only to relative at definitions: adjust the time of the next command execution so, that it will also be executed at the desired alignTime. The argument is a timespec, see above for the definition.
  Example:
  
  # Make sure that it chimes when the new hour begins
  define at2 at +*01:00 set Chime on-for-timer 1
  attr at2 alignTime 00:00
  


• computeAfterInit
  If perlfunc() in the timespec relies on some other/dummy readings, then it will return a wrong time upon FHEM start, as the at define is processed before the readings are known. If computeAfterInit is set, FHEM will recompute timespec after the initialization is finished.


• disable
• disabledForIntervals
• skip_next
  Used for at commands: skip the execution of the command the next time.


• setList
  Leerzeichen getrennte Liste von benutzerdefinierten Befehlen. Beim ausfüren solcher Befehle wird ein gleichnamiges Reading auf dem Wert des Befehls gesetzt. Kann z.Bsp. wie folgt verwendet werden:
  define wecker at *07:30 set Licht on-for-timer [$SELF:dauer]
attr wecker setList dauer:60,120,180

autocreate

[EN DE]

Automatically create not yet defined FHEM devices upon reception of a message generated by this device. Note: devices which are polled (like the EMEM/EMWZ accessed through the EM1010PC) will NOT be automatically created.
Define
define <name> autocreate


By defining an instance, the global attribute autoload_undefined_devices is set, so that modules for unknnown devices are automatically loaded. The autocreate module intercepts the UNDEFINED event generated by each module, creates a device and optionally also FileLog and SVG entries.
Note 1: devices will be created with a unique name, which contains the type and a unique id for this type. When renaming the device, the automatically created filelog and SVG devices will also be renamed.
Note 2: you can disable the automatic creation by setting the disable attribute, in this case only the rename hook is active, and you can use the createlog command to add FileLog and SVG to an already defined device. Note 3: It makes no sense to create more than one instance of this module.

Example:

    define autocreate autocreate
    attr autocreate autosave
    attr autocreate device_room %TYPE
    attr autocreate filelog test2/log/%NAME-%Y.log
    attr autocreate weblink
    attr autocreate weblink_room Plots
    

Set
N/A

Get
N/A

Attributes
• autosave
  After creating a device, automatically save the config file with the command save command. Default is 1 (i.e. on), set it to 0 to switch it off.
  Note: this attribute is deprecated, use the global autosave attribute instead.


• device_room
  "Put" the newly created device in this room. The name can contain the wildcards %TYPE and %NAME, see the example above.


• filelog
  Create a filelog associated with the device. The filename can contain the wildcards %TYPE and %NAME, see the example above. The filelog will be "put" in the same room as the device.


• weblink
  Create an SVG associated with the device/filelog.


• weblink_room
  "Put" the newly created SVG in this room. The name can contain the wildcards %TYPE and %NAME, see the example above.


• disable


• ignoreTypes
  This is a regexp, to ignore certain devices, e.g. the neighbours FHT. You can specify more than one, with usual regexp syntax, e.g.
  attr autocreate ignoreTypes (CUL_HOERMANN.*|FHT_1234|CUL_WS_7)
  The word "Types" is somehow misleading, as it first checks the generated device name, and then the type:name pair.
  Note: starting with featurelevel 5.8 the regexp is automatically extended with ^ and $, so that it must match the whole name or type:name (same procedure as in notify and FileLog).


• autocreateThreshold
  A list of <type>:<count>:<interval> triplets. A new device is only created if there have been at least count events of TYPE type in the last interval seconds.
  attr autocreateThreshold LaCrosse:2:30,EMT7110:2:60

createlog
Use this command to manually add a FileLog and an SVG to an existing device. This command is part of the autocreate module.

usb
Usage:
usb scan
usb create

This command will scan the /dev directory for attached USB devices, and will try to identify them. With the argument scan you'll get back a list of FHEM commands to execute, with the argument create there will be no feedback, and the devices will be created instead.

Note that switching a CUL to HomeMatic mode is still has to be done manually.

On Linux it will also check with the lsusb command, if unflashed CULs are attached. If this is the case, it will call CULflash with the appropriate parameters (or display the CULflash command if scan is specified). The usb command will only flash one device per call.

This command is part of the autocreate module.

average

[EN DE]

Compute additional average, minimum and maximum values for current day and month.
Define
define <name> average <regexp>


The syntax for <regexp> is the same as the regexp for notify.
If it matches, and the event is of the form "eventname number", then this module computes the daily and monthly average, maximum and minimum values and sums depending on attribute settings and generates events of the form
<device> <eventname>_avg_day: <computed_average>
<device> <eventname>_min_day: <minimum day value>
<device> <eventname>_max_day: <maximum day value>
<device> <eventname>_cum_day: <sum of the values during the day>
and
<device> <eventname>_avg_month: <computed_average>
<device> <eventname>_min_month: <minimum month value>
<device> <eventname>_max_month: <maximum month value>
<device> <eventname>_cum_month: <sum of the values during the month>
at the beginning of the next day or month respectively depending on attributes defined.
The current average, minimum, maximum and the cumulated values are stored in the device readings depending on attributes defined.

Example:

    # Compute the average, minimum and maximum for the temperature events of
    # the ws1 device
    define avg_temp_ws1 average ws1:temperature.*

    # Compute the average, minimum and maximum for each temperature event
    define avg_temp_ws1 average .*:temperature.*

    # Compute the average, minimum and maximum for all temperature and humidity events
    # Events:
    # ws1 temperature: 22.3
    # ws1 humidity: 67.4
    define avg_temp_ws1 average .*:(temperature|humidity).*

    # Compute the same from a combined event. Note: we need two average
    # definitions here, each of them defining the name with the first
    # paranthesis, and the value with the second.
    # 
    # Event: ws1 T: 52.3  H: 67.4
    define avg_temp_ws1_t average ws1:(T):.([-\d\.]+).*
    define avg_temp_ws1_h average ws1:.*(H):.([-\d\.]+).*
    

Set
N/A

Get
N/A

Attributes
• disable
• disabledForIntervals
• computeMethod [integral|counter]
  defines how values are added up for the average calculation. This attribute can be set to integral or counter. The integral mode is meant for measuring continuous values like temperature, counter is meant for adding up values, e.g. from a feeding unit. In the first case, the time between the events plays an important role, in the second case not. Default is integral.


• floatformat <formatstring>
  string used in sprintf to format the numbers, default is %0.1f


• nominmax [0|1]
  don't compute min and max values. Default is 0 (compute min & max).
• noaverage [0|1]
  don't compute average values. Default is 0 (compute avarage).


Generated events:
• <eventname>_avg_day: $avg_day
• <eventname>_avg_month: $avg_month
• <eventname>_cum_day: $cum_day (only if cumtype is set to raw)
• <eventname>_cum_month: $cum_month (only if cumtype is set to raw)
• <eventname>_min_day: $min_day
• <eventname>_min_month: $min_month
• <eventname>_max_day: $max_day
• <eventname>_max_month: $max_month

backup

[EN DE]

backup

The complete FHEM directory (containing the modules), the WebInterface pgm2 (if installed) and the config-file will be saved into a .tar.gz file by default. The file is stored with a timestamp in the modpath/backup directory or to a directory specified by the global Attribute backupdir.
Note: tar and gzip must be installed to use this feature.

If you need to call tar with support for symlinks, you could set the global Attribute backupsymlink to everything else as "no".

You could pass the backup to your own command / script by using the global ::attribute backupcmd.

cloneDummy

[EN DE]

This module provides a cloneDummy which will receive readings from any other device sending data to fhem.
E.g. may be used in an FHEM2FHEM environment. Duplicate source events which may occur within the time given by the global attribute dupTimeout, will be suppressed in order to avoid overhead. The value of this attribute is to be changed with great care, as it affects other parts of FHEM, too.
the order of precedence for STATE is following:
• if there is no parameter preset then state of cloneDummy (initialized,active)
• if addStateEvent is set then the "state" of cloned Device is set (no "state" from cloneDummy)
• if the optional reading is set in define, then value of the optional reading. (this will overstrike the previous two lines)
• if stateFormat set ass attr, it will dominate all previous lines

Define
define <cloneDevice> cloneDummy <sourceDevice> [reading]

Example:


define clone_OWX_26_09FF26010000 cloneDummy OWX_26_09FF26010000

Optional parameter [reading] will be written to STATE if provided.

Example:


define clone_OWX_26_09FF26010000 cloneDummy OWX_26_09FF26010000 temperature


Set
N/A

Get
N/A

Attributes
• addStateEvent
  When paremeter in Modul is set to 1 the originalstate of the original Device will be STATE (Momentarily not possible in Connection with FHEM2FHEM)


• cloneIgnore
  - comma separated list of readingnames that will NOT be generated.
  Useful to prevent truncated readingnames coming from state events.


• deleteBeforeUpdate
  If set to 1, all readings will be deleted befor update.


• readingFnAttributes

Important: You MUST use different names for cloneDevice and sourceDevice!

cmdalias

[EN DE]

create new FHEM commands or replace internal ones.

Define
define <name> cmdalias <cmd_to_be_replaced or new_cmd> [parameter] AS <existing_cmd>

parameter is optional and is a regexp which must match the command entered. If it matches, then the specified <existing_command> will be executed, which is a FHEM command (see FHEM command types for details). Like in notify, $EVENT or $EVTPART may be used, in this case representing the command arguments as whole or the unique words entered.

Notes:
• recursion is not allowed.
• if there are multiple definitions, they are checked/executed in alphabetically sorted <name> oder.
Examples:
define s1 cmdalias shutdown update AS save;;shutdown
define s2 cmdalias set lamp .* AS { Log 1, "$EVENT";; fhem("set $EVENT") }
Attribute
• disable
• disabledForIntervals

configDB

[EN DE]

Link to FHEM forum

This is the core backend library for configuration from SQL database.
See configdb command documentation for detailed info.

configdb

[EN DE]

Link to FHEM forum

Starting with version 5079, fhem can be used with a configuration database instead of a plain text file (e.g. fhem.cfg).
This offers the possibility to completely waive all cfg-files, "include"-problems and so on.
Furthermore, configDB offers a versioning of several configuration together with the possibility to restore a former configuration.
Detailed information about the available recovery and rescue modes can be found in this forum thread:
https://forum.fhem.de/index.php/topic,86225.0.html
Access to database is provided via perl's database interface DBI.

Interaction with other modules


Currently the fhem modules


• 02_RSS.pm
• 10_RHASSPY.pm
• 31_Lightscene.pm
• 55_InfoPanel.pm
• 91_eventTypes
• 93_DbLog.pm
• 95_holiday.pm
• 98_SVG.pm
• 98_weekprofile.pm

will use configDB to read their configuration data from database
instead of formerly used configuration files inside the filesystem.

This requires you to import your configuration files from filesystem into database.

Examples:
configdb fileimport FHEM/nrw.holiday
configdb fileimport FHEM/myrss.layout
configdb fileimport www/gplot/xyz.gplot

This does not affect the definitons of your holiday or RSS entities.

During migration all external configfiles used in current configuration
will be imported aufmatically.

Each fileimport into database will overwrite the file if it already exists in database.




Prerequisits / Installation



• Please install perl package Text::Diff if not already installed on your system.


• You must have access to a SQL database. Supported database types are SQLITE, MYSQL and POSTGRESQL.


• The corresponding DBD module must be available in your perl environment,
  e.g. sqlite3 running on a Debian systems requires package libdbd-sqlite3-perl


• Create an empty database, e.g. with sqlite3:
  

  	mba:fhem udo$ sqlite3 configDB.db
  
  	SQLite version 3.7.13 2012-07-17 17:46:21
  	Enter ".help" for instructions
  	Enter SQL statements terminated with a ";"
  	sqlite> pragma auto_vacuum=2;
  	sqlite> .quit
  
  	mba:fhem udo$ 
  			

• The database tables will be created automatically.


• Create a configuration file containing the connection string to access database.
  
  IMPORTANT:
  
  
  • This file must be named "configDB.conf"
  • This file must be located in the same directory containing fhem.pl and configDB.pm, e.g. /opt/fhem
  
  

  ## for MySQL
  ################################################################
  #%dbconfig= (
  #	connection => "mysql:database=configDB;host=db;port=3306",
  #	user => "fhemuser",
  #	password => "fhempassword",
  #);
  ################################################################
  #
  ## for PostgreSQL
  ################################################################
  #%dbconfig= (
  #        connection => "Pg:database=configDB;host=localhost",
  #        user => "fhemuser",
  #        password => "fhempassword"
  #);
  ################################################################
  #
  ## for SQLite (username and password stay empty for SQLite)
  ################################################################
  #%dbconfig= (
  #        connection => "SQLite:dbname=/opt/fhem/configDB.db",
  #        user => "",
  #        password => ""
  #);
  ################################################################
  			



Start with a complete new "fresh" fhem Installation


It's easy... simply start fhem by issuing following command:


perl fhem.pl configDB

configDB is a keyword which is recognized by fhem to use database for configuration.

That's all. Everything (save, rereadcfg etc) should work as usual.

or:

Migrate your existing fhem configuration into the database


It's easy, too...


• start your fhem the last time with fhem.cfg
  
  
  perl fhem.pl fhem.cfg



• transfer your existing configuration into the database
  
  
  enter
  
  configdb migrate
  
  into frontend's command line
  
  
  Be patient! Migration can take some time, especially on mini-systems like RaspberryPi or Beaglebone.
  Completed migration will be indicated by showing database statistics.
  Your original configfile will not be touched or modified by this step.


• shutdown fhem


• restart fhem with keyword configDB
  
  
  perl fhem.pl configDB

configDB is a keyword which is recognized by fhem to use database for configuration.

That's all. Everything (save, rereadcfg etc) should work as usual.


Additional functions provided


A new command configdb is propagated to fhem.
This command can be used with different parameters.


• configdb attr [attribute] [value]

Provides the possibility to pass attributes to backend and frontend.

configdb attr private 1 - set the attribute named 'private' to value 1.

configdb attr private - delete the attribute named 'private'

configdb attr - show all defined attributes.

configdb attr ?|help - show a list of available attributes.


• configdb diff <device> <version>

Compare configuration dataset for device <device> from current version 0 with version <version>
Example for valid request:

configdb diff telnetPort 1

will show a result like this:

compare device: telnetPort in current version 0 (left) to version: 1 (right)
+--+--------------------------------------+--+--------------------------------------+
| 1|define telnetPort telnet 7072 global  | 1|define telnetPort telnet 7072 global  |
* 2|attr telnetPort room telnet           *  |                                      |
+--+--------------------------------------+--+--------------------------------------+

Special: configdb diff all current

Will show a diff table containing all changes between saved version 0
and UNSAVED version from memory (currently running installation).


• configdb dump [unzipped]

Create a gzipped dump file from from database.
If optional parameter 'unzipped' provided, dump file will be written unzipped.



• configdb filedelete <Filename>

Delete file from database.



• configdb fileexport <targetFilename>|all

Exports specified file (or all files) from database into filesystem.
Example:

configdb fileexport FHEM/99_myUtils.pm



• configdb fileimport <sourceFilename>

Imports specified text file from from filesystem into database.
Example:

configdb fileimport FHEM/99_myUtils.pm



• configdb filelist

Show a list with all filenames stored in database.



• configdb filemove <sourceFilename>

Imports specified fhem file from from filesystem into database and
deletes the file from local filesystem afterwards.
Example:

configdb filemove FHEM/99_myUtils.pm



• configdb fileshow <Filename>

Show content of specified file stored in database.



• configdb info [raw]

Returns some database statistics
if optional "raw" selected, version infos will be returned as json"


--------------------------------------------------------------------------------
 configDB Database Information
--------------------------------------------------------------------------------
 dbconn: SQLite:dbname=/opt/fhem/configDB.db
 dbuser: 
 dbpass: 
 dbtype: SQLITE
--------------------------------------------------------------------------------
 fhemconfig: 7707 entries

 Ver 0 saved: Sat Mar  1 11:37:00 2014 def: 293 attr: 1248
 Ver 1 saved: Fri Feb 28 23:55:13 2014 def: 293 attr: 1248
 Ver 2 saved: Fri Feb 28 23:49:01 2014 def: 293 attr: 1248
 Ver 3 saved: Fri Feb 28 22:24:40 2014 def: 293 attr: 1247
 Ver 4 saved: Fri Feb 28 22:14:03 2014 def: 293 attr: 1246
--------------------------------------------------------------------------------
 fhemstate: 1890 entries saved: Sat Mar  1 12:05:00 2014
--------------------------------------------------------------------------------

Ver 0 always indicates the currently running configuration.


• configdb list [device] [version]

Search for device named [device] in configuration version [version]
in database archive.
Default value for [device] = % to show all devices.
Default value for [version] = 0 to show devices from current version.
Examples for valid requests:

get configDB list
get configDB list global
get configDB list '' 1
get configDB list global 1


• configdb rawList

Lists the running configuration in the same order that
would be written to a configuration file.


• configdb recover <version>

Restores an older version from database archive.
configdb recover 3 will copy version #3 from database to version #0.
Original version #0 will be lost.

Important!
The restored version will NOT be activated automatically!
You must do a rereadcfg or - even better - shutdown restart yourself.


• configdb reorg [keep]

Deletes all stored versions with version number higher than [keep].
Default value for optional parameter keep = 3.
This function can be used to create a nightly running job for
database reorganisation when called from an at-Definition.


• configdb search [searchVersion]

Search for specified searchTerm in any given version (default=0)


Example:

configdb search %2286BC%

Result:

search result for: %2286BC% in version: 0 
-------------------------------------------------------------------------------- 
define az_RT CUL_HM 2286BC 
define az_RT_Clima CUL_HM 2286BC04 
define az_RT_Climate CUL_HM 2286BC02 
define az_RT_ClimaTeam CUL_HM 2286BC05 
define az_RT_remote CUL_HM 2286BC06 
define az_RT_Weather CUL_HM 2286BC01 
define az_RT_WindowRec CUL_HM 2286BC03 
attr Melder_FAl peerIDs 00000000,2286BC03, 
attr Melder_FAr peerIDs 00000000,2286BC03, 



• configdb uuid

Returns a uuid that can be used for own purposes.




Author's notes


• You can find two template files for datebase and configfile (sqlite only!) for easy installation.
  Just copy them to your fhem installation directory (/opt/fhem) and have fun.


• The frontend option "Edit files"->"config file" will be removed when running configDB.


• Please be patient when issuing a "save" command (either manually or by clicking on "save config").
  This will take some moments, due to writing version informations.
  Finishing the save-process will be indicated by a corresponding message in frontend.


• There still will be some more (planned) development to this extension, especially regarding some perfomance issues.


• Have fun!

copy

[EN DE]

copy <orig name> <copy name> [<type dependent arguments>]

Create a copy of device <orig name> with the name <copy name>.
If <type dependent arguments> are given they will replace the DEF of <orig name> for the creation of <copy name>.

count

[EN DE]

count [devspec] [raw]

Count devices specified by devspec.
If no devspec given, count will return number of totally defined devices.
Count will return the plain number of devices if "raw" passed as last part of the command.
This is useful for processing the number of devices itself.

dash_dhcp

[EN DE]

Module to integrate amazon dash buttons into FHEM;.

The module can listen direclty to dhcp broadcast messages or listen to redirected openwrt dhcp log messages. Notes:
• if listening for dhcp messages the module has to run as root or you have to redirect port 67 with
  iptables -A PREROUTING -t nat -i eth0 -p udp --dport 67 -j REDIRECT --to-port 6767
  or
  iptables -I PREROUTING -t nat -i eth0 -p udp --src 0.0.0.0 --dport 67 -j DNAT --to 0.0.0.0:6767
  and use the port attribute to configure the redirected port.
• to make iptables rules permanent see for example: https://www.thomas-krenn.com/de/wiki/Iptables_Firewall_Regeln_dauerhaft_speichern
Attr
• devAlias
  space separated list of <mac>:<alias> pairs.
• allowed
  comma separated list of allowed mac adresses
• port
  the listen port. defaults to 67 for root and 6767 for other users.
• disable
• disabledForIntervals

dewpoint

[EN DE]

Dewpoint calculations. Offers three different ways to use dewpoint:

• dewpoint
  Compute additional reading dewpoint from a sensor offering temperature and humidity.
• fan
  Generate a event to turn a fan on if the outside air has less water than the inside.
• alarm
  Generate a mold alarm if a reference temperature is lower than the current dewpoint.


Define
define <name> dewpoint dewpoint <devicename-regex> [<temp_name> <hum_name> <new_name>]


Calculates dewpoint for device <devicename-regex> from temperature and humidity and write it to a new reading named dewpoint. If optional <temp_name>, <hum_name> and <new_name> is specified then read temperature from reading <temp_name>, humidity from reading <hum_name> and write the calculated dewpoint to reading <new_name>.
Obsolete, avoid for new definitions
  If <temp_name> is T then use temperature from state T: H:, add <new_name> to the STATE. The addition to STATE only occurs if the target device does not define attribute "stateFormat".
If the obsolete behaviour of STATE is mandatory set attribute legacyStateHandling.


Example:

    # Compute the dewpoint for the temperature/humidity
    # events of the temp1 device and generate reading dewpoint.
    define dew_temp1 dewpoint dewpoint temp1
    define dew_temp1 dewpoint dewpoint temp1 temperature humidity dewpoint

    # Compute the dewpoint for the temperature/humidity
    # events of all devices offering temperature and humidity
    # and generate reading dewpoint.
    define dew_all dewpoint dewpoint .*
    define dew_all dewpoint dewpoint .* temperature humidity dewpoint

    # Compute the dewpoint for the temperature/humidity
    # events of the device Aussen_1 offering temperature and humidity
    # and insert is into STATE unless Aussen_1 has attribute "stateFormat" defined.
    # If "stateFormat" is defined then a reading D will be generated.
    define dew_state dewpoint dewpoint Aussen_1 T H D

    # Compute the dewpoint for the temperature/humidity
    # events of all devices offering temperature and humidity
    # and insert the result into the STATE. (See example above).
    # Example STATE: "T: 10 H: 62.5" will change to
    # "T: 10 H: 62.5 D: 3.2"
    define dew_state dewpoint dewpoint .* T H D

    

define <name> dewpoint fan <devicename> <devicename-outside> <min-temp> [<diff_temp>]


May be used to turn an fan on or off if the outside air has less water.
• Generate event "fan: on" if (dewpoint of <devicename-outside>) + <diff_temp> is lower than dewpoint of <devicename> and temperature of <devicename-outside> is >= min-temp and reading "fan" was not already "on". The event will be generated for <devicename>. Parameter <diff-temp> is optional
• Generate event "fan: off": else and if reading "fan" was not already "off".

Example:

    # Generate event "fan: on" when dewpoint of Aussen_1 is first
    # time lower than basement_tempsensor and outside temperature is >= 0
    # and change it to "fan: off" is this condition changes.
    # Set a switch on/off (fan_switch) depending on the state.
    define dew_fan1 dewpoint fan basement_tempsensor Aussen_1 0
    define dew_fan1_on notify basement_tempsensor.*fan:.*on set fan_switch on
    define dew_fan1_off notify basement_tempsensor.*fan:.*off set fan_switch off

    

define <name> dewpoint alarm <devicename> <devicename-reference> <diff-temp>


Generate a mold alarm if a reference temperature is lower than the current dewpoint.
• Generate reading/event "alarm: on" if temperature of <devicename-reference> - <diff-temp> is lower than dewpoint of <devicename> and reading "alarm" was not already "on". The event will be generated for <devicename>.
• Generate reading/event "alarm: off" if temperature of <devicename-reference> - <diff-temp> is higher than dewpoint of <devicename> and reading "alarm" was not already "off".

Example:

    # Using a wall temperature sensor (wallsensor) and a temp/hum sensor
    # (roomsensor) to alarm if the temperature of the wall is lower than
    # the dewpoint of the air. In this case the water of the air will
    # condense on the wall because the wall is cold.
    # Set a switch on (alarm_siren) if alarm is on using notify.
    define dew_alarm1 dewpoint alarm roomsensor wallsensor 0
    define roomsensor_alarm_on notify roomsensor.*alarm:.*on set alarm_siren on
    define roomsensor_alarm_off notify roomsensor.*alarm:.*off set alarm_siren off

    # If you do not have a temperature sensor in/on the wall, you may also
    # compare the rooms dewpoint to the temperature of the same or another
    # inside sensor. Alarm is temperature is 5 degrees colder than the
    # inside dewpointinside.
    define dev_alarm2 dewpoint alarm roomsensor roomsensor 5

    

Set
N/A

Get
N/A

Attributes
• disable
• absoluteHumidity <reading_name>
In addition the absolute humidity in g/m³ will be computed as reading <reading_name>.


• vapourPressure <reading_name>
In addition the vapour pressure in hPa will be computed as reading <reading_name>.


• max_timediff
Maximum time difference in seconds allowed between the temperature and humidity values for a device. dewpoint uses the Readings for temperature or humidity if they are not delivered in the event. This is necessary for using dewpoint with event-on-change-reading. Also needed for sensors that do deliver temperature and humidity in different events like for example technoline sensors TX3TH.
If not set default is 1 second.

Examples:

		# allow maximum time difference of 60 seconds
		define dew_all dewpoint dewpoint .*
		attr dew_all max_timediff 60
    

dummy

[EN DE]

Define a dummy. A dummy can take via set any values. Used for programming.

Define
define <name> dummy

Example:
define myvar dummy
set myvar 7


Set
set <name> <value>
Set any value.

Get
N/A

Attributes
• disable
• disabledForIntervals
• readingList
  Space separated list of readings, which will be set, if the first argument of the set command matches one of them.
• setList
  Space separated list of commands, which will be returned upon "set name ?", so the FHEMWEB frontend can construct a dropdown and offer on/off switches. Example: attr dummyName setList on off
• useSetExtensions
  If set, and setList contains on and off, then the set extensions are available.
  Side-effect: if set, only the specified parameters are accepted, even if setList contains no on and off.
• setExtensionsEvent
  If set, the event will contain the command implemented by SetExtensions (e.g. on-for-timer 10), else the executed command (e.g. on).
• readingFnAttributes

echodevice

[EN DE]

Basic remote control for Amazon Echo devices. You can find the complete documentation here.

https://mwinkler.jimdo.com/smarthome/eigene-module/echodevice/

Define
define <name> echodevice <DeviceID> [DeviceType]
Example: define <Name> echodevice <Amazon account> <Amazon Kennwort>
Example: define <Name> echodevice

Set
• ...
  ...


Get
• settings
  Manually reload setings (dnd, bluetooth, wakeword)


• devices
  Displays a list of Amazon devices connected to your account

Readings
• ...
  ...



Attributes
• interval
  Poll interval in seconds (300)


• cookie
  Amazon access cookie, has to be entered for the module to work


• server
  Amazon server used for controlling the Echo

eventTypes

[EN DE]

Define
define <name> eventTypes <filename>

Collect event types for all devices. This service is used by frontends, e.g. notify and FileLog, to assist you in selecting the correct events. The filename is used to store the collected events before shutdown.
More than one instance of eventTypes should not be necessary. Examples:
define et eventTypes log/eventTypes.txt




Set
• flush
  used to write all collected event types into datafile.


• clear
  used to clear the internal table containing all collected event types.

Get
• list [devicename]
  listWithCounter [devicename]
  return the list of collected event types for all devices or for devicename if specified.

Attributes
• disable


• ignoreList
  Comma separated device names to ignore whe collecting the events. E.g. ECMD-Devices are used to post RAW data as events.

expandJSON

[EN DE]

Expand a JSON object from a reading into individual readings

• Requirements: perl module JSON
  Use "cpan install JSON" or operating system's package manager to install Perl JSON Modul. Depending on your os the required package is named: libjson-perl or perl-JSON. Additionally JSON::XS may be required if Boolean values (true/false) are missing. Package name for this lib is libjson-xs-perl or perl-JSON-XS.
• Decoding of JSON objects is fully implemented. JSON arrays are supported but may change in future a little bit...

Define


define <name> expandJSON <source_regex> [<target_regex>]


• <name>
  A name of your choice.


• <source_regex>
  Regexp that must match your devices, readings and values that contain the JSON strings. Regexp syntax is the same as used by notify and must not contain spaces.
  


• <target_regex>
  Optional: This regexp is used to determine whether the target reading is converted or not at all. If not set then all readings will be used. If set then only matching readings will be used. Regexp syntax is the same as used by notify and must not contain spaces.
  


• Examples:
  
  Source reading:
  device:\{.*} #state without attribute addStateEvent
device:state:.\{.*} #state with attribute addStateEvent
device:reading:.\{.*} #regular reading (typical application)

  
  Target reading:
  .*power.*
(Power|Current|Voltage|.*day)
  
  Complete definitions:
  define ej expandJSON device:reading:.\{.*} targetReading
define ej expandJSON Sonoff.*:ENERGY.*:.\{.*} (Power|.*day)
  


Set


N/A


Get


N/A


Attributes


• addReadingsPrefix
  Add source reading as prefix to new generated readings. Useful if you have more than one reading with a JSON string that should be converted.


• disable
  Used to disable this device.


• do_not_notify
  Do not generate events for converted readings at all. Think twice before using this attribute. In most cases, it is more appropriate to use event-on-change-reading in target devices.


• disabledForIntervals
• addStateEvent

fakeRoku

[EN DE]

This module allows you to add a 'fake' roku player device to a harmony hub based remote and to receive and process configured key presses in FHEM.

Notes:
• XML::Simple is needed.
• IO::Socket::Multicast is needed.
• The following 12 functions are available and can be used:
  • InstantReplay
  • Home
  • Info
  • Search
  • Back
  • FastForward = Fwd
  • Rewind = Rev
  • Select
  • DirectionUp
  • DirectionRight
  • DirectionLeft
  • DirectionDown


Define
define <name> fakeRoku


Set
none

Get
none

Attr
• favourites
  comma separated list of names to use as apps/channels/favourites. the list can be reloaded on the harmony with edit->reset.
• fhemIP
  overwrites autodetected local ip used in advertising
• httpPort
• reusePort
  not set -> set ReusePort on multicast socket if SO_REUSEPORT flag ist known. should work in most cases.
  0 -> don't set ReusePort on multicast socket
  1 -> set ReusePort on multicast socket
• serial

feels_like

[EN DE]

Computation of a 'feels like' temperature based on ambient temperature, humidity, wind speed and solar radiation.
While for a simple computation temperature, humidity, wind speed are sufficient this module is specifically tailored to support stations with the Fine Offset sensor array marketed under several names like



• Ambient Weather WS-1200 / IP-1400 / ...
• Froggit WS2601
• Renkforce WH2600


Most of them are supported by the module HP1000.

Algorithms providing a 'feels like' temperature work the following way:
• Compute the net extra radiation on the human body using environmental data, the position of the sun and the amount of cloud cover
  resulting in the Mean Radiant Temperature
• Make a complete heat balance of the human body including this extra radiation.
• Compare this to the heat balance of a walking person in the shadow with no wind and average humidity.
• The temperature where these two match defines the feels like, equivalent, or apparent temperature.

This implementation computes the short and long wave radiation parts based on the position of the sun.
Taking into account the solar radiation reading the amount of cloud cover is computed in Oktas.
Using this a Mean Radiant Temperature is computed that is consistent with the provided solar radiation reading.

Currently this module provides two different equivalent temperatures:

• Universal Temperature Climate Index
  Currently considered as the gold standard. It was created 2007 by a joint effort of world wide experts. See the pdf Poster for a quick introduction.
  
• Apparent Temperature
  An older standard developed by R. B. Steadman in the 1970s to 1990s and still in use in Australia and USA.
  

Define

define <name> feels_like <out-device> <temperature> <humidity> [<wind_speed> [<solarradiation> [<pressure>]]]


Calculates a 'feels like' temperatures for specified readings and writes them into new readings for device <out-device>.
Input readings can be specified as <device>:<reading>. At least one input reading must belong to <out-device>.

Input Readings

temperature	ambient temperature [°C]
humidity	ambient relative humidity [%]
wind_speed	speed of wind 10 m above ground (so be sure to calibrate accordingly) [m/s]
solarradiation	solar radiation [W/m^2]
pressure	pressure [hPa]



Generated Readings

temperature_utci	temperature according to UTCI [°C]
temperature_at	temperature according to Steadman [°C]
temperature_mrt	mean radiant temperature [°C]
extra_radiation	extra radiation on human body [W/m^2]



If <solarradiation> is specified as input parameter these readings are generated in addition:



coverage	cloud cover as value 0.0 -> 1.0
oktas	cloud cover in oktas 1 -> 8
clouds	letter code for coverage SKC -> OVC


The value for clouds is compatible with Wunderground and can be uploaded with field code "clouds".

Note:For cloud detection it is essential that an event for <solarradiation> is generated for each transmission of the weather station, i.e. each 16 seconds.

Example:

# Use full functionality for a wh2601 weather station
define wh2601_fl feels_like wh2601 temperature humidity wind_speed solarradiation pressure

# Use different sensors
define Thermo_1_fl feels_like Thermo_1 temperature Thermo_2:humidity WS_Sensor:wind_speed

Attributes


latitude, longitude, altitude	required	must be defined in global
maxTimediff	optional, should match installation	Maximum allowed time difference in seconds for readings of different sensors to be considered coherent (default: 600)
sensorSkyViewFactor	optional, should match installation	Fraction of sky that is visible to the sensor (default: 0.6)
skyViewFactor	optional, your personal choice	Fraction of visible sky to be used for computation of T_mrt (default: 0.7)
directRadiationRatio	optional, your personal choice	Fraction of direct insolation to be used for computation of T_mrt (default 0.4)
utciWindCutoff	optional, your personal choice	Max wind speed for UTCI computation (default: 3 m/s)
bowenRatio	optional, technical	Bowen ratio of environment (default 0.6 = grassland)
linkeTurbity	optional, technical	Linke Turbity of atmosphere. Value should be an array of 12 values ( = one value / month) (default: values for Frankfurt) You can find values for other locations here
sunVisibility	optional, should match installation	Comma separated list of azimuth/altitude values to describe whether the sun is visible (e.g. due to buildings, trees, ...). Must start with 0 and end with 360. E.g. 0,5,75,20.5,130,10,360 -> sun must be > 5° between 0 and 75° azimuth, then > 20.5° between 75° and 130° etc.
coverageCallback	optional, technical	Callback function for use with an additional infrared thermometer
sensorType	optional, technical	Type of sensor for applying specific corrections, values:wh2601,generic (default: wh2601)



If your environment is a
large paved parking lot use skyViewFactor = 1.0, directRadiationRatio = 1.0, bowenRatio = 5,
shadowy wetland use skyViewFactor = 0.2, directRadiationRatio = 0.2, bowenRatio = 0.2,
suburb, golf course... use the defaults.

Bibliography
P. Bröde et al. (2010): The Universal Thermal Climate Index UTCI in Operational Use
Proceedings of Conference: Adapting to Change: New Thinking on Comfort Cumberland Lodge, Windsor, UK, 9-11 April 2010 download

Andreas Matzarakis, Frank Rutz, Helmut Mayer (2010): Modelling radiation fluxes in simple and complex environments: basics of the RayMan model
Int J Biometeorol (2010) 54:131–139 download

Robert G. Steadman. (1994): Norms of apparent temperature in Australia.
Aust. Met. Mag., Vol 43, 1-16. download

John L. Monteith† and Mike H. Unsworth: Principles of Environmental Physics, Fourth Edition
Elsevier, Kidlington, UK, 2013

fhemdebug

[EN DE]

fhemdebug <command>

where <command> is one of
• enable/disable/status
  fhemdebug produces debug information in the FHEM Log to help localize certain error messages. Currently following errors are examined:
  - Error: >...< has no TYPE, but following keys: >...<
  
  As it frequently examines internal data-structures, it uses a lot of CPU, it is not recommended to enable it all the time. A FHEM restart after disabling it is not necessary.
  
• timerList
  show the list of InternalTimer calls.
• addTimerStacktrace {1|0}
  enable or disable the registering the stacktrace of each InternalTimer call. This stacktrace will be shown in the timerList command.
• sizeInFile [<num>]
  returns the name of the devices requiring the most space in storage. If [<num>] is omitted, the top 20 is returned.
  Note: the total wont include the comment lines.
• utf8check
  returns the list of strings with the internal utf8-bit set. Such strings may cause various problems.

fheminfo

[EN DE]

fheminfo [send]

fheminfo displays information about the system and FHEM definitions.

The optional parameter send transmitts the collected data to a central server in order to support the development of FHEM.
The submitted data is processed graphically. The results can be viewed on http://fhem.de/stats/statistics.html.
The IP address will not be stored in database, only used for region determination during send.

Features:

• ConfigType (configDB|configFILE)
• SVN rev number
• Operating System Information
• Installed Perl version
• Defined modules
• Defined models per module

Attributes

The following attributes are used only in conjunction with the send parameter. They are set on attr global.


• sendStatistics
  This attribute is used in conjunction with the update command.
  onUpdate: transfer of data on every update (recommended setting).
  manually: manually transfer of data via the fheminfo send command.
  never: prevents transmission of data at anytime.

freezemon

[EN DE]

FREEZEMON monitors - similar to PERFMON possible freezes, however FREEZEMON is a real module, hence it has:


• Readings - which might be logged for easier analysis
• Attributes - to influence the behaviour of the module
• additional functionality - which tries to identify the device causing the freeze
It's recommended to deactivate PERFMON once FREEZEMON is active. They anyways detect the same freezes thus everything would be duplicated.

Please note! FREEZEMON just does an educated guess, which device could have caused the freeze based on timers that were supposed to run. There might be a lot of other factors (internal or external) causing freezes. FREEZEMON doesn't replace a more detailed analysis. The module just tries to give you some hints what could be optimized.

Define
FREEZEMON will be defined without Parameters.

define <devicename> freezemon

With that freezemon is active (and you should see a message in the log)


Set
• inactive: disables the device (similar to attribute "disable", however without the need to save
• active: reactivates the device after it was set inactive
• clear:
  • statistics_all: clears the statistics (i.e. deletes all the readings created for statistics)
  • statistics_low: clears the statistics with low significance (see attribute fm_statistics_low)
  • all: clears all readings (including the list of the last 20 freezes.)
  • getFreezes: similar to "get freeze", however as a set command it can be used e.g. in webCmd Attribute
Get
• freeze: returns the last 20 freezes (in compact view, like in state) - This is for a quick overview. For detailed analysis the data should be logged.
• log: provides direct access to the logfiles written when fm_logFile is active
• statistic: Provides a nicer formatted overview of the top 20 devices from freeze statistics
Readings
• freezeTime: Duration of the freeze
• freezeDevice: List of functions(Devices) that possibly caused the freeze
• fcDay: cumulated no. of freezes per day
• ftDay: cumulated duration of freezes per day
• fcDayLast: stores cumulated no. of freezes of the last day (for daily plots). Due to technical reasons, freezes that occur shortly after midnight might still be taken into account for previous day.
• ftDayLast: stores cumulated duration of freezes of the last day (for daily plots). Due to technical reasons, freezes that occur shortly after midnight might still be taken into account for previous day.
• fs_.*_c: freeze statistics - count of freezes where the device was probably involved
• fs_.*_t: freeze statistics - cumulated time of freezes where the device was probably involved
• state: s:<startTime> e:<endTime> f:<Duration> d:<Devices>
;
Attributes
• fm_CatchFnCalls: if enabled, FHEM internal function calls are monitored additionally, in some cases this might give additional hints on who's causing the freeze. 0 means disabled, numbers >= 1 describe the loglevel for logging long running function calls.
• fm_CatchHttp: if enabled, callback functions of non-blocking http-calls are monitored additionally, in some cases this might give additional hints on who's causing the freeze, 0 means disabled, numbers >= 1 describe the loglevel for logging long running callback.
• fm_CatchCmds: if enabled, FHEM commands are monitored additionally, in some cases this might give additional hints on who's causing the freeze, 0 means disabled, numbers >= 1 describe the loglevel for logging long running commands.
• fm_extDetail: provides in some cases extended details for recognized freezes. In some cases it was reported that FHEM crashes, so please be careful.
• fm_freezeThreshold: Value in seconds (Default: 1) - Only freezes longer than fm_freezeThreshold will be considered as a freeze
• fm_forceApptime: When FREEZEMON is active, apptime will automatically be started (if not yet active)
• fm_ignoreDev: list of comma separated Device names. If all devices possibly causing a freeze are in the list, the freeze will be ignored (not logged)
• fm_ignoreMode: takes the values off,single or all. If you have added devices to fm_ignoreDev then ignoreMode acts as follows:
  all: A freeze will only be ignored, if all devices probably causing the freeze are part of the ignore list. This might result in more freezes being logged than expected.
  single: A freeze will be ignored as soon as one device possibly causing the freeze is listed in the ignore list. With this setting you might miss freezes.
  off: All freezes will be logged.
  If the attribute is not set, while the ignore list is maintained, mode "all" will be used.
• fm_log: dynamic loglevel, takes a string like 10:1 5:2 1:3 , which means: freezes > 10 seconds will be logged with loglevel 1 , >5 seconds with loglevel 2 etc...
• fm_logFile: takes a valid file name (like e.g. ./log/freeze-%Y%m%d-%H%M%S.log). If set, logs messages of loglevel 5 (even if global loglevel is < 5) before a freeze in separate file.
• fm_logExtraSeconds: usually the log starts approx. 1 second before the freeze. This attribute allows to extend that timeframe
• fm_logKeep: A number that defines how many logFiles should be kept. If set all logfiles except the latest n freezemon logfiles will be deleted regularly.
• fm_whitelistSub: Comma-separated list of subroutines that you're sure that don't cause a freeze. Whitelisted Subs do not appear in the "possibly caused by" list. Typically you would list subroutines here that frequently appear in the "possibly caused by" list, but you're really sure they are NOT the issue. Note: The subroutine is the initial part (before the devicename in brackets) in freezemon log messages.
• fm_statistics: activate/deactivate freeze statistics. Creates readings for each device that possibly caused a freeze and sums up occurences and duration of those freezes
• fm_statistics_low: Parametrization of clear statistics_low set command, format is c:t. With clear statistics_low all statistics-readings will be deleted where count is less or equal "c" AND cumulated duration is less or equal "t"
• disable: activate/deactivate freeze detection

gassistant

[EN DE]

Module to control the integration of Google Assistant devices with FHEM.

Notes:
• HOWTO for public FHEM Connect action: Google Assistant FHEM Connect
Set
• reload
  Reloads the devices and sends them to Google.
• createDefaultConfig
  creates a default gassistant-fhem.cfg file gassistantFHEM-config attribut if not already set.
• clearCredentials
  clears all stored credentials
• unregister
  unregister and delete all data in FHEM Connect


Get
Attr
• gassistantFHEM-auth
  the user:password combination to use to connect to fhem.
• gassistantFHEM-cmd
  The command to use as gassistant-fhem.
• gassistantFHEM-config
  The config file to use for gassistant-fhem.
• gassistantFHEM-log
  The log file to use for gassistant-fhem. For possible %-wildcards see FileLog.
.
• nrarchive
  see FileLog
.
• gassistantFHEM-params
  Additional gassistant-fhem cmdline params.
• gassistantName
  The name to use for a device with gassistant.
• realRoom
  The room name to use for a device with gassistant.

harmony

[EN DE]

Defines a device to integrate a Logitech Harmony Hub based remote control into fhem.

It is possible to: start and stop activities, send ir commands to devices, send keyboard input by bluetooth and smart keyboard usb dongles.

You probably want to use it in conjunction with the fakeRoku module.

Notes:
• JSON has to be installed on the FHEM host.
• For hubs with firmware version 3.x.y <username> and <password> are not required as no authentication with the logitech myharmony server is needed for the full functionality of this module.
• For hubs with firmware version 4.x.y <username> and <password> are required for device level control. Activit level control is (currently) still possible without authentication.
• activity and device names can be given as id or name. names can be given as a regex and spaces in names musst be replaced by a single '.' (dot).

Define
define <name> harmony [<username> <password>] <ip>

Defines a harmony device.

Examples:
define hub harmony 10.0.1.4


Readings
• currentActivity
  the name of the currently selected activity.
• previousActivity
  the name of the previous selected activity. does not trigger an event.
• newVersion
  will be set if a new firmware version is avaliable.

Internals
• currentActivityID
  the id of the currently selected activity.
• previousActivityID
  the id of the previous selected activity.
• sleeptimer
  timeout for sleeptimer if any is set.

Set
• activity <id>|<name> [<channel>]
  switch to this activit and optionally switch to <channel>
• channel <channel>
  switch to <channel> in the current activity
• command [<id>|<name>] <command> [duration=<duration>]
  send the given ir command for the current activity or for the given device
• getConfig
  request the configuration from the hub
• getCurrentActivity
  request the current activity from the hub
• off
  switch current activity off
• reconnect [all]
  close connection to the hub and reconnect, if all is given also reconnect to the logitech server
• sleeptimer [<timeout>]
  <timeout> -> timeout in minutes
  -1 -> timer off
  default -> 60 minutes
• sync
  syncs the hub to the myHarmony config
• hidDevice [<id>|<name>]
  sets the target device for keyboard commands, if no device is given -> set the target to the default device for the current activity.
• text <text>
  sends <text> by bluetooth/smart keaboard dongle. a-z ,A-Z ,0-9, \n, \e, \t and space are currently possible
• cursor <direction>
  moves the cursor by bluetooth/smart keaboard dongle. <direction> can be one of: up, down, left, right, pageUp, pageDown, home, end.
• special <key>
  sends special key by bluetooth/smart keaboard dongle. <key> can be one of: previousTrack, nextTrack, stop, playPause, volumeUp, volumeDown, mute.
• autocreate [<id>|<name>]
  creates a fhem device for a single/all device(s) in the harmony hub. if activities are startet the state of these devices will be updatet with the power state defined in these activites.
• update
  triggers a firmware update. only available if a new firmware is available.
• inactive
  inactivates the current device. note the slight difference to the disable attribute: using set inactive the state is automatically saved to the statefile on shutdown, there is no explicit save necesary.
  this command is intended to be used by scripts to temporarily deactivate the harmony device.
  the concurrent setting of the disable attribute is not recommended.
• active
  activates the current device (see inactive).
The command, hidDevice, text, cursor and special commmands are also available for the autocreated devices. The <id>|<name> paramter hast to be omitted.

Get
• activites [<param>]
  lists all activities
  parm = power -> list power state for each device in activity
• devices [<param>]
  lists all devices
• commands [<id>|<name>]
  lists the commands for the specified activity or for all activities
• deviceCommands [<id>|<name>]
  lists the commands for the specified device or for all devices
• activityDetail [<id>|<name>]
• deviceDetail [<id>|<name>]
• configDetail
• currentActivity
  returns the current activity name
• showAccount
  display obfuscated user and password in cleartext
The commands commmand is also available for the autocreated devices. The <id>|<name> paramter hast to be omitted.

Attributes
• forceWebSocket
  1 -> use websocket interface even if xmpp availability is dicovered
• disable
  1 -> disconnect from the hub

?, help

[EN DE]

?    [<commandName|moduleName|deviceName>] [<language>]
help [<commandName|moduleName|deviceName>] [<language>]


• Returns a list of available commands, when called without a moduleName/deviceName.
• Returns a module/command dependent helptext, same as in commandref.
• language will be determined in following order:
  • valid parameter <language> given
  • global attribute language
  • nothing founde: return english

holiday

[EN DE]

Define
define <name> holiday

Define a set of holidays. The module will try to open the file <name>.holiday in the modpath/FHEM directory first, then in the modpath/FHEM/holiday directory, the latter containing a set of predefined files. This list of available holiday files will be shown if an error occurs at the time of the definition, e.g. if you type "define help holiday"
If entries in the holiday file match the current day, then the STATE of this holiday instance displayed in the list command will be set to the corresponding values, else the state is set to the text none. Most probably you'll want to query this value in some perl script: see Value() in the perl section or the global attribute holiday2we.
Note: since March 2019 the IsWe() function (and $we) are accessing the state, tomorrow and yesterday readings, and not the STATE internal.
The file will be reread once every night, to compute the value for the current day, and by each get command (see below).

Holiday file definition:
The file may contain comments (beginning with #) or empty lines. Significant lines begin with a number (type) and contain some space separated words, depending on the type. The different types are:

• 1
  Exact date. Arguments: <MM-DD> <holiday-name>
  Exampe: 1 12-24 Christmas
  MM-DD can also be written as YYYY-MM-DD.
• 2
  Easter-dependent date. Arguments: <day-offset> <holiday-name>. The offset is counted from Easter-Sunday.
  Exampe: 2 1 Easter-Monday
  Sidenote: You can check the easter date with: fhem> { join("-", western_easter(2011)) }
• 3
  Month dependent date. Arguments: <nth> <weekday> <month <holiday-name>.
  Examples:
  
  3 1 Mon 05 First Monday In May
  3 2 Mon 05 Second Monday In May
  3 -1 Mon 05 Last Monday In May
  3 0 Mon 05 Each Monday In May
  
• 4
  Interval. Arguments: <MM-DD> <MM-DD> <holiday-name> .
  Note: An interval cannot contain the year-end. Example:
  
  4 06-01 06-30 Summer holiday
  4 12-20 01-10 Winter holiday # DOES NOT WORK. Use the following 2 lines instead:
  4 12-20 12-31 Winter holiday
  4 01-01 01-10 Winter holiday
  
  MM-DD can also be written as YYYY-MM-DD.
• 5
  Date relative, weekday fixed holiday. Arguments: <nth> <weekday> <month> <day> < holiday-name>
  Note that while +0 or -0 as offsets are not forbidden, their behaviour is undefined in the sense that it might change without notice.
  Examples:
  
  5 -1 Wed 11 23 Buss und Bettag (first Wednesday before Nov, 23rd)
  5 1 Mon 01 31 First Monday after Jan, 31st (1st Monday in February)
  
• 6
  Use a perl function to calculate a date. Function must return the result as an exact date in format "mm-dd", e.g. "12-02"
  
  Example:
  
  6 calcAdvent 21 1.Advent
6 calcAdvent 14 2.Advent
6 calcAdvent 7 3.Advent
6 calcAdvent 0 4.Advent

  
  Explanation:
  
  calcAdvent = name of function, e.g. included in 99_myUtils.pm
21 = parameter given to function
1.Advent = text to be shown in readings

  
  this will call "calcAdvent(21)" to calculate a date.
  Errors will be logged in Loglevel 1.
  

Set
• createPrivateCopy
  
  if the holiday file is opened from the FHEM/holiday directory (which is refreshed by FHEM-update), then it is readonly, and should not be modified. With createPrivateCopy the file will be copied to the FHEM directory, where it can be modified.
• deletePrivateCopy
  
  delete the private copy, see createPrivateCopy above
• reload
  
  set the state, tomorrow and yesterday readings. Useful after manually editing the file.

Get
get <name> <YYYY-MM-DD>
get <name> <MM-DD>
get <name> yesterday
get <name> today
get <name> tomorrow
get <name> days <offset>


Return the holiday name of the specified date or the text none.



Attributes
N/A

inotify

[EN DE]

This module collects file events in a given path. Inotify (inode notify) is a Linux kernel subsystem that
acts to extend filesystems to notice changes to the filesystem, and report those changes to applications

Notes:

• Perl modules Data::Dumper, Linux::Inotify2, File::Find have to be installed on the FHEM host.



Define

define <name> inotify <path> [<file-RegEx>]


• path: absolute path to watch
• file-RegEx: file-Pattern (only watch a group of files)


Example:
define watchPath inotify /temp testfile.*



Set

• active - set active - watching starts
• inactive - set iactive - watching stops



Attributes

• readingFnAttributes
• do_not_notify
• disable
• subfolders
  set to 1 if you want to watch all subfolders of the given path.
  
• mask
  set your own mask for watching. Komma seperated list. See the Linux::Inotify2 Doku for possible masks.
  
  

Readings

• lastEventFile
  the last modified file
• lastEventMask
  the last mask we got in the event
• state
  device is active or inactive

KM200

[EN DE]

The Buderus KM200, KM100 or KM50 (hereafter described as KMxxx) is a communication device to establish a connection between the Buderus central heating control unit and the internet. It has been designed in order to allow the inhabitants accessing their heating system via his Buderus App EasyControl. Furthermore it allows the maintenance companies to access the central heating control system to read and change settings. The km200 fhem-module enables read/write access to these parameters. In order to use the KMxxx with fhem, you must define the private password with the Buderus App EasyControl first. Remark: Despite the instruction of the Buderus KMxxx Installation guide, the ports 5222 and 5223 should not be opened and allow access to the KMxxx module from outside. You should configure (or leave) your internet router with the respective settings. If you want to read or change settings on the heating system, you should access the central heating control system via your fhem system only. As soon the module has been defined within the fhem.cfg, the module is trying to obtain all known/possible services. After this initial contact, the module differs between a set of continuous (dynamically) changing values (e.g.: temperatures) and not changing static values (e.g.: Firmware version). This two different set of values can be bound to an individual polling interval. Refer to Attributes




Define
define <name> km200 <IPv4-address> <GatewayPassword> <PrivatePassword>
<name> :	The name of the device. Recommendation: "myKm200".
<IPv4-address> :	A valid IPv4 address of the KMxxx. You might look into your router which DHCP address has been given to the KMxxx.
<GatewayPassword> :	The gateway password which is provided on the type sign of the KMxxx.
<PrivatePassword> :	The private password which has been defined by the user via EasyControl.




Set
The set function is able to change a value of a service which has the "writeable" - tag within the KMxxx service structure. Most of those values have an additional list of allowed values which are the only ones to be set. Other floatable type values can be changed only within their range of minimum and maximum value.
set <service> <value>
<service> :	The name of the service which value shall be set. E.g.: "/heatingCircuits/hc1/operationMode"
<value> :	A valid value for this service.




Get
The get function is able to obtain a value of a service within the KMxxx service structure. The additional list of allowed values or their range of minimum and maximum value will not be handed back.
get <service> <option>
<service> :	The name of the service which value shall be obtained. E.g.: "/heatingCircuits/hc1/operationMode"   It returns only the value but not the unit or the range or list of allowed values possible.
<option> :	The optional Argument for the result of the get-command e.g.: "json"   The following options are available:   json - Returns the raw json-answer from the KMxxx as string.




Attributes

The following user attributes can be used with the km200 module in addition to the global ones e.g. room.

IntervalDynVal : A valid polling interval for the dynamically changing values of the KMxxx. The value must be >=20s to allow the km200 module to perform a full polling procedure. The default value is 300s.

PollingTimeout : A valid time in order to allow the module to wait for a response of the KMxxx. Usually this value does not need to be changed but might in case of slow network or slow response. The default and minimum value is 5s.

DoNotPoll : A list of services separated by blanks which shall not be downloaded due to repeatable crashes or irrelevant values. The list can be filled with the name of the top - hierarchy service, which means everything below that service will also be ignored. The default value (empty) therefore nothing will be ignored.

ReadBackDelay : A valid time in milliseconds [ms] for the delay between writing and re-reading of values after using the "set" - command. The value must be >=0ms. The default value is 100 = 100ms = 0,1s.

disable : Stops the device from further pollings and deletes the existing readings. The default value is 0 = activated

livetracking

[EN DE]

This modul pulls livetracking data from Life360 and Swarm (FourSquare).
Data can also be pushed from OwnTracks or Traccar (iOS).
Swarm Token: https://foursquare.com/oauth2/authenticate?client_id=EFWJ0DNVIREJ2CY1WDIFQ4MAL0ZGZAZUYCNE0NE0XZC3NCPX&response_type=token&redirect_uri=http://localhost&display=wap

Define
define <name> livetracking <...>
Example: define livetrackingdata livetracking [life360_email] [life360_pass] [swarm_token]
Any combination of these services can be defined as long as their order is correct.
 
• ...
  Reverse geocoding: Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright



Get
• All
  Manually trigger a data update for all sources (Life360/Swarm)


• Life360
  Manually trigger a data update for Life360


• Swarm
  Manually trigger a data update for Swarm


• owntracksLocation
  Request position from OwnTracks


• owntracksSteps
  Request steps data from OwnTracks


• address [<lat,lng>/short/long]
  Get an address from coordinates
  



Set
• owntracksMessage
  Send a message to OwnTracks


• bootstrapLife360
  Re-initialize Life360 login data



Readings
• location
  GPS position


• latitude
  GPS position - latitude


• longitude
  GPS position - longitude


• distance (km)
  GPS distance from home


• accuracy (m)
  GPS accuracy


• altitude (m)
  GPS altitude


• velocity (km/h)
  GPS velocity


• heading (deg)
  GPS heading


• place
  Swarm place name


• steps (steps)
  iOS walked steps


• walking (m)
  iOS walked distance


• floorsup (floors)
  iOS floors walked up


• floorsdown (floors)
  iOS floors walked down


• zone_N (active/inactive)
  Zone status in OwnTracks


• beacon
  Beacon ID from OwnTracks


• beacon_N_X
  Beacon data for saved beacons for indoor positioning


• batteryState (ok/low)
  Battery state (can be set through attribute batteryWarning )


• batteryPercent (%)
  Battery percentage


• connection (mobile/wifi/offline/unknown)
  Phone connection type from OwnTracks at last position



Attributes
• batteryWarning (%)
  Set battery ok/low threshold


• beacon_N
  Saved beacon IDs from OwnTracks for indoor positioning, e.g.:
  FDA50693-A4E2-4FB1-AFCF-C6EB07647825,19789,1


• zonename_N
  Assign zone name from OwnTracks


• home (lat,lon)
  Home location


• swarmHome/SwarmHomeName (lat,lon)
  Fake home location or name (that is assigned to private homes for security reasons) of your Swarm home (exact position)


• filterAccuracy (m)
  Minimum accuracy of GPS location to update any readings


• roundDistance (km)
  Rounding for distance reading to prevent too many changes


• roundAltitude (m)
  Rounding for altitude reading to prevent too many changes


• owntracksDevice
  OwnTracks MQTT device to look for notifies from


• addressLanguage (de/en/fr/es/it/nl)
  Preferred language used to return reverse geocoding results


• addressReading (0/1)
  Write reverse geocoding results to address reading


• osmandServer (0/1)
  Starts an OsmAnd compatible listener on FHEM which can be entered into traccar-client directly.
  This is also compatible with OwnTracks HTTP mode.
  Traccar for Android supports no authentication, OwnTracks may need separate fields instead of user:pass in the address
  https://user:pass@your.fhem.ip/fhem/osmand (address to be entered in the client)


• osmandId (if more than one instance is used)
  The device identifier that is set in the OsmAnd client and transmitted in the request as id
  If OwnTracks HTTP mode is used, this can be the TrackerID

logProxy

[EN DE]

Allows the manipulation of data to be plotted in an SVG device:
• addition of horizontal lines at fixed values
• addition of horizontal lines at dynamic values eg: min, max or average values of another plot
• addition of vertical lines at fixed or dynamic times between two fixed or dynamic y values
• addition of calculated data like week profiles of HeatingControll devices or heating thermostats
• merge plot data from different sources. eg. different FileLog devices
• horizontaly shifting a (merged) plot to align average or statistic data to the correct day,week and month

Define
define <name> logProxy

Only one logProxy device can be defined and is needed.

Example:
define myProxy logProxy


Set

Get
see FileLog and DbLog

Attributes


#logProxy <column_spec>
where <column_spec> can be one or more of the following:
• FileLog:<log device>[,<options>]:<column_spec>
  
• DbLog:<log device>[,<options>]:<column_spec>
  

options is a comma separated list of zero or more of:

• clip
  clip the plot data to the plot window
• extend=<value>
  extend the query range to the log device by <value> seconds (or <value> months if <value> ends in m). also activates cliping.
• interpolate
  perform a linear interpolation to the values in the extended range to get the values at the plot boundary. only usefull if plotfunction is lines.
• offset=<value>
  shift plot by <value> seconds (or <value> months if <value> ends in m). allows alignment of values calculated by average or statsitics module to the correct day, week or month.
• predict[=<value>]
  no value -> extend the last plot value to now.
  value -> extend the last plot value by <value> but maximal to now.
  
• postFn='<myPostFn>'
  myPostFn is the name of a postprocessing function that is called after all processing of the data by logProxy has been done. it is called with two arguments: the devspec line from the gplot file and a reference to a data array containing the points of the plot. each point is an array with three components: the point in time in seconds, the value at this point and the point in time in string form. the return value must return a reference to an array of the same format. the third component of each point can be omittet and is not evaluated.
  
• scale2reading=<scaleHashRef>
  Use zoom step dependent reading names.
  The reading name to be used is the result of a lookup with the current zoom step into scaleHashRef. The keys can be from the following list: year, month, week, day, qday, hour
  Example:
  #logProxy DbLog:dbLog,scale2reading={year=>'temperature_avg_day',month=>'temperature_avg_day'}:s300ht_1:temperature::
  
  
  
  
• ConstX:<time>,<y>[,<y2>]
  Will draw a vertical line (or point) at <time> between <y> to <y2>.
  Everything after the : is evaluated as a perl expression that hast to return one time string and one or two y values.
  Examples:
  #logProxy ConstX:$data{currdate1},$data{currval1}
#logProxy ConstX:$data{mindate1},$data{min1},$data{avg1}
#logProxy ConstX:$data{maxdate1},$data{max1},$data{avg1}
#logProxy ConstX:logProxy_shiftTime($from,60*60*2),$data{min1},$data{max1}
  


• ConstY:<value>[,<from>[,<to>]]
  Will draw a horizontal line at <value>, optional only between the from and to times.
  Everything after the : is evaluated as a perl expression that hast to return one value and optionaly one or two time strings.
  Examples:
  #logProxy ConstY:0
#logProxy ConstY:1234+15+myFunc(123)
#logProxy ConstY:$data{avg1}
#logProxy ConstY:$data{avg2},$from,$to
#logProxy ConstY:$data{avg2},logProxy_shiftTime($from,60*60*12),logProxy_shiftTime($from,-60*60*12)


• Polar:[<options>]:<values>
  Will draw a polar/spiderweb diagram with the given values. <values> has to evaluate to a perl array.
  If <values> contains numbers these values are plottet and the last value will be connected to the first.
  If <values> contains strings these strings are used as labels for the segments.
  The axis are drawn automaticaly if the values are strings or if no values are given but the segments option is set.
  The corrosponding SVG device should have the plotsize attribute set (eg: attr <mySvg> plotsize 340,300) and the used gplot file has to contain xrange and yrange entries and the x- and y-axis labes should be switched off with xtics, ytics and y2tics entries.
  The following example will plot the temperature and desiredTemperature values of all devices named MAX.*:
  set xtics ()
set ytics ()
set y2tics ()
set xrange [-40:40]
set yrange [-40:40]

#logProxy Polar::{[map{ReadingsVal($_,"temperature",0)}devspec2array("MAX.*")]}
#logProxy Polar::{[map{ReadingsVal($_,"desiredTemperature",0)}devspec2array("MAX.*")]}
#logProxy Polar::{[map{ReadingsVal($_,"temperature",0)}devspec2array("MAX.*")]}
#logProxy Polar::{[devspec2array("MAX.*")]}

plot "<IN>" using 1:2 axes x1y1 title 'Ist' ls l0 lw 1 with lines,\
plot "<IN>" using 1:2 axes x1y1 title 'Soll' ls l1fill lw 1 with lines,\
plot "<IN>" using 1:2 axes x1y1 notitle ls l0 lw 1 with points,\
plot "<IN>" using 1:2 axes x1y1 notitle ls l2 lw 1 with lines,\
  
  
  options is a comma separated list of zero or more of:
  
  • axis
    force to draw the axis
  • noaxis
    disable to draw the axis
  • range=<value>
    the range to use for the radial axis
  • segments=<value>
    the number of circle/spiderweb segments to use for the plot
  • isolines=<value>
    a | separated list of values for which an isoline shoud be drawn. defaults to 10|20|30.


• Func:<perl expression>
  Specifies a perl expression that returns the data to be plotted and its min, max and last value. It can not contain space or : characters. The data has to be one string of newline separated entries of the form: yyyy-mm-dd_hh:mm:ss value
  Example:
  #logProxy Func:logProxy_WeekProfile2Plot("HCB",$from,$to)
#logProxy Func:logProxy_WeekProfile2Plot("myHeatingControll",$from,$to,"(\\d)*\$")
#logProxy Func:logProxy_Func2Plot($from,$to,'{logProxy_hms2dec(sunrise_abs_dat($sec))}')
#logProxy Func:logProxy_Func2Plot($from,$to,'{logProxy_hms2dec(sunset_abs_dat($sec))}')
  
  
  Notes:
  • logProxy_WeekProfile2Plot is a sample implementation of a function that will plot the week profile of a Heating_Control, WeekdyTimer, HomeMatic or MAX Thermostat device can be found in the 98_logProxy.pm module file.
  • logProxy_Func2Plot($from,$to,$func) is a sample implementation of a function that will evaluate the given function (3rd parameter) for a zoom factor dependent number of times. the current time is given in $sec. the step width can be given in an optional 4th parameter. either as a number or as an hash with the keys from the following list: hour,qday,day,week,month,year and the values representing the step with for the zoom level.
  • logProxy_xy2Plot(\@xyArray) is a sample implementation of a function that will accept a ref to an array of xy-cordinate pairs as the data to be plotted.
  • logProxy_xyFile2Plot($filename,$column,$regex) is a sample implementation of a function that will accept a filename, a column number and a regular expression. The requested column in all lines in the file that match the regular expression needs to be in the format x,y to indicate the xy-cordinate pairs as the data to be plotted.
  • logProxy_values2Plot(\@xyArray) is a sample implementation of a function that will accept a ref to an array of date-y-cordinate pairs as the data to be plotted.
  • The perl expressions have access to $from and $to for the begining and end of the plot range and also to the SVG specials min, max, avg, cnt, sum, firstval (first value), lastval (last value), currval (last value) and currdate (last date) values of the individual curves already plotted are available as $data{<special-n>}.
    
  • logProxy_Range2Zoom($seconds) can be used to get the approximate zoom step for a plot range of $seconds.
  • SVG_time_to_sec($timestamp) can be used to convert the timestamp strings to epoch times for calculation.



Please see also the column_spec paragraphs of FileLog, DbLog and SVG.

NOTE: spaces are not allowed inside the colums_specs.

To use any of the logProxy features with an existing plot the associated SVG file hast to be changed to use the logProxy device and the .gplot file has to be changed in the following way:
All existing #FileLog and #Dblog lines have to be changed to #logProxy lines and
the column_spec of these line has to be prepended by FileLog:<log device>: or DbLog:<log device>: respectively.
Examples:
#DbLog <myDevice>:<myReading>
#FileLog 4:<SPEC1>:power\x3a::
#FileLog 4:<SPEC1>:consumption\x3a::

will become:

#logProxy DbLog:<myDb>:<myDevice>:<myReading>
#logProxy FileLog:FileLog_<SPEC1>:4:<SPEC1>.power\x3a::
#logProxy FileLog:FileLog_<SPEC1>:4:<SPEC1>.consumption\x3a::

mailcheck

[EN DE]

Watches a mailbox with imap idle and for each new mail triggers an event with the subject of this mail.

This can be used to send mails *to* FHEM and react to them from a notify. Application scenarios are for example a geofencing apps on mobile phones, networked devices that inform about warning or failure conditions by e-mail or (with a little logic in FHEM) the absence of regular status messages from such devices and so on.

Notes:
• Mail::IMAPClient and IO::Socket::SSL and IO::Socket::INET hast to be installed on the FHEM host.
• Probably only works reliably if no other mail programm is marking messages as read at the same time.
• If you experience a hanging system caused by regular forced disconnects of your internet provider you can disable and enable the mailcheck instance with an at.
• If MIME::Parser is installed non ascii subjects will be docoded to utf-8
• If MIME::Parser and Mail::GnuPG are installed gpg signatures can be checked and mails from unknown senders can be ignored.

Define
define <name> mailcheck <host> <user> <password> [<folder>]

<user> and <password> can be of the form {perl-code}. no spaces are allowed. for both evals $NAME and $HOST is set to the name and host of the mailcheck device and $USER is set to the user in the password eval.
Defines a mailcheck device.

Examples:
define mailcheck mailcheck imap.mail.me.com x.y@me.com myPassword
define mailcheck mailcheck imap.mail.me.com {"x.y@me.com"} {myPasswordOfAccount($USER)}


Readings
• Subject
  the subject of the last mail received
• From
  the mail address of the last sender

Set
• inactive
  temporarily deactivates the device
• active
  reenables the device

Get
• update
  trigger an update
• folders
  list available folders

Attributes
• delete_message
  1 -> delete message after Subject reading is created
• interval
  the interval in seconds used to trigger an update on the connection. if idle is supported the defailt is 600, without idle support the default is 60. the minimum is 60.
• nossl
  1 -> don't use ssl.


• disable
  1 -> disconnect and stop polling
• debug
  1 -> enables debug output. default target is stdout.
• logfile
  set the target for debug messages if debug is enabled.
• accept_from
  comma separated list of gpg keys that will be accepted for signed messages. Mail::GnuPG and MIME::Parser have to be installed

monitoring

[EN DE]

Each monitoring has a warning- and an error list, which are stored as readings.
When a defined add-event occurs, the device is set to the warning list after a predefined time.
After a further predefined time, the device is deleted from the warning list and set to the error list.
If a defined remove-event occurs, the device is deleted from both lists and still running timers are canceled.
This makes it easy to create group messages and send them formatted by two attributes.

The following applications are possible and are described below:

• opened windows
• battery warnings
• activity monitor
• regular maintenance (for example changing the table water filter or cleaning rooms)
• operating hours dependent maintenance (for example clean the Beamer filter)

The monitor does not send a message by itself, a notify or DOIF is necessary, which responds to the event "<monitoring-name> error add: <name>" and then sends the return value of "get <monitoring-name> default".


Define

define <name> monitoring <add-event> [<remove-event>]
The syntax for <add-event> and <remove-event> is the same as the pattern for notify (device-name or device-name:event).
If only an <add-event> is defined, the device is deleted from both lists as it occurs and the timers for warning and error are started.


Set

• active
  Two things will happen:
  1. Restores pending timers, or sets the devices immediately to the corresponding list if the time is in the past.
  2. Executes the commands specified under the "setActiveFunc" attribute.
• clear (warning|error|all)
  Removes all devices from the specified list and aborts timers for this list. With "all", all devices are removed from both lists and all running timers are aborted.
• errorAdd <name>
  Add <name> to the error list.
• errorRemove <name>
  Removes <name> from the error list.
• inactive
  Two things will happen:
  1. Executes the commands specified under the "setInactiveFunc" attribute.
  2. Inactivates the current device. Note the slight difference to the disable attribute: using set inactive the state is automatically saved to the statefile on shutdown, there is no explicit save necesary.
• warningAdd <name>
  Add <name> to the warning list.
• warningRemove <name>
  Removes <name> from the warning list.

Get

• all
  Returns the error and warning list, separated by a blank line.
  The formatting can be set with the attributes "errorReturn" and "warningReturn".
• default
  The "default" value can be set in the attribute "getDefault" and is intended to leave the configuration for the return value in the monitoring device. If nothing is specified "all" is used.
• error
  Returns the error list.
  The formatting can be set with the attribute "errorReturn".
• warning
  Returns the warning list.
  The formatting can be set with the attribute "warningReturn".

Readings



• allCount
  Displays the amount of devices on the warning and error list..
• error
  Comma-separated list of devices.
• errorAdd_<name>
  Displays the time when the device will be set to the error list.
• errorCount
  Displays the amount of devices on the error list.
• state
  Displays the status (active, inactive, or disabled). In "active" it displays which device added to which list or was removed from which list.
• warning
  Comma-separated list of devices.
• warningAdd_<name>
  Displays the time when the device will be set to the warning list.
• warningCount
  Displays the amount of devices on the warning list.

Attributes

• addStateEvent
• blacklist <devspec list>
  Space-separated list of devspecs which will be ignored.
  If the attribute is set all devices which are specified by the devspecs are removed from both lists.
• disable (1|0)
  1: Executes the commands specified under the "setInactiveFunc" attribute and disables the monitoring.
  0: see "set active"
• disabledForIntervals HH:MM-HH:MM HH:MM-HH-MM ...
• errorFuncAdd {<perl code>}
  The following variables are available in this function:
  
  • $name
    Name of the event triggering device
  • $event
    Includes the complete event, e.g. measured-temp: 21.7 (Celsius)
  • $addMatch
    Has the value 1 if the add-event is true
  • $removeMatch
    Has the value 1 if the remove-event is true
  • $SELF
    Name of the monitoring
  If the function returns a 1, the device is set to the error list after the wait time.
  If the attribute is not set, it will be checked for $addMatch.
• errorFuncAdded {<perl code>}
  The following variables are available in this function:
  
  • $name
    Name of the event triggering device
  • $SELF
    Name of the monitoring
  This function will be executed when a device is added to the error list.
• errorFuncRemove {<perl code>}
  This function provides the same variables as for "errorFuncAdd".
  If the function returns a 1, the device is removed from the error list and still running timers are canceled.
  If the attribute is not set, it will be checked for $removeMatch if there is a <remove-event> in the DEF, otherwise it will be checked for errorFuncAdd.
• errorWait <perl code>
  Code returning waiting time (in seconds) until the device is set to the error list.
• errorReturn {<perl code>}
  The following variables are available in this attribute:
  • @errors
    Array with all devices on the error list.
  • @warnings
    Array with all devices on the warning list.
  • $SELF
    Name of the monitoring
  With this attribute the output created with "get <name> error" can be formatted.
  Note: As evaluation is done in package context, using functions from main may require redirection in lexical main context (e.g. use double colons "::myFunction($SELF)").
• getDefault (all|error|warning)
  This attribute can be used to specify which list(s) are / are returned by "get <name> default". If the attribute is not set, "all" will be used.
• setActiveFunc <statement>
  The statement is one of the FHEM command types and is executed when you define the monitoring or "set active".
  For a battery message "trigger battery=low battery: low" can be useful.
• setInactiveFunc <statement>
  The statement is one of the FHEM command types and is executed when you define the monitoring or "set inactive".
• warningFuncAdd {<perl code>}
  Like errorFuncAdd, just for the warning list.
• warningFuncAdded {<perl code>}
  Like errorFuncAdded, just for the warning list.
• warningFuncRemove {<perl code>}
  Like errorFuncRemove, just for the warning list.
• warningWait <perl code>
  Like errorWait, just for the warning list.
• warningReturn {<perl code>}
  Like errorReturn, just for the warning list.
• whitelist <devspec list>
  Space-separated list of devspecs which are allowed.
  If the attribute is set all devices which are not specified by the devspecs are removed from both lists.
• readingFnAttributes

Examples

The following sample codes can be imported via "Raw definition".


• Global, flexible opened windows/doors message (similar to those described in the forum)
  

  defmod Fenster_monitoring monitoring .*:(open|tilted) .*:closed
  attr Fenster_monitoring errorReturn {return if !@errors;;\
   $_ = AttrVal($_, 'alias', $_) for @errors;;\
   return("Das Fenster \"$errors[0]\" ist schon länger geöffnet.") if(int(@errors) == 1);;\
   @errors = sort {lc($a) cmp lc($b)} @errors;;\
   return(join("\n - ", "Die folgenden ".@errors." Fenster sind schon länger geöffnet:", @errors))\
  }
  attr Fenster_monitoring errorWait {AttrVal($name, "winOpenTimer", 60*10)}
  attr Fenster_monitoring warningReturn {return if !@warnings;;\
   $_ = AttrVal($_, 'alias', $_) for @warnings;;\
   return("Das Fenster \"$warnings[0]\" ist seit kurzem geöffnet.") if(int(@warnings) == 1);;\
   @warnings = sort {lc($a) cmp lc($b)} @warnings;;\
   return(join("\n - ", "Die folgenden ".@warnings." Fenster sind seit kurzem geöffnet:", @warnings))\
  }

  As soon as a device triggers an "open" or "tilded" event, the device is set to the warning list and a timer is started after which the device is moved from the warning to the error list. The waiting time can be set for each device via userattr "winOpenTimer". The default value is 10 minutes.
  As soon as a device triggers a "closed" event, the device is deleted from both lists and still running timers are stopped.


• Battery monitoring
  

  defmod Batterie_monitoring monitoring .*:battery:.low .*:battery:.ok
  attr Batterie_monitoring errorReturn {return if !@errors;;\
   $_ = AttrVal($_, 'alias', $_) for @errors;;\
   return("Bei dem Gerät \"$errors[0]\" muss die Batterie gewechselt werden.") if(int(@errors) == 1);;\
   @errors = sort {lc($a) cmp lc($b)} @errors;;\
   return(join("\n - ", "Die folgenden ".@errors." Geräten muss die Batterie gewechselt werden:", @errors))\
  }
  attr Batterie_monitoring errorWait 60*60*24*14
  attr Batterie_monitoring warningReturn {return if !@warnings;;\
   $_ = AttrVal($_, 'alias', $_) for @warnings;;\
   return("Bei dem Gerät \"$warnings[0]\" muss die Batterie demnächst gewechselt werden.") if(int(@warnings) == 1);;\
   @warnings = sort {lc($a) cmp lc($b)} @warnings;;\
   return(join("\n - ", "Die folgenden ".@warnings." Geräten muss die Batterie demnächst gewechselt werden:", @warnings))\
  }

  As soon as a device triggers a "battery: low" event, the device is set to the warning list and a timer is started after which the device is moved from the warning to the error list. The waiting time is set to 14 days.
  As soon as a device triggers a "battery: ok" event, the device is deleted from both lists and still running timers are stopped.


• Activity Monitor
  

  defmod Activity_monitoring monitoring .*:.*
  attr Activity_monitoring errorReturn {return if !@errors;;\
   $_ = AttrVal($_, 'alias', $_) for @errors;;\
   return("Das Gerät \"$errors[0]\" hat sich seit mehr als 24 Stunden nicht mehr gemeldet.") if(int(@errors) == 1);;\
   @errors = sort {lc($a) cmp lc($b)} @errors;;\
   return(join("\n - ", "Die folgenden ".@errors." Geräten haben sich seit mehr als 24 Stunden nicht mehr gemeldet:", @errors))\
  }
  attr Activity_monitoring errorWait 60*60*24
  attr Activity_monitoring warningReturn {return if !@warnings;;\
   $_ = AttrVal($_, 'alias', $_) for @warnings;;\
   return("Das Gerät \"$warnings[0]\" hat sich seit mehr als 12 Stunden nicht mehr gemeldet.") if(int(@warnings) == 1);;\
   @warnings = sort {lc($a) cmp lc($b)} @warnings;;\
   return(join("\n - ", "Die folgenden ".@warnings." Geräten haben sich seit mehr als 12 Stunden nicht mehr gemeldet:", @warnings))\
  }
  attr Activity_monitoring warningWait 60*60*12

  Devices are not monitored until they have triggered at least one event. If the device does not trigger another event in 12 hours, it will be set to the warning list. If the device does not trigger another event within 24 hours, it will be moved from the warning list to the error list.
  
  Note: It is recommended to use the whitelist attribute.


• Regular maintenance (for example changing the table water filter)
  

  defmod Wasserfilter_monitoring monitoring Wasserfilter_DashButton:.*:.short
  attr Wasserfilter_monitoring errorReturn {return if !@errors;;\
   return "Der Wasserfilter muss gewechselt werden.";;\
  }
  attr Wasserfilter_monitoring errorWait 60*60*24*30
  attr Wasserfilter_monitoring warningReturn {return if !@warnings;;\
   return "Der Wasserfilter muss demnächst gewechselt werden.";;\
  }
  attr Wasserfilter_monitoring warningWait 60*60*24*25

  A DashButton is used to tell FHEM that the water filter has been changed.
  After 30 days, the DashButton is set to the error list.


• Regular maintenance (for example cleaning rooms)
  

  defmod putzen_DashButton dash_dhcp
  attr putzen_DashButton allowed AC:63:BE:2E:19:AF,AC:63:BE:49:23:48,AC:63:BE:49:5E:FD,50:F5:DA:93:2B:EE,AC:63:BE:B2:07:78
  attr putzen_DashButton devAlias ac-63-be-2e-19-af:Badezimmer\
  ac-63-be-49-23-48:Küche\
  ac-63-be-49-5e-fd:Schlafzimmer\
  50-f5-da-93-2b-ee:Arbeitszimmer\
  ac-63-be-b2-07-78:Wohnzimmer
  attr putzen_DashButton event-min-interval .*:5
  attr putzen_DashButton port 6767
  attr putzen_DashButton userReadings state {return (split(":", @{$hash->{CHANGED}}[0]))[0];;}
  attr putzen_DashButton widgetOverride allowed:textField-long devAlias:textField-long
  
  defmod putzen_monitoring monitoring putzen_DashButton:.*:.short
  attr putzen_monitoring errorFuncAdd {$event =~ m/^(.+):/;;\
   $name = $1;;\
   return 1;;\
  }
  attr putzen_monitoring errorReturn {return if !@errors;;\
   return("Der Raum \"$errors[0]\" muss wieder geputzt werden.") if(int(@errors) == 1);;\
   return(join("\n - ", "Die folgenden Räume müssen wieder geputzt werden:", @errors))\
  }
  attr putzen_monitoring errorWait 60*60*24*7

  Several DashButton are used to inform FHEM that the rooms have been cleaned.
  After 7 days, the room is set to the error list.
  However, the room name is not the device name but the readings name and is changed in the errorFuncAdd attribute.


• Operating hours dependent maintenance (for example, clean the Beamer filter)
  

  defmod BeamerFilter_monitoring monitoring Beamer_HourCounter:pulseTimeOverall BeamerFilter_DashButton:.*:.short
  attr BeamerFilter_monitoring userattr errorInterval
  attr BeamerFilter_monitoring errorFuncAdd {return 1\
     if(ReadingsVal($name, "pulseTimeOverall", 0) >= \
          ReadingsVal($name, "pulseTimeService", 0)\
        + (AttrVal($SELF, "errorInterval", 0))\
        && $addMatch\
     );;\
   return;;\
  }
  attr BeamerFilter_monitoring errorFuncRemove {return if !$removeMatch;;\
   $name = "Beamer_HourCounter";;\
   fhem(\
      "setreading $name pulseTimeService "\
     .ReadingsVal($name, "pulseTimeOverall", 0)\
   );;\
   return 1;;\
  }
  attr BeamerFilter_monitoring errorInterval 60*60*200
  attr BeamerFilter_monitoring errorReturn {return if !@errors;;\
   return "Der Filter vom Beamer muss gereinigt werden.";;\
  }
  attr BeamerFilter_monitoring warningFuncAdd {return}
  attr BeamerFilter_monitoring warningFuncRemove {return}

  An HourCounter is used to record the operating hours of a beamer and a DashButton to tell FHEM that the filter has been cleaned.
  If the filter has not been cleaned for more than 200 hours, the device is set to the error list.
  If cleaning is acknowledged with the DashButton, the device is removed from the error list and the current operating hours are stored in the HourCounter device.

msgConfig

Provides global settings and tools for FHEM command msg.
A device named globalMsg will be created automatically when using msg-command for the first time and no msgConfig device could be found.
The device name can be renamed and reconfigured afterwards if desired.



Define

define <name> msgConfig





Set

• addLocation     
  Conveniently creates a Dummy device based on the given location name. It will be pre-configured to be used together with location-based routing when using the msg-command. The dummy device will be added to attribute msgLocationDevs automatically. Afterwards additional configuration is required by adding msgContact* or msgRecipient* attributes for gateway devices placed at this specific location.
• cleanReadings   []  
  Easy way to cleanup all fhemMsg readings. A parameter is optional and can be a concrete device name or mixed together with regex. This command is an alias for "deletereading fhemMsg.*".
• createResidentsDev     
  Creates a new device named rgr_Residents of type RESIDENTS. It will be pre-configured based on the given language. In case rgr_Residents exists it will be updated based on the given language (basically only a language change). Afterwards next configuration steps will be displayed to use RESIDENTS together with presence-based routing of the msg-command.
  This next step is basically to set attribute msgResidentsDevice to refer to this RESIDENTS device either globally or for any other specific FHEM device (most likely you do NOT want to have this attribute set globally as otherwise this will affect ALL devices and therefore ALL msg-commands in your automations).
  Note that use of RESIDENTS only makes sense together with ROOMMATE and or GUEST devices which still need to be created manually. See RESIDENTS Set commands addRoommate and addGuest respectively.
• createSwitcherDev     
  Creates a pre-configured Dummy device named HouseAnn and updates globalMsg attribute msgSwitcherDev to refer to it.

msgDialog

With msgDialog you can define dialogs for instant messages via TelegramBot, Jabber and yowsup (WhatsApp).
The communication uses the msg command. Therefore, a device of type msgConfig must be defined first.
For each dialog you can define which person is authorized to do so. Devices of the type ROOMMATE or GUEST with a defined msgContactPush attribute are required for this. Make sure that the reading fhemMsgRcvPush generates an event.

Prerequisites:
The Perl module "JSON" is required.
Under Debian (based) system, this can be installed using "apt-get install libjson-perl".



Define

define <name> msgDialog <JSON>
Because of the complexity, it is easiest to define an empty dialog first. define <name> msgDialog {} Then edit the DEF in the detail view.

{
  "<TRIGGER>": {
    "match": "<regex>",
    "setOnly": (true|false),
    "commands": "(fhem command|{perl code})",
    "message": [
      "{perl code}",
      "text"
    ],
    "<NEXT TRIGGER 1>": {
      ...
    },
    "<NEXT TRIGGER 2>": {
      ...
    }
  }
}
    

• TRIGGER
  Can be any text. The device checks whether the incoming message equals it. If so, the dialogue will be continued at this point.


• match
  If you do not want to allow only one message, you can specify a regex. The regex must apply to the whole incoming message.


• setOnly
  Can be optionally set to true or false. In both cases, the TRIGGER will not be returned at "get <name> trigger".
  If setOnly is set to true, the dialog at this point cannot be triggered by incoming messages, but only by using "set <name> say TRIGGER".
  This can be used to initiate a dialog from FHEM.


• commands
  Can contain a single or multiple commands:

  "commands": "single command"
  
  "commands": [
  "command 1",
  "command 2",
  "{perl command}"
  ]
        

• message
  Can contain a single or multiple text that is connected by a line break:

  "message": "text"
  
  "message": [
  "text 1",
  "text 2",
  "{return from perl command}"
  ]
        

For multi-level dialogs, this structure is specified nested.

Variables and placeholders defined under the attribute evalSpecials are evaluated.
Variables:
• $SELF
  name of the msgDialog


• $message
  received message


• $recipient
  Name of the dialog partner



Set

• reset
  Resets the dialog for all users.


• say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]
  The dialog is continued for all specified recipients at the specified position.
  If no recipients are specified, the dialog is continued for all recipients specified under the allowed attribute.


• updateAllowed
  Updates the selection for the allowed attribute.
• update <allowed or configFile>
  
  • allowed - updates the selection for the allowed attribute.
  • configFile - rereads configFile (e.g. after editing).



Get

• trigger
  Lists all TRIGGERs of the first level where setOnly is not specified.



Attributes

• allowed
  List with all RESIDENTS and ROOMMATE that are authorized for this dialog.


• disable 1
  Dialog is deactivated.


• disabledForIntervals HH:MM-HH:MM HH:MM-HH-MM ...


• evalSpecials key1=value1 key2=value2 ...
  Space Separate list of name=value pairs.
  Value may contain spaces if included in "" or {}.
  Value is evaluated as a perl expression if it is included in {}.
  In the DEF, %Name% strings are replaced by the corresponding value.
  This attribute is available as "msgDialog_evalSpecials" in the msgConfig device.
  If the same name was defined in the msgConfig and msgDialog, the value from msgDialog is used.


• msgCommand <command>
  Command used to send a message.
  The default is "msg push \@$recipients $message".
  This attribute is available in the msgConfig device.
• configFile
  

  Path to a configuration file for the dialogue. This is an alternative way to using DEF.
  The file itself must contain a JSON-encoded dialogue structure - just as described in define.

  Example (placed in the same dir fhem.pl is located):

  attr <msgDialogDevice> configFile ./metaDialogue.cfg




Readings

• $recipient_history
  | separated list of TRIGGERS to save the current state of the dialog.
  A readings is created for each dialog partner. When the dialog is finished, the reading will be cleared.

Notes for use with TelegramBot:
It may be necessary to set the attribute "utf8specials" to 1 in the TelegramBot, for messages with special characters to be sent.

The msg command supports the TelegramBot_MTYPE. The default is message. The queryInline value can be used to create an inline keyboard.

Notes for use with Jabber:
The msg command supports the TelegramBot_MTYPE. The default is empty. The value otr can be used to send an OTR message.

Notes for use with yowsub (WhatsApp):
No experiences so far.

Examples:
The following example codes can be imported by "Raw defnition".

All examples are designed for communication via the TelegramBot. When using Jabber or yowsup, they may need to be adjusted.
It is assumed that the msgConfig device contains the evalSpecials "me" with a name which is used to call the bot.

Meta dialog for listing all authorized dialogs:

defmod meta_Dialog msgDialog {\
  "%me%": {\
    "match": "\/?(start|%me%)",\
    "commands": "deletereading TYPE=msgDialog $recipient_history",\
    "message": [\
      "{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger'))), 'abbrechen') . ') ')}",\
      "Ich kann folgendes für dich tun:"\
    ]\
  },\
  "zurück": {\
    "commands": "set $recipient_history=.+|.+ say @$recipient {(ReadingsVal($DEV, '$recipient_history', '') =~ m/(.+)\\|.+$/;; return $2 ? $2 : $1;;)}"\
  },\
  "abbrechen": {\
    "match": "\/?abbrechen",\
    "commands": "deletereading TYPE=msgDialog $recipient_history",\
    "message": [\
      "TelegramBot_MTYPE=queryInline (%me%) ",\
      "Dialog abgebrochen."\
    ]\
  },\
  "beenden": {\
    "match": "\/?beenden",\
    "commands": "deletereading TYPE=msgDialog $recipient_history",\
    "message": [\
      "TelegramBot_MTYPE=queryInline (%me%) ",\
      "Dialog beendet."\
    ]\
  }\
}
attr meta_Dialog allowed everyone

Request of current fuel prices

defmod Tankstelle_Dialog msgDialog {\
  "Tankstelle": {\
    "message": [\
      "TelegramBot_MTYPE=queryInline (%me%) ",\
      "Die Krafstoffpreise der betragen aktuell folgende Werte:",\
      "",\
      "AIVA",\
      "",\
      "[%AIVA%:Diesel] €/l Diesel",\
      "[%AIVA%:Super] €/l Super",\
      "[%AIVA%:E10] €/l E10",\
      "[%AIVA%:Autogas] €/l Autogas"\
    ]\
  }\
}
attr Tankstelle_Dialog evalSpecials AIVA=AIVA_petrolStation

Programming of the washing machine

defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
    "message": [\
      "{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
      "{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
      "{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
      "(Verlaufsdiagramm) ",\
      "(abbrechen) ",\
      "{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
      "{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
    ],\
    "Zeitprogramm stoppen": {\
      "commands": "set %controlUnit% controlMode manual",\
      "message": [\
        "TelegramBot_MTYPE=queryInline (%me%) ",\
        "Das Zeitprogramm wurde gestoppt."\
      ]\
    },\
    "programmieren": {\
      "message": [\
        "(bestätigen|zurück|abbrechen) ",\
        "( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
        "( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
        "( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
        "( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
        "( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
        "( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
        "( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
        "( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
        "( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
        "( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
        "( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
        "( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
        "( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
        "( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
        "( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
        "( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
        "( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
        "( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
        "( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
        "( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
        "( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
        "( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
        "( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
        "( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
        "Wann soll die Wäsche fertig sein?",\
        "Bitte Uhrzeit in HH:MM angeben.",\
        "Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
      ],\
      "Uhrzeit": {\
        "match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
        "commands": [\
          "set %controlUnit% time $message",\
          "set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
        ]\
      },\
      "bestätigen": {\
        "commands": "set %controlUnit% controlMode auto",\
        "message": [\
          "TelegramBot_MTYPE=queryInline (%me%) ",\
          "Das Zeitprogramm wurde eingestellt.",\
          "Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
          "Bitte die Waschmaschine vorbereiten."\
        ]\
      }\
    },\
    "einschalten": {\
      "commands": [\
        "set %controlUnit% controlMode manual",\
        "set %actor% on"\
      ]\
    },\
    "Verlaufsdiagramm": {\
      "commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
      "message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
    }\
  },\
  "auto": {\
    "setOnly": true,\
    "commands": [\
      "set %actor% on",\
      "set %controlUnit% controlMode manual"\
    ],\
    "message": [\
      "TelegramBot_MTYPE=queryInline (%me%) ",\
      "Die Wachmaschine wurde automatisch eingeschaltet."\
    ]\
  },\
  "manual": {\
    "setOnly": true,\
    "message": [\
      "TelegramBot_MTYPE=queryInline (%me%) ",\
      "Die Wachmaschine wurde manuell eingeschaltet."\
    ]\
  },\
  "done": {\
    "setOnly": true,\
    "commands": "set %actor% off",\
    "message": [\
      "TelegramBot_MTYPE=queryInline (%me%) ",\
      "Die Wachmaschine ist fertig."\
    ]\
  }\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG

netatmo

[EN DE]

FHEM module for netatmo weather stations, thermostats and cameras.

Notes:
• JSON has to be installed on the FHEM host.
• You need to create an app here to get your client_id / client_secret.
  Request the access scope including cameras and thermostats as given (read_thermostat write_thermostat read_camera write_camera access_camera read_doorbell access_doorbell read_presence write_presence access_presence read_homecoach read_carbonmonoxidedetector read_smokedetector read_station) and generate a refresh token on the dev.netatmo.com page.

Define
define <name> netatmo ACCOUNT <username> <password> <client_id> <client_secret> <refresh_token>
define <name> netatmo <device> (you should use autocreate from the account device!)

Defines a netatmo device.

If a netatmo device of the account type is created all fhem devices for the netatmo devices are automaticaly created (if autocreate is not disabled).
Examples:
define netatmo netatmo ACCOUNT abc@test.com myPassword 2134123412399119d4123134 AkqcOIHqrasfdaLKcYgZasd987123asd 2134123412399119d4123134|058764ac532fb9a080412baa7d107d42
define netatmo_station netatmo 2f:13:2b:93:12:31
define netatmo_module netatmo MODULE 2f:13:2b:93:12:31 f1:32:b9:31:23:11
define netatmo_publicstation netatmo PUBLIC 70:ee:50:27:2c:9c 02:00:00:27:4a:a6 temperature,humidity 70:ee:50:27:2c:9c pressure 05:00:00:04:cc:42 rain 06:00:00:01:ae:94 windstrength,windangle,guststrength,gustangle
define netatmo_maparea netatmo PUBLIC 47.8941876,16.64446 0.08
define netatmo_forecast netatmo FORECAST 2f:13:2b:93:12:31
define netatmo_relay netatmo RELAY 70:ee:50:00:12:34
define netatmo_thermostat netatmo THERMOSTAT 70:ee:50:00:12:34 04:00:00:0a:00:11
define netatmo_home netatmo HOME 1234567890abcdef12345678
define netatmo_camera netatmo CAMERA 1234567890abcdef12345678 70:ee:12:34:56:78
define netatmo_tag netatmo TAG 70:ee:12:34:56:78 70:ee:50:11:22:33
define netatmo_person netatmo PERSON 1234567890abcdef12345678 01234567-89ab-cdef-0123-456789abcdef
define netatmo_webhook netatmo WEBHOOK


Webhook

define <name> netatmo WEBHOOK

Set your URL in attribute webhookURL, events from cameras will be received instantly
Ports 80 and 443 only, self-signed certificates will fail.

Readings
• temperature
• humidity
• pressure
• co2
• noise
• rain
• rain_hour
• rain_day
• windstrength
• windangle
• guststrength
• gustangle

Set
• autocreate
  Create fhem devices for all netatmo weather devices.
• autocreate_homes
  Create fhem devices for all netatmo homes, cameras and persons.
• autocreate_thermostats
  Create fhem devices for all netatmo relays and thermostats.
• autocreate_homecoachs
  Create fhem devices for all netatmo homecoachs.

Get
ACCOUNT
• devices
  list the netatmo weather devices for this account
• home
  list the netatmo home devices for this account
• update
  trigger a global update for dashboard data
• public [<address>] <args>
  no arguments -> get all public stations in a radius of 0.025° around global fhem latitude/longitude
  <rad> -> get all public stations in a radius of <rad>° around global fhem latitude/longitude
  <lat> <lon> [<rad>] -> get all public stations in a radius of 0.025° or <rad>° around <lat>/<lon>
  <lat1> <lon1> <lat2> <lon2> -> get all public stations in the area of <lat1> <lon2> <lat2> <lon2>
  if <address> is given then list stations in the area of this address. can be given as 5 digit german postal code or a: followed by a textual address. all spaces have to be replaced by a +.
  <lat> <lon> values can also be entered as a single coordinates parameter <lat>,<lon>
  

DEVICE/MODULE
• update
  update the device readings
• updateAll
  update the device readings after deleting all current readings

HOME
• update
  update the home events and all camera and person readings

CAMERA
• ping
  ping the camera and get the local command url
• live/_local
  get the playlist for live video (internet or local network)
• video/_local <video_id>
  get the playlist for a video id (internet or local network)

PRESENCE
• config
  read the camera config
• timelapse
  get the link for a timelapse video (local network)

PERSON
• update
  n/a

Attributes
• interval
  the interval in seconds used to check for new data
• disable
  1 -> stop polling
• addresslimit
  maximum number of addresses to resolve in public station searches (ACCOUNT - default: 10)
• setpoint_duration
  setpoint duration in minutes (THERMOSTAT - default: 60)
• videoquality
  video quality for playlists (HOME - default: medium)
• webhookURL
  webhook URL - can include basic auth and port (80 or 443 only, no self-signed certificates!): http://user:pass@your.url:80/fhem/netatmo (WEBHOOK)
• webhookPoll
  poll home after event from webhook (WEBHOOK - default: 0)
• ignored_device_ids
  ids of devices/persons ignored on autocrate (ACCOUNT - comma separated)

notice

[EN DE]

notice [confirm [value]|list [<keyword>]|reset [yes]|view <id> [noheader|[de|en]]]

View and confirmation of system messages.

During an update or a system start from FHEM sometimes it is necessary to inform the user about important changes or additions. It may be necessary to confirm a system message by the user.

By entering the command 'notice' a list of all messages is displayed. Are messages available in different languages, they are ordered by language.
Example:

    fhem> notice
    ==> Language: de
      ID                  Published  Expired    Confirmed  Description
      advice-20130128-002 actually   never      not needed kurze beschreibung
      update-20130128-002 31.01.2013 01.02.2013 no         kurze beschreibung

    ==> Language: en
      ID                  Published  Expired    Confirmed  Description
      advice-20130128-001 actually   never      no         short description
      advice-20130128-002 actually   never      not needed short description
      update-20130128-001 actually   never      no         short description
      update-20130128-002 31.01.2013 01.02.2013 no         short description
    

By entering 'notice list <keyword>' the output of the list contains only available messages that starts with '<keyword>'.
Example:

    fhem> notice list update
    ==> Language: de
      ID                  Published  Expired    Confirmed  Description
      update-20130128-002 31.01.2013 01.02.2013 no         kurze beschreibung

    ==> Language: en
      ID                  Published  Expired    Confirmed  Description
      update-20130128-001 actually   never      no         short description
      update-20130128-002 31.01.2013 01.02.2013 no         short description
    

To display a single message, enter the command 'notice view <id>' where id is the Identifier of the message. You can use the optional parameter noheader or the language codes de or en to display the message without the header informations or in your prefered language if available.
Example:

    fhem> notice view advice-20130128-002 de
    ID        : advice-20130128-002
    From      : M. Fischer
    Date      : 28.01.2013
    Expire    : 0
    Title     : kurze beschreibung
    ### Start of Text
    test-advice

    dies ist ein test

    001
    ### End of Text
    

If it is necessary to confirm a message, this is be done by entering 'notice confirm <id> [value]'. The optional argument value will also be stored with the confirmation.
Example:

    fhem> notice confirm update-20130128-001 foo:bar
    update-20130128-001 confirmed on 2013-01-29 20:58:57: foo:bar
    

Sometimes it is necessary to reset all confirmations. This is be done by entering 'notice reset'.
Example:

    fhem> notice reset
    This command delete all confirmations.
    If you really want to do this, call 'notice reset yes'
    


For developers only:

notice [condition <id>|get <keyword> <value>|position <id>]


These arguments are normally not needed by any user.

A message may optionally contains one or more code snippets. The argument condition supplies the determined value(s) of the embedded test(s) as a key:value pair. If more than one pair returned, they they are seperated by |. It is possible to define your own rules for a condition, like !empty or >>5 and so on. An example of a condition is shown in the below example message file. Example:

    fhem> notice condition update-20130127-001
    configfile:./fhem.cfg|sendStatistics:never:!empty
    

The argument get, followed by a keyword and a number from 0 to 8, returns a comma seperated list of message ids. The possible outputs are:
• 0 returns a list of all messages.
• 1 returns a list of unconfirmed messages.
• 2 returns a list of messages that are not expired.
• 3 returns a list of messages that are not expired and unconfirmed.
• 4 returns a list of published messages.
• 5 returns a list of unconfirmed and published messages.
• 6 returns a list of published messages that are not expired.
• 7 returns a list of published, unconfirmed and not expired messages.
• 8 returns a list of confirmed messages.
Example:

    fhem> notice get all 2
    advice-20130128-001,advice-20130128-002,update-20130128-001,update-20130128-002
    

The argument position followed by an <id> returns the view position of a message if defined.
Example:

    fhem> notice position update-20130128-001
    before
    

Example of a message file:

    # FROM: M. Fischer
    # DATE: 28.01.2013
    # CONFIRM: 1
    # PUBLISH: 31.01.2013
    # EXPIRE: 01.02.2013
    # KEY_1: sendStatistics
    # VAL_1: AttrVal("global","sendStatistics",undef);
    # CON_1: !empty
    # KEY_2: configfile
    # VAL_2: AttrVal("global","configfile",undef);
    # POSITION: top
    # TITLE_DE: kurze beschreibung
    # NOTICE_DE
    Hinweis:

    dies ist ein test
    # TITLE_EN: short description
    # NOTICE_EN
    Advice:

    this is a test
    

The keywords 'FROM, DATE, CONFIRM, PUBLISH, EXPIRE, TITLE_DE, TITLE_EN, NOTICE_DE, NOTICE_EN' are fixed. It is possible to add any key:value string to these files. Also it is possible to set only one or both keywords of 'TITLE_DE, TITLE_EN' and 'NOTICE_DE, NOTICE_EN'.

notify

Define
define <name> notify <pattern> <command>

Execute a command when received an event for the definition <pattern>. If <command> is enclosed in {}, then it is a perl expression, if it is enclosed in "", then it is a shell command, else it is a "plain" fhem.pl command (chain). See the trigger command for testing it. Examples:
define b3lampV1 notify btn3 set lamp $EVENT
define b3lampV2 notify btn3 { fhem "set lamp $EVENT" }
define b3lampV3 notify btn3 "/usr/local/bin/setlamp "$EVENT""
define b3lampV3 notify btn3 set lamp1 $EVENT;;set lamp2 $EVENT
define wzMessLg notify wz:measured.* "/usr/local/bin/logfht $NAME "$EVENT""
define LogUndef notify global:UNDEFINED.* "send-me-mail.sh "$EVENT""


Notes:
• <pattern> is either the name of the triggering device, or devicename:event.
• <pattern> must completely (!) match either the device name, or the compound of the device name and the event. To identify the events use the inform command from the telnet prompt or the "Event Monitor" link in the browser (FHEMWEB), and wait for the event to be printed. See also the eventTypes device.
• in the command section you can access the event:
  • The variable $EVENT will contain the complete event, e.g. measured-temp: 21.7 (Celsius)
  • $EVTPART0,$EVTPART1,$EVTPART2,etc contain the space separated event parts (e.g. $EVTPART0="measured-temp:", $EVTPART1="21.7", $EVTPART2="(Celsius)". This data is available as a local variable in perl, as environment variable for shell scripts, and will be textually replaced for FHEM commands.
  • $NAME and $TYPE contain the name and type of the device triggering the event, e.g. myFht and FHT
  • $SELF contains the name of the notify itself
• Note: the following is deprecated and will be removed in a future release. It is only active for featurelevel up to 5.6. The described replacement is attempted if none of the above variables ($NAME/$EVENT/etc) found in the command.
  • The character % will be replaced with the received event, e.g. with on or off or measured-temp: 21.7 (Celsius)
    It is advisable to put the % into double quotes, else the shell may get a syntax error.
  • The character @ will be replaced with the device name.
  • To use % or @ in the text itself, use the double mode (%% or @@).
  • Instead of % and @, the parameters %EVENT (same as %), %NAME (same as @) and %TYPE (contains the device type, e.g. FHT) can be used. The space separated event "parts" are available as %EVTPART0, %EVTPART1, etc. A single % looses its special meaning if any of these parameters appears in the definition.
• Following special events will be generated for the device "global"
  • INITIALIZED after initialization is finished.
  • REREADCFG after the configuration is reread.
  • SAVE before the configuration is saved.
  • SHUTDOWN before FHEM is shut down.
  • DEFINED <devname> after a device is defined.
  • DELETED <devname> after a device was deleted.
  • RENAMED <old> <new> after a device was renamed.
  • UNDEFINED <defspec> upon reception of a message for an undefined device.
• Notify can be used to store macros for manual execution. Use the trigger command to execute the macro. E.g.
  fhem> define MyMacro notify MyMacro { Log 1, "Hello"}
fhem> trigger MyMacro
  

Set
• addRegexpPart <device> <regexp>
  add a regexp part, which is constructed as device:regexp. The parts are separated by |. Note: as the regexp parts are resorted, manually constructed regexps may become invalid.
• removeRegexpPart <re>
  remove a regexp part. Note: as the regexp parts are resorted, manually constructed regexps may become invalid.
  The inconsistency in addRegexpPart/removeRegexPart arguments originates from the reusage of javascript functions.
• inactive
  Inactivates the current device. Note the slight difference to the disable attribute: using set inactive the state is automatically saved to the statefile on shutdown, there is no explicit save necesary.
  This command is intended to be used by scripts to temporarily deactivate the notify.
  The concurrent setting of the disable attribute is not recommended.
• active
  Activates the current device (see inactive).

Get
N/A

Attributes
• disable
• disabledForIntervals
• disabledAfterTrigger someSeconds
  disable the execution for someSeconds after it triggered.
• addStateEvent
  The event associated with the state Reading is special, as the "state: " string is stripped, i.e $EVENT is not "state: on" but just "on". In some circumstances it is desireable to get the event without "state: " stripped. In such a case the addStateEvent attribute should be set to 1 (default is 0, i.e. strip the "state: " string).
  Note 1: you have to set this attribute for the event "receiver", i.e. notify, FileLog, etc.
  Note 2: this attribute will only work for events generated by devices supporting the readingFnAttributes.
• forwardReturnValue
  Forward the return value of the executed command to the caller, default is disabled (0). If enabled (1), then e.g. a set command which triggers this notify will also return this value. This can cause e.g FHEMWEB to display this value, when clicking "on" or "off", which is often not intended.
• ignoreRegexp regexp
  It is hard to create a regexp which is _not_ matching something, this attribute helps in this case, as the event is ignored if it matches the argument. The syntax is the same as for the original regexp.
• perlSyntaxCheck
• readLog
  Execute the notify for messages appearing in the FHEM Log. The device in this case is set to the notify itself, e.g. checking for the startup message looks like:
  define n notify n:.*Server.started.* { Log 1, "Really" }
attr n readLog
• setList
  space separated list of user-defined commands. When executing such a command, a reading with the same name is set to the arguments of the command.
  Can be used in scenarios like:
  define lightOn notify switch:on set Light on-for-timer [$SELF:duration]
attr lightOn setList duration:60,120,180

Node.js installation and update

[EN DE]

npmjs - controls Node.js installation and updates
This module allows to install, uninstall and update outdated Node.js packages using NPM package manager.
Global installations will be controlled by default and running update/install/uninstall require sudo permissions like this:

fhem ALL=(ALL) NOPASSWD:SETENV: /usr/bin/npm update *
fhem ALL=(ALL) NOPASSWD:SETENV: /usr/bin/npm install *
fhem ALL=(ALL) NOPASSWD:SETENV: /usr/bin/npm uninstall *

This line may easily be added to a new file in /etc/sudoers.d/fhem and will automatically included to /etc/sudoers from there.


Define

define <name> npmjs [<[user@]HOSTNAME[:port]>]

Example:

define fhemServerNpm npmjs


This command creates an npmjs instance named 'fhemServerNpm' to run commands on the local host machine. Afterwards all information about installation and update state will be fetched. This will take a moment.

If you would like to connect to a remote host, set the optional HOSTNAME to something different than 'localhost'. In that case, make sure that SSH keys between the FHEM running user and remote server are setup appropriately.


Readings
• state - update status about the server
• nodejsVersion - installed Node.js version
• outdated - status about last update status sync
• updated - status about last update command
• installed - status about last install command
• uninstalled - status about last uninstall command
• updatesAvailable - number of available updates


Set
• statusRequest - Update Node.js installation status
• outdated - fetch information about update state
• update - trigger complete or selected update process (using 'npm update' command). FHEM related packages will always be upgraded to the latest major version (using 'npm install' instead of 'npm update'). Other packages will repsect semantic versioning and major upgrades will not be performed.
• upgrade - trigger complete or selected upgrade process (using 'npm install' command). ATTENTION! Every package will be upgraded to the latest and greatest version (using 'npm install' command instead of 'npm update'), no matter if the package maintainer has defined some incompatiblities between the current installed and latest version. If in doubt, consider to only use the update set command instead.
• install - Install one or more NPM packages. If Node.js is not installed on the server, it will offer to initially install Node.js (APT compatible Linux distributions only). You may still install Node.js and NPM manually and trigger to re-detect the installation by using any of the provided options. Existing Node.js installations will never be overwritten and it will not be possible to upgrade Node.js using this FHEM module!
• uninstall - Uninstall one or more NPM packages


Get
• showOutdatedList - list about available updates
• showErrorList - list errors that occured for the last command


Attributes
• disable - disables the device
• updateListReading - add Update List Reading as JSON
• npmglobal - work on global or user installation. Defaults to 1=global
• disabledForIntervals - disable device for interval time (13:00-18:30 or 13:00-18:30 22:00-23:00)

panStamp

[EN DE]

The panStamp is a family of RF devices sold by panstamp.com. It is possible to attach more than one device in order to get better reception, fhem will filter out duplicate messages.

This module provides the IODevice for the SWAP modules that implement the SWAP protocoll to communicate with the individual moths in a panStamp network.

Note: currently only panSticks are know to work. The panStamp shield for a Rasperry Pi is untested.

Note: this module may require the Device::SerialPort or Win32::SerialPort module if you attach the device via USB and the OS sets strange default parameters for serial devices.

Define
define <name> panStamp <device> [<address> [<channel> [<syncword>]]]

USB-connected devices:

<device> specifies the serial port to communicate with the panStamp. The name of the serial-device depends on your distribution, under linux the cdc_acm kernel module is responsible, and usually a /dev/ttyACM0 device will be created. If your distribution does not have a cdc_acm module, you can force usbserial to handle the panStamp by the following command:
modprobe usbserial vendor=0x0403 product=0x6001
In this case the device is most probably /dev/ttyUSB0.

You can also specify a baudrate if the device name contains the @ character, e.g.: /dev/ttyACM0@38400

If the baudrate is "directio" (e.g.: /dev/ttyACM0@directio), then the perl module Device::SerialPort is not needed, and fhem opens the device with simple file io. This might work if the operating system uses sane defaults for the serial parameters, e.g. some Linux distributions and OSX.



The address is a 2 digit hex number to identify the moth in the panStamp network. The default is 01.
The channel is a 2 digit hex number to define the channel. the default is 00.
The syncword is a 4 digit hex number to identify the panStamp network. The default is B547.

Uppon initialization a broadcast message is send to the panStamp network to try to autodetect and autocreate all listening SWAP devices (i.e. all devices not in power down mode).

Set
• raw data
  send raw data to the panStamp to be transmitted over the RF link.


Get
Attributes

pilight

[EN DE]

Define

define <name> pilight <protocol>

Defines a module for setting pilight compartible switches on or off. See Sweetpi.

Supported protocols: kaku_switch, quigg_*, elro_he, elro_hc, silvercrest, pollin, brennenstuhl, mumbi, impuls, rsl366, rev1_switch, rev2_switch, clarus_switch, raw, and intertechno_old. If you need more, just write an issue!

Example:
define Weihnachtsbaum pilight kaku_switch
attr Weihnachtsbaum housecode 12323578
attr Weihnachtsbaum unitcode 0


If your pilight server does not run on localhost, please set both the attributes remote_ip and remote_port. If you are running pilight >3.0, then please define the port used by pilight settings: http://www.pilight.org/getting-started/settings/; fhem-plight uses 5000 by default.
This version is written for pilight 6.0. If you run a prior version, please set the following attribute: attr Weihnachtsbaum useOldVersion 1

Attributes

• attr <name> protocol <string>
  Protocol used in pilight, e.g. "kaku_switch"
• attr <name> housecode <string>
  Housecode used in pilight (for protocol kaku*, clarus_switch, rev1_switch, rev2_switch, rev3_switch, quigg_switch, quigg_gt1000, quigg_gt7000)
• attr <name> systemcode <string>
  Systemcode of your switch (for protocol elso, elro_he, elro_hc, silvercrest, impuls, rsl366, pollin, mumbi, brennenstuhl, intertechno_old)
• attr <name> unitcode <string>
  Unit code/device code used in pilight (all protocols)
• attr <name> rawCode <string>
  Raw code to send on/off-command with protocol "raw"
• attr <name> remote_ip <string>
  Remote IP of you pilight server (127.0.0.1 is default)
• attr <name> remote_port <string>
  Remote port of you pilight server (5000 is default)
• attr <name> rawCodeOn <string>
  Raw command to send to switch device ON (only used with protocol 'raw')
• attr <name> rawCodeOff <string>
  Raw command to send to switch device OFF (only used with protocol 'raw')

pilight_contact

[EN DE]

pilight_contact represents a contact sensor receiving data from pilight
You have to define the base device pilight_ctrl first.
Further information to pilight: http://www.pilight.org/

Define
define <name> pilight_contact protocol id [unit]

Example:
define myctrl pilight_contact arctech_contact 12836682 1




Readings

• state
  present the current state (open|closed)

pilight_ctrl

[EN DE]

pilight_ctrl is the base device for the communication (sending and receiving) with the pilight-daemon.
You have to define client devices e.q. pilight_switch for switches.
Further information to pilight: http://www.pilight.org/

Further information to pilight protocols: http://wiki.pilight.org/doku.php/protocols#protocols
Currently supported:

• Switches:
• Dimmers:
• Temperature and humitity sensors


Define
define <name> pilight_ctrl ip:port [api] ip:port is the IP address and port of the pilight-daemon
api specifies the pilight api version - default 6.0

Example:
define myctrl pilight_ctrl localhost:5000 5.0
define myctrl pilight_ctrl 192.168.1.1:5000




Set

• reset Reset the connection to the pilight daemon
• disconnectDiconnect from pilight daemon and do not reconnect automatically



Readings

• rcv_raw
  The last complete received message in json format.

Attributes
• ignoreProtocol
  Comma separated list of protocol:id combinations to ignore.
  protocol:* ignores the complete protocol.
  * All incomming messages will be ignored. Only protocol id combinations from defined submodules will be accepted
  Example:
• ignoreProtocol tfa:0
• ignoreProtocol tfa:*
• ignoreProtocol *
• brands
  Comma separated list of : combinations to rename protocol names.
  pilight uses different protocol names for the same protocol e.q. arctech_switch and kaku_switch
  Example: brands archtech:kaku
• ContactAsSwitch
  Comma separated list of ids which correspond to a contact but will be interpreted as switch.
  In this case opened will be interpreted as on and closed as off.
  Example: ContactAsSwitch 12345
• SendTimeout
  Timeout [s] for aborting sending commands (non blocking) - default 1s

pilight_dimmer

[EN DE]

pilight_dimmer represents a dimmmer controled with\from pilight
You have to define the base device pilight_ctrl first.
Further information to pilight: http://www.pilight.org/
Supported dimmers: http://wiki.pilight.org/doku.php/protocols#dimmers

It is possible to add the screen feature to a dimmer. So you can change the dimlevel by set 'up' or 'down'.
If you push up or down on the remote control the dimlevel will be changed by dimlevel_step.
Further it is possible to define a simulated dimmer with a screen and switch protocol. See example three.
That means if you change the dimlevel a up or down command will be send n times to dim the device instead of send a dimlevel directly.

Define
define <name> pilight_dimmer protocol id unit [protocol]
The second protocol is optional. With it you can add the pilight screen feature (up|down) Example:
define myctrl pilight_dimmer kaku_dimmer 13483668 0
define myctrl pilight_dimmer kaku_dimmer 13483668 0 kaku_screen - Dimmer with screen feature
define myctrl pilight_dimmer quigg_screen 1 0 quigg_gt7000 - Simulated dimmer with screen feature




Set

• on
• off
• up only if defined with screen protocol
• down only if defined with screen protocol
• dimlevel
• set extensions are supported
  



Readings

• state
  state of the dimmer on or off
• dimlevel
  dimlevel of the dimmer

Attributes
• dimlevel_max_device
  Maximum of the dimlevel of the device - default 15
  Have to be less or equal than dimlevel_max
  
• dimlevel_max
  Maximum of the dimlevel in FHEM - default dimlevel_max_device
  
• dimlevel_step
  Step of the dimlevel - default 1
  
• dimlevel_on
  Change dimlevel to value if on set - default no changing
  Could be a numeric value or dimlevel_max
  
• dimlevel_off
  Change dimlevel to value if off set - default no changing
  

pilight_raw

[EN DE]

With pilight_raw it si possible to send raw codes
You have to define the base device pilight_ctrl first.

Define
define <name> pilight_raw



Set

• on Send 'onCode' as raw code
• off Send 'offCode' as raw code
• code Send as raw code
• set extensions are supported
  



Readings

• state
  state on or off

Attributes
• onCode
  raw code for state on
• onCode
  raw code for state off
• sendCount
  How many times the command is send. Default: 1

pilight_smoke

[EN DE]

pilight_smoke represents a smoke sensor receiving data from pilight
You have to define the base device pilight_ctrl first.
Further information to pilight: http://www.pilight.org/

Define
define <name> pilight_smoke protocol id

Example:
define myctrl pilight_smoke secudo_smoke_sensor 0




Readings

• state
  present the current state (alarm|none)

Attributes
• resetTime
  Time [sec] to reset the state to none.

pilight_switch

[EN DE]

pilight_switch represents a switch controled with\from pilight
You have to define the base device pilight_ctrl first.
Further information to pilight: http://www.pilight.org/
Supported switches: http://wiki.pilight.org/doku.php/protocols#switches

Define
define <name> pilight_switch protocol id unit

Example:
define myctrl pilight_switch kaku_switch_old 0 0




Set

• on
• off
• set extensions are supported
  



Readings

• state
  state of the switch on or off
Attributs
• IODev
  
• sendCount
  How many times the command is send. Default: 1

pilight_temp

[EN DE]

pilight_temp represents a temperature and humidity sensor receiving data from pilight
You have to define the base device pilight_ctrl first.
Further information to pilight: http://www.pilight.org/
Supported Sensors: http://wiki.pilight.org/doku.php/protocols#weather_stations

Define
define <name> pilight_temp protocol id

Example:
define myctrl pilight_temp alecto_wsd17 100




Readings

• state
  present the current temperature
• temperature
  present the current temperature
• humidity
  present the current humidity (if sensor support it)
• battery
  present the battery state of the senor (if sensor support it)
• pressure
  present the pressure state of the senor (if sensor support it)
• windavg
  present the average wind speed state of the senor (if sensor support it)
• winddir
  present the wind direction state of the senor (if sensor support it)
• windgust
  present the wind gust state of the senor (if sensor support it)

Attributes
• corrTemp
  A factor (e.q. 0.1) to correct the temperture value. Default: 1 temperature = corrTemp * piligt_temp + offsetTemp
• offsetTemp
  An offset for temperature value. Default: 0 temperature = corrTemp * piligt_temp + offsetTemp
• corrHumidity
  A factor (e.q. 0.1) to correct the humidity value. Default: 1 humidity = corrHumidity * piligt_humidity + offsetHumidity
• offsetHumidity
  An offset for humidity value. Default: 0 humidity = corrHumidity * piligt_humidity + offsetHumidity

ping

[EN DE]

This module provides a simple "ping" function for testing the state of a remote network device.

It allows for alerts to be triggered when devices cannot be reached using a notify function.

Define

define <name> ping <host/ip> <mode> <timeout>

Specifies the ping device.
<host/ip> is the hostname or IP address of the Bridge.

Specifies ping mode.
<mode> One of: tcp|udp|icmp. Read the perl docs for more detail: http://perldoc.perl.org/Net/Ping.html

Timeout.
<timeout> is the maximum time to wait for each ping.

Readings

• state
  [Initialized|ok|unreachable]: Shows reachable status check every 10 (checkInterval) seconds.

Attributes

• checkInterval
  Default: 10s. Time after the bridge connection is re-checked.
• minFailCount
  Default: 1. Number of failures before reporting "unreachable".

plex

[EN DE]

This module allows you to control and receive events from plex.



Notes:
• IO::Socket::Multicast is needed to use server and client autodiscovery.
• As far as possible alle get and set commands are non-blocking. Any output is displayed asynchronous and is using fhemweb popup windows.


Define
define <name> plex [<server>]


Set
• play [<server> [<item>]]
  
• resume [<server>] <item>]
  
• pause [<type>]
• stop [<type>]
• skipNext [<type>]
• skipPrevious [<type>]
• stepBack [<type>]
• stepForward [<type>]
• seekTo <value> [<type>]
• volume <value> [<type>]
• shuffle 0|1 [<type>]
• repeat 0|1|2 [<type>]
• mirror [<server>] <item>
  show preplay screen for <item>
• home
• music
• showAccount
  display obfuscated user and password in cleartext
• playlistCreate [<server>] <name>
• playlistAdd [<server>] <key> <keys>
• playlistRemove [<server>] <key> <keys>
• unwatched [[<server>] <items>]
• watched [[<server>] <items>]
• autocreate <machineIdentifier>
  create device for remote/shared server

Get
• [<server>] ls [<path>]
  browse the media library. eg:
  
  get <plex> ls

    Plex Library
    key                                 type       title
    1                                   artist       Musik
    2                      ...

  
  get <plex> ls /1

    Musik
    key                                 type       title
    all                                            All Artists
    albums                                         By Album
    collection                                     By Collection
    decade                                         By Decade
    folder                                         By Folder
    genre                                          By Genre
    year                                           By Year
    recentlyAdded                                  Recently Added
    search?type=9                                  Search Albums...
    search?type=8                                  Search Artists...
    search?type=10                                 Search Tracks...

  
  get <plex> ls /1/albums

    Musik ; By Album
    key                                  type       title
    /library/metadata/133999/children   album       ...
    /library/metadata/134207/children   album       ...
    /library/metadata/168437/children   album       ...
    /library/metadata/82906/children    album       ...
    ...

  
  get <plex> ls /library/metadata/133999/children

    ...

  
  
  if used from fhemweb album art can be displayed and keys and other items are klickable.
  
  
• [<server>] search <keywords>
  search the media library for items that match <keywords>
• [<server>] onDeck
  list the global onDeck items
• [<server>] recentlyAdded
  list the global recentlyAdded items
• [<server>] detail <key>
  show detail information for media item <key>
• [<server>] playlists
  list playlists
• [<server>] m3u [album]
  creates an album playlist in m3u format. can be used with other players like sonos.
• [<server>] pls [album]
  creates an album playlist in pls format. can be used with other players like sonos.
• clients
  list the known clients
• servers
  list the known servers
• pin
  get a pin for authentication at https://plex.tv/pin

Attr
• httpPort
• ignoredClients
• ignoredServers
• removeUnusedReadings
• user
• password
  user and password of a myPlex account. required if plex home is used. both are stored obfuscated

powerMap

[EN DE]

powerMap will help to determine current power consumption and calculates energy consumption either when power changes or within regular interval.
These new values may be used to collect energy consumption for devices w/o power meter (e.g. fridge, lighting or FHEM server) and for further processing using module ElectricityCalculator.
Note: As this module will derive some additional readings when readings are changed (with event) in the supervised FHEM devices to prepare for further processing with other event handlers, this will happen on a rather early stage of the entire event processing. So do not expect powerMap to work properly when setting own values (e.g. using notify or DOIF in combination with "setreading" commands).


Define

define <name> powerMap
You may only define one single instance of powerMap.



Set

• assign <devspec>
  Adds pre-defined powerMap attributes to one or more devices for further customization.



Get

• devices
  Lists all devices having set an attribute named 'powerMap'.



Readings



Device specific readings:
• pM_energy
  A counter for consumed energy in Wh.
  Hint: In order to have the calculation working, attribute timestamp-on-change-reading may not be set for reading pM_energy!


• pM_energy_begin
  Unix timestamp when collection started and device started to consume energy for the very first time.


• pM_consumption
  Current power consumption of device in W.



Attributes

• disable 1
  No readings will be created or calculated by this module.


• do_not_notify
• powerMap_eventChainWarnOnly <1>
  When set, event chain will NOT be repaired automatically if readings were found to be required for powerMap but their events are currently suppressed because they are either missing from attributes event-on-change-reading or event-on-update-reading. Instead, manual intervention is required.


• powerMap_interval <seconds>
  Interval in seconds to calculate energy.
  Default value is 900 seconds.


• powerMap_noEnergy 1
  No energy consumption will be calculated for that device.


• powerMap_noPower 1
  No power consumption will be determined for that device and consequently no energy consumption at all.


• powerMap_rname_E
  Sets reading name for energy consumption.
  Default value is 'pM_energy'.


• powerMap_rname_P
  Sets reading name for power consumption.
  Default value is 'pM_consumption'.


• powerMap

          {
            '<reading>' => {
              '<value>' => <power>,
              '<value>' => <power>,
               ...
            },
  
            '<reading>' {
              '<value>' => <power>,
              '<value>' => <power>,
               ...
            },
  
            ...
          }

  (device specific)
  A Hash containing event(=reading) names and possible values of it. Each value can be assigned a corresponding power consumption.
  For devices with dimming capability intemediate values will be linearly interpolated. For this to work two separate numbers will be sufficient.
  
  Text values will automatically get any numbers extracted from it and be used for interpolation. (example: dim50% will automatically be interpreted as 50).
  In addition "off" and "on" will be translated to 0 and 100 respectively.
  If the value cannot be interpreted in any way, 0 power consumption will be assumed.
  Explicitly set definitions in powerMap attribute always get precedence.
  
  In case several power values need to be summarized, the name of other readings may be added after number value, separated by comma. The current status of that reading will then be considered for total power calculcation. To consider all readings powerMap knows, just add an *.
  
  Example for FS20 socket:

            'state' => {
              '0' => 0,
              '100' => 60,
            },
            

  
  
  
  Example for HUE white light bulb:

            'pct' => {
              '0' => 0.4,
              '10' => 1.2,
              '20' => 1.7,
              '30' => 1.9,
              '40' => 2.3,
              '50' => 2.7,
              '60' => 3.4,
              '70' => 4.7,
              '80' => 5.9,
              '90' => 7.5,
              '100' => 9.2,
            },
            'state' => {
              'unreachable' => 0,
              '*' => 'pct',
            },
            

  
  

rain

[EN DE]

Rain calculations. Offers different values from a rain sensor.
Define
define <name> rain <devicename-regex> [<rain_name> <israining_name> <new_name>]


Calculates rain values for device <devicename-regex> from incremental rain-value and israining-state and write it to some new readings named rain_calc_???????. If optional <rain_name>, <israining_name> and <new_name> is specified then read rain from reading <rain_name>, israining from reading <israining_name> and write the calculated rain to reading <new_name>.
The following values are generated:
• rain_calc_all --> all values in one line
• rain_calc_d_curr --> liter rain at the current day (from 7:30 local time)
• rain_calc_d_last --> liter rain of 24h before 7:30 local time
• rain_calc_d_start --> first incremental rain value from the rain device after 7:30 local time
• rain_calc_h_curr --> liter rain at the current hour (from XX:30)
• rain_calc_h_last --> liter rain of 1 hour before the last XX:30 time
• rain_calc_h_start --> first incremental rain value from the rain device after last XX:30
• rain_calc_now_diff --> fallen rain in liter since last value from rain device
• rain_calc_now_rate --> fallen rain in liter/hour since last value from rain device

Example:

    # Compute the rain for the rain/israining
    # events of the ks300 device and generate reading rain_calc.
    define rain_ks300 rain ks300

    

Set
N/A

Get
N/A

Attributes
• disable
• DontUseIsRaining 0/1
  Don't use the devicevalue IsRaining, if set to 1
• DayChangeTime HHMM
  Change the default (day)time of the 'set value to zero' time (use the timecode as four digits!)
  The minutevalue is used to set the (hour)time of the 'set value to zero' time
• CorrectionValue 1
  Use this value if you wish to do a correction of the rain-device-values. It is used as an factor. The value 1 will not change anything.

readingsChange

[EN DE]

Define
define <name> readingsChange <device> <readingName> <toReplace> <replaceWith>"

Change the content of a reading if it changes, with the perl string substitute mechanism. Note: As some modules rely on the known format of some readings, changing such readings may cause these modules to stop working.

<device>, <readingName> and <toReplace> are regular expressions, and are not allowed to contain whitespace. If replaceWith is enclosed in {}, then the content will be executed as a perl expression for each match.
Notes:
• after a Reading is set by a module, first the event-* attributes are evaluated, then userReadings, then stateFormat, then the readingsChange definitions (in alphabetical order), and after this the notifies, FileLogs, etc. again in alphabetical order.
• if stateFormat for the matched device is set, then it will be executed multiple times: once before the readingsChange, and once for every matching readingsChange.


Examples:
# shorten the reading power 0.5 W previous: 0 delta_time: 300
# to just power 0.5 W
define pShort readingsChange pm power (.*W).* $1

# format each decimal number in the power reading to 2 decimal places
define p2dec readingsChange pm power (\d+\.\d+) {sprintf("%0.2f", $1)}

Set
N/A

Get
N/A

Attributes
• disable
• disabledForIntervals
• addStateEvent

readingsGroup

[EN DE]

Displays a collection of readings from on or more devices.

Define
define <name> readingsGroup <device>[:regex] [<device-2>[:regex-2]] ... [<device-n>[:regex-n]]

Notes:
• <device> can be of the form INTERNAL=VALUE where INTERNAL is the name of an internal value and VALUE is a regex.
• <device> can be of the form ATTRIBUTE&VALUE where ATTRIBUTE is the name of an attribute and VALUE is a regex.
• <device> can be of the form <STRING> or <{perl}> where STRING or the string returned by perl is inserted as a line in the readings list. skipped if STRING is undef.
• <device> can be a devspec (see devspec) with at least one FILTER expression.
• If regex is a comma separatet list the reading values will be shown on a single line.
• If regex starts with a '+' it will be matched against the internal values of the device instead of the readings.
• If regex starts with a '?' it will be matched against the attributes of the device instead of the readings.
• If regex starts with a '!' the display of the value will be forced even if no reading with this name is available.
• If regex starts with a '$' the calculation with value columns and rows is possible.
• The following "set magic" prefixes and suffixes can be used with regex:
  • You can use an i:, r: or a: prefix instead of + and ? analogue to the devspec filtering.
  • The suffix :d retrieves the first number.
  • The suffix :i retrieves the integer part of the first number.
  • The suffix :r<n> retrieves the first number and rounds it to <n> decimal places. If <n> is missing, then rounds it to one decimal place.
  • The suffix :t returns the timestamp (works only for readings).
  • The suffix :sec returns the number of seconds since the reading was set. probably not realy usefull with readingsGroups.
• regex can be of the form <regex>@device to use readings from a different device.
  if the device name part starts with a '!' the display will be foreced. use in conjunction with ! in front of the reading name.
• regex can be of the form <regex>@{perl} to use readings from a different device.
• regex can be of the form <STRING> or <{perl}[@readings]> where STRING or the string returned by perl is inserted as a reading or:
  • the item will be skipped if STRING is undef
  • if STRING is br a new line will be started
  • if STRING is hr a horizontal line will be inserted
  • if STRING is tfoot the table footer is started
  • if STRING is of the form %ICON[%CMD] ICON will be used as the name of an icon instead of a text and CMD as the command to be executed if the icon is clicked. also see the commands attribute.
  if readings is given the perl expression will be reevaluated during longpoll updates.
• If the first regex is '@<index>' it gives the index of the following regex by which the readings are to be grouped. if capture groups are used they can be refferenced by #<number>. eg:
  
  <IP-Adress><Hostname><MAC><Vendor>
nmap:@2,<#1>,(.*)_hostname,#1_macAddress,#1_macVendor
• For internal values and attributes longpoll update is not possible. Refresh the page to update the values.
• the <{perl}> expression is limited to expressions without a space. it is best just to call a small sub in 99_myUtils.pm instead of having a compex expression in the define.

Examples:
define batteries readingsGroup .*:battery

define temperatures readingsGroup s300th.*:temperature
define temperatures readingsGroup TYPE=CUL_WS:temperature

define culRSSI readingsGroup cul_RSSI=.*:+cul_RSSI

define heizung readingsGroup t1:temperature t2:temperature t3:temperature
attr heizung notime 1
attr heizung mapping {'t1.temperature' => 'Vorlauf', 't2.temperature' => 'Rücklauf', 't3.temperature' => 'Zirkulation'}
attr heizung style style="font-size:20px"

define systemStatus readingsGroup sysstat
attr systemStatus notime 1
attr systemStatus nostate 1
attr systemStatus mapping {'load' => 'Systemauslastung', 'temperature' => 'Systemtemperatur in °C'}

define Verbrauch readingsGroup TYPE=PCA301:state,power,consumption
attr Verbrauch mapping %ALIAS
attr Verbrauch nameStyle style="font-weight:bold"
attr Verbrauch style style="font-size:20px"
attr Verbrauch valueFormat {power => "%.1f W", consumption => "%.2f kWh"}
attr Verbrauch valueIcon { state => '%devStateIcon' }
attr Verbrauch valueStyle {($READING eq "power" && $VALUE > 150)?'style="color:red"':'style="color:green"'}

define rg_battery readingsGroup TYPE=LaCrosse:[Bb]attery
attr rg_battery alias Batteriestatus
attr rg_battery commands { "battery.low" => "set %DEVICE replaceBatteryForSec 60" }
attr rg_battery valueIcon {'battery.ok' => 'batterie', 'battery.low' => 'batterie@red'}

define rgMediaPlayer readingsGroup myMediaPlayer:currentTitle,<>,totaltime,
,currentAlbum,<>,currentArtist,
,volume,<{if(ReadingsVal($DEVICE,"playStatus","")eq"paused"){"%rc_PLAY%set+$DEVICE+play"}else{"%rc_PAUSE%set+$DEVICE+pause"}}@playStatus>,playStatus
attr rgMediaPlayer commands { "playStatus.paused" => "set %DEVICE play", "playStatus.playing" => "set %DEVICE pause" }
attr rgMediaPlayer mapping  
attr rgMediaPlayer notime 1
attr rgMediaPlayer valueFormat { "volume" => "Volume: %i" }
#attr rgMediaPlayer valueIcon { "playStatus.paused" => "rc_PLAY", "playStatus.playing" => "rc_PAUSE" }



Set
• hide
  will hide all visible instances of this readingsGroup
• show
  will show all visible instances of this readingsGroup
• toggle
  will toggle the hidden/shown state of all visible instances of this readingsGroup
• toggle2
  will toggle the expanded/collapsed state of all visible instances of this readingsGroup

Get

Attributes
• alwaysTrigger
  1 -> always trigger update events. even if not visible.
  2 -> trigger events for calculated values.


• disable
  1 -> disable notify processing and longpoll updates. Notice: this also disables rename and delete handling.
  2 -> also disable html table creation
  3 -> also disable html creation completely


• sortDevices
  1 -> sort the device lines alphabetically. use the first of sortby or alias or name that is defined for each device.
• noheading
  If set to 1 the readings table will have no heading.


• nolinks
  Disables the html links from the heading and the reading names.


• nostate
  If set to 1 the state reading is excluded.


• nonames
  If set to 1 the reading name / row title is not displayed.


• notime
  If set to 1 the reading timestamp is not displayed.


• mapping
  Can be a simple string or a perl expression enclosed in {} that returns a hash that maps reading names to the displayed name. The keys can be either the name of the reading or <device>.<reading> or <reading>.<value> or <device>.<reading>.<value>. %DEVICE, %ALIAS, %ROOM, %GROUP, %ROW and %READING are replaced by the device name, device alias, room attribute, group attribute and reading name respectively. You can also prefix these keywords with $ instead of %. Examples:
  attr temperatures mapping $DEVICE-$READING
attr temperatures mapping {temperature => "%DEVICE Temperatur"}


• separator
  The separator to use between the device alias and the reading name if no mapping is given. Defaults to ':' a space can be enteread as  


• setList
  Space separated list of commands, which will be returned upon "set name ?", so the FHEMWEB frontend can construct a dropdown and offer on/off switches. set commands not in this list will be rejected.


• setFn
  perl expresion that will be executed for the commands from the setList. has access to $CMD and $ARGS.


• style
  Specify an HTML style for the readings table, e.g.:
  attr temperatures style style="font-size:20px"


• cellStyle
  Specify an HTML style for a cell of the readings table. regular rows and colums are counted starting with 1, the row headings are column number 0. perl code has access to $ROW and $COLUMN. keys for hash lookup can be r:#, c:# or r:#,c:# , e.g.:
  attr temperatures cellStyle { "c:0" => 'style="text-align:right"' }


• nameStyle
  Specify an HTML style for the reading names, e.g.:
  attr temperatures nameStyle style="font-weight:bold"


• valueStyle
  Specify an HTML style for the reading values, e.g.:
  attr temperatures valueStyle style="text-align:right"


• valueColumn
  Specify the minimum column in which a reading should appear.
  attr temperatures valueColumn { temperature => 2 }


• valueColumns
  Specify an HTML colspan for the reading values, e.g.:
  attr wzReceiverRG valueColumns { eventdescription => 'colspan="4"' }


• valueFormat
  Specify an sprintf style format string used to display the reading values. If the format string is undef this reading will be skipped. Can be given as a string, a perl expression returning a hash or a perl expression returning a string, e.g.:
  attr temperatures valueFormat %.1f °C
attr temperatures valueFormat { temperature => "%.1f °C", humidity => "%i %%" }
attr temperatures valueFormat { ($READING eq 'temperature')?"%.1f °C":undef }


• valuePrefix
  text to be prepended to the reading value


• valueSuffix
  text to be appended after the reading value
  attr temperatures valueFormat { temperature => "%.1f", humidity => "%i" }
attr temperatures valueSuffix { temperature => "°C", humidity => " %" }


• nameIcon
  Specify the icon to be used instead of the reading name. Can be a simple string or a perl expression enclosed in {} that returns a hash that maps reading names to the icon name. e.g.:
  attr devices nameIcon $DEVICE


• valueIcon
  Specify an icon to be used instead of the reading value. Can be a simple string or a perl expression enclosed in {} that returns a hash that maps reading value to the icon name. e.g.:
  attr devices valueIcon $VALUE
attr devices valueIcon {state => '%VALUE'}
attr devices valueIcon {state => '%devStateIcon'}
attr rgMediaPlayer valueIcon { "playStatus.paused" => "rc_PLAY", "playStatus.playing" => "rc_PAUSE" }


• commands
  Can be used in to different ways:
  • To make a reading or icon clickable by directly specifying the command that should be executed. eg.:
    attr rgMediaPlayer commands { "playStatus.paused" => "set %DEVICE play", "playStatus.playing" => "set %DEVICE pause" }
  • Or if the mapped command is of the form <command>:[<modifier>] then the normal FHEMWEB webCmd widget for <modifier> will be used for this command. if <modifier> is omitted then the FHEMWEB lookup mechanism for <command> will be used. eg:
    attr rgMediaPlayer commands { volume => "volume:slider,0,1,100" }
attr lights commands { pct => "pct:", dim => "dim:" }
  • commands can be used for attribtues. eg:
    attr commands { disable => "disable:" }


• visibility
  if set to hidden or hideable will display a small button to the left of the readingsGroup name to expand/hide the contents of the readingsGroup. if a readingsGroup is expanded then all others in the same group will be hidden.
  
  hidden -> default state is hidden but can be expanded
  hideable -> default state is visible but can be hidden
  
  
  if set to collapsed or collapsible readingsGroup will recognise the specials <->,<+> and <+-> as the first elements of a line to add a + or - symbol to this line. clicking on the + or - symbol will toggle between expanded and collapsed state. if a readingsGroup is expanded then all others in the same group will be collapsed.
  - -> line will be visible in expanded state
  + -> line will be visible in collapsed state
  +- -> line will be visible in both states
  
  collapsed -> default state is collapsed but can be expanded
  collapsible -> default state is visible but can be collapsed
• headerRows
  
• sortColumn
  > 0 -> automatically sort the table by this column after page loading 0 -> do not sort automatically but allow sorting of the table by clicking on a column header < 0 -> automatically sort the table in reverse by this column after page loading


• perlSyntaxCheck

For the hash version of all mapping attributes it is possible to give a default value with { '' => <default> }.

The style attributes can also contain a perl expression enclosed in {} that returns the style string to use. For nameStyle and valueStyle The perl code can use $DEVICE,$READING,$VALUE and $NUM, e.g.:

attr batteries valueStyle {($VALUE ne "ok")?'style="color:red"':'style="color:green"'}
attr temperatures valueStyle {($DEVICE =~ m/aussen/)?'style="color:green"':'style="color:red"'}

Note: Only valueStyle, valueFomat, valueIcon and <{...}@reading> are evaluated during longpoll updates and valueStyle has to return a non empty style for every possible value. All other perl expressions are evaluated only once during html creation and will not reflect value updates with longpoll. Refresh the page to update the dynamic style. For nameStyle the color attribut is not working at the moment, the font-... and background attributes do work.

Calculation: to be written...
eg: define rg readingsGroup .*:temperature rg:$avg
please see a description in the wiki

readingsHistory

[EN DE]

Displays a history of readings from on or more devices.

Define
define <name> readingsHistory [<device>[:regex] [<device-2>[:regex-2] ... [<device-n>[:regex-n]]]]

Notes:
• <device> can be of the form INTERNAL=VALUE where INTERNAL is the name of an internal value and VALUE is a regex.
• If regex is a comma separatet list it will be used as an enumeration of allowed readings.
• if no device/reading argument is given only lines with 'set <device> add ...' are displayed.

Examples:

Set
• add ...
  directly add text as new line to history.
• clear
  clear the history.

Get
• history
  list history

Attributes
• alwaysTrigger
  1 -> alwaysTrigger update events. even if not visible.
• disable
  1 -> disable notify processing and longpoll updates. Notice: this also disables rename and delete handling.
  2 -> also disable html table creation
  3 -> also disable html creation completely
• noheading
  If set to 1 the readings table will have no heading.
• nolinks
  Disables the html links from the heading and the reading names.
• notime
  If set to 1 the reading timestamp is not displayed.
• mapping
  Can be a simple string or a perl expression enclosed in {} that returns a hash that maps device names to the displayed name. The keys can be either the name of the reading or <device>.<reading>. %DEVICE, %ALIAS, %ROOM and %GROUP are replaced by the device name, device alias, room attribute and group attribute respectively. You can also prefix these keywords with $ instead of %.
• style
  Specify an HTML style for the readings table, e.g.:
  attr history style style="font-size:20px"
• timestampFormat
  POSIX strftime compatible string for used as the timestamp for each line.
• valueFormat
  Specify an sprintf style format string used to display the reading values. If the format string is undef this reading will be skipped. Can be given as a string, a perl expression returning a hash or a perl expression returning a string, e.g.:
  attr history valueFormat %.1f °C
attr history valueFormat { temperature => "%.1f °C", humidity => "%.1f %" }
attr history valueFormat { ($READING eq 'temperature')?"%.1f °C":undef }
• rows
  Number of history rows to show.

readingsProxy

[EN DE]

Makes (a subset of) a reading from one device available as a new device.
This can be used to map channels from 1-Wire, EnOcean or SWAP devices to independend devices that can have state,icons and webCmd different from the parent device and can be used in a floorplan.

Define
define <name> readingsProxy <device>:<reading>

Examples:
define myProxy readingsProxy myDS2406:latch.A


Set

Get

Attributes
• disable
  1 -> disable notify processing. Notice: this also disables rename and delete handling.
• getList
  Space separated list of commands, which will be returned upon "get name ?", so the FHEMWEB frontend can construct a dropdown. %PARENT% will result in the complete list of commands from the parent device. get commands not in this list will be rejected.
• setList
  Space separated list of commands, which will be returned upon "set name ?", so the FHEMWEB frontend can construct a dropdown and offer on/off switches. %PARENT% will result in the complete list of commands from the parent device. set commands not in this list will be rejected. Example: attr proxyName setList on off
• readingFnAttributes
• getFn
  perl expresion that will return the get command forwarded to the parent device. has access to $DEVICE, $READING, $CMD and $ARGS.
  undef -> do nothing
  "" -> pass through
  (<value>,1) -> directly return <value>, don't call parent getFn
  everything else -> use this instead
• setFn
  perl expresion that will return the set command forwarded to the parent device. has access to $CMD, $DEVICE, $READING and $ARGS.
  undef -> do nothing
  "" -> pass through
  everything else -> use this instead
  Examples:
  attr myProxy setFn {($CMD eq "on")?"off":"on"}
• valueFn
  perl expresion that will return the value that sould be used as state. has access to $LASTCMD, $DEVICE, $READING and $VALUE.
  undef -> do nothing
  "" -> pass through
  everything else -> use this instead
  Examples:
  attr myProxy valueFn {($VALUE == 0)?"off":"on"}


• perlSyntaxCheck

readingsWatcher

[EN DE]

The module monitors readings in other modules that its readings or their times change at certain intervals and
if necessary, triggers events that can be processed further with other modules (for example, notify, DOIF).
Forum : https://forum.fhem.de/index.php/topic,49408.0.html

Define
define <name> readingsWatcher

Defines a readingsWatcher device.

Afterwards each FHEM device has the new global attribute readingsWatcher
This attribute must be assigned at all monitored devices as follows:
Timeout in seconds, new Reading value, Reading1 of the device, Reading2, etc.

Example: A radio thermometer sends its values at regular intervals (eg.5 seconds)
If these remain off for a time X, the module can overwrite these invalid values with any other new value (Ex. ???)
The readingsWatcher attribute could be set here as follows:

attr myThermo readingsWatcher 300, ???, temperature

or if more than one reading should be monitored

attr myThermo readingsWatcher 300, ???, temperature, humidity

If readings are only to be monitored for their update and should not be overwritten
so the replacement string must be empty

Example : attr myThermo readingsWatcher 300,,temperature,humidity

other examples :
attr weather readingsWatcher 300,,temperature+humidity (new)
attr weather readingsWatcher 300,,temperature,humidity;3600,???,battery
Set
• active
• inactive
• checkNow
• clearReadings
Get
devices
Attribute


• delimiter
  separator for reading names ( e.g. device_reading) default _


• disable
  deactivate/activate the device


• interval <seconds>
  Time interval for continuous check (default 60)


• deleteUnusedReadings
  delete unused readings (default 1)


• readingActivity (default none)
  Similar to the HomeMatic ActionDetector, the module can set its own reading in the monitored device and save the monitoring status.
  attr <name> readingActivity actifity
  Creates the additional reading actifity in the monitored devices and supplies it with the status dead or alive
  attr <name> readingActivity activ:0:1
  Creates the additional reading activ in the monitored devices and supplies it with the status 0 or 1

remotecontrol

[EN DE]

Displays a graphical remote control. Buttons (=icons) can be chosen and arranged. Predefined layouts are available for e.g. Samsung-TV or iTunes. Any buttonclick can be forwarded to the actual fhem-device. For further explanation, please check the Wiki-Entry.

Define
define <rc-name> remotecontrol

Typical steps to implement a remotecontrol:


define rc1 remotecontrol	# defines a "blank" remotecontrol
get rc1 layout	# displays all available predefined layouts
set rc1 layout samsung	# assigns keys for a SamsungTV
set rc1 makenotify myTV	# creates notify_rc1 which forwards every buttonclick to myTV for execution
Note: keys can be changed at any time, it is not necessary to redefine the weblink
attr rc1 row15 VOLUP,VOLDOWN


Set
• set <rc-name> layout [delete|<layoutname>]
layout delete deletes all rowXX-attributes
  layout <layoutname> assigns a predefined layout to rowXX-attributes
• set <rc-name> makeweblink [<name>]
  creates a weblink to display the graphical remotecontrol. Default-name is weblink_<rc-name> .
• set <rc-name> makenotify <executingDevice>
  creates a notify to trigger <executingDevice> every time a button has been pressed. name is notify_<rc-name> .

Get
get <rc-name> [htmlcode|layout]

• htmlcode displays htmlcode for the remotecontrol on fhem-page
• layout shows which predefined layouts ae available

Attributes
• loglevel
• rc_iconpath
  path for icons, default is "icons" . The attribute-value will be used for all icon-files except .svg .
• rc_iconprefix
  prefix for icon-files, default is "" . The attribute-value will be used for all icon-files except .svg .
• Note: Icon-names (button-image-file-names) will be composed as fhem/<rc_iconpath>/<rc_iconprefix><command|image>
  For .svg -icons, the access sequence is according to the FHEMWEB-attribute iconPath, default is openautomation:fhemSVG:default .
• rc_devStateIcon
  In FHEMWEB-room-overview, displays the button-layout on the rc-device itself. Default is 1, set to 0 is the remotecontrol-device should not display its buttons in FHEMWEB roomview.


• rowXX
  attr <rc-name> rowXX <command>[:<image>][,<command>[:<image>]][,...]
  Comma-separated list of buttons/images per row. Any number of buttons can be placed in one row. For each button, use
• <command> is the command that will trigger the event after a buttonclick. Case sensitive.
• <image> is the filename of the image


• Per button for the remotecontrol, use
• <command> where an icon with the name <command> is displayed
  Example:
  attr rc1 rc_iconprefix black_btn_ # used for ALL icons on remotecontrol rc1
attr rc1 row00 VOLUP
  icon is black_btn_VOLUP, a buttonclick creates the event VOLUP
or
• <command>:<image> where an icon with the name <rc_iconprefix><image> is displayed
  Example:
  row00=LOUDER:VOLUP
  icon is black_btn_VOLUP, a buttonclick creates the event LOUDER
  Examples:
  attr rc1 row00 1,2,3,TV,HDMI
attr rc2 row00 play:PLAY,pause:PAUSE,louder:VOLUP,quieter:VOLDOWN
  
• Hint: use :blank for a blank space, use e.g. :blank,:blank,:blank for a blank row

restore

[EN DE]

restore list [<filename|directory>]
restore [<filename|directory>]
restore -a [<filename|directory>]

Restore the files saved previously by the update command. Check the available files with the list argument. See also the update command and its restoreDirs attribute. After a restore normally a "shutdown restart" is necessary.
If the -a option is specified, the configuration files are also restored.

rssFeed

[EN DE]

This device helps to extract data from an rss feed specified by the url given in the DEF section. Trhe results will be extracted to several corresponding readings. Also the headlines of the news elements will be extracted to a special "ticker"-string that could be retrieved via GET or a special function. The data will be updated automatically after the given interval.

Define
define <name> rssFeed <url> [interval]


url = url of the rss feed
interval = actualization interval in seconds
Minimum for this value is 600 and maximum is 86400

Example:
define rssGEA rssFeed http://www.gea.de/rss?cat=Region%20Reutlingen&main=true 3600

The example will retrieve the data from the rss feed every hour

Set
set <name> update
retrieving the data from feed and updateing readings data

Get

get <name> ticker
getting the headlines from the feed with specified formatting (also see attributes)

Attributes
• disable
  This attribute can be used to disable the entier feed device (1) or to activate it again (0 or attribute missing). If the device is disabled all readings will be removed, except the state reading which will then be set to "disabled". Data will no longer be automatically retrieved from the url. The ticker data contains only one line indicating the disabled ticker device. (s.a. attribute rfDisabledText).
  
• rfDisabledText
  The text in this attribute will be returnde by GET ticker when the device is disabled (s.a. attribute disable). If this attribute is not specified a default text is returned.
  Example: attr <name> rfDisabledText This feed is disabled
• rfTickerChars
  Specifies a string which will surround each headline in the ticker data.
  Example: attr <name> rfTickerChars +++
  Result: +++ This is a sample headline +++
  These characters are also used for "marquee"-ticker data.
  
• rfMaxLines
  Defines the maximum number of news items that will be extracted from the feed. If there are less items in the feed then specified by this attribute then only that few items are extracted. If this attribute is missing a default of 10 will be assumed.
  Example: attr <name> rfMaxLines 15
  
• rfDisplayTickerReadings
  If this attribute is set then there will be two additional readings containing the ticker data for "toast"-Tickers (same as rssFeedGetTicker()) and one containing the ticker data for "marquee"-tickers on a single line.
• rfEncode
  Defines an encoding which will be used for any text extracted from the feed that will be applied before setting the readings. Therefore the encode method of the Perl-core module Encode is used. If the attribute is missng then no encoding will be performed. Sometimes this is necessary when feeds contain wide characters that could sometimes lead to malfunction in FHEMWEB. Also the headlines data returned by rssFeedFunctions and get ticker are encoded using this method.
  This will be set to utf8 by default on first define
  
• rfReadings
  This attribute defines the readings that will be created from the extracted data. It is a comma separated list of the following values:
  • title = title section
    extract the title section of the feed and each news item to a corresponding reading
    
  • description = description section
    extract the description section of the feed and each news item to a corresponding reading
    
  • encodedContent = content:encoded section
    if present this contains a more detailed description
    
  • pubDate = Publication time of feed and of each news item will be extracted to a corresponding reading.
    
  • link = link url to the feed or to the full article of a single news items in the feed.
    
  • buildDate = time of the last feed actulization by the feed vendor.
    
  • imageURl = url of a probably available image of a news item
    
  • imageTitle = image title of a probably available news item image.
    
  If this attribute is missing "title,description,pubDate" will be assumed as default value. When the device is defined for the first time the attribute will be automatically created with the default value.
  
• rfCustomTextPrepFn
  Can specify a funtion located for example in 99_myUtils.pm This function will be uses for further modification of extracted feed data before setting it to the readings or the ticker list. The function will receive an id for the text type and the text itself. It must then return the modified Text.
  Possible text type ids are (s.a. rfReadings)
  
  • feedTitle
  • feedDescription
  • imageTitle
  • desctiption
  • encodedContent
  
  Example for 99_myUtils.pm:

  		
  #Text preparation for rssFeedDevices
  sub rssFeedPrep($$)
  {
  	my($texttype,$text) = @_;
  
  	#Cut the lenght of description texts to max 50 characters
  	my $tLn=length $text;
  	$text=substr($text,0,47).'...' if ($tLn >50 && ($texttype=~/description/));	
  
  	#filter Probably errorneous HASH(xxxxxx) from any texts	
  	return ' ' if ($text=~/HASH\(.*\)/);
  
  	#set a custom feed title reading
  	return 'My Special Title' if ($texttype =~/feedTitle/);
  
  	#returning modified text
  	return $text;
  }	
  		

  and then set the attribute to that function:
  attr <rssFeedDevice> rfCustomTextPrepFn rssFeedPrep
  
• rfAllReadingsEvents
  If this attribute is set to 1 all Readings that are created or updated will generate appropriate events (depending on event-on-... attributes). By default no events are created for most Readings, especially not for the feed data Readings
• readingFnAttributes

Functions
• rssFeedGetTicker
  This function will returned the foratted headlines as a single string. Each headline will be separated by a new line character. The result of this function can for example be used in InfoPanel as ticker data. The function takes the name of a rssFeed device as single parameter. The result is the same as from get ticker as it uses this function too. Syntax: rssFeedGetTicker(<rssFeedDevice>)
  

Readings
Depending on the attribute rfReadings a bunch of readings is created from the extracted news feed data. Some of the readings ar prefixed to tell to which part of the feed the data belongs to.


• Nxx_
  readings with that prefix correspond to the news items in the feed. xx index of the news item
  Example showing the readings of a single news item
  
  N00_title
N00_descripton
N00_pubDate
  
• f_
  redings with that prefix correspond to the feed itself.
  Example of feed-readings:
  f_title
f_descripton
f_buildDate
  
• preparedLines
  This readings contains the number of new items that were extracted in the last update of the feed data.
• tickerToast
  This reading contains the same data that is returned by the rssFeedGetTicker() funciton (if attribute rfDisplayTickerReadings is set)
  Example: +++ Headline 1 +++ \n +++ Headline 2 +++ \n +++ Headline 3 +++
• tickerMarquee
  This reading contains the ticker data on a single line for "marquee" style tickers (if attribute rfDisplayTickerReadings is set)
  Example: Headline 1 +++ Hadline 2 +++ Headline 3 +++
• gzippedFeed
  Sometimes RSS-Feed data is delivered gzipped. This is automatically recognized by the module. So if the received data was originally gzipped this reading is set to 1 otherwise it is set to 0
• state
  The state reading contains the timestamp of the last automatic or manual update of the device data from the feed, as long as the device is not disabled. If the device is disabled state contains "disabled". When the device is defined then the start of cyclic updates is retarded for about 10 seconds. During that time state is set to "defined"

search

[EN DE]

search <search expression>
Searches FHEM for devices, modules, developer packages, keywords, authors/maintainers and Perl packages.
This command requires a device instance of the FHEM Installer module. If no local Installer device is present, the first run of this command will create one.

Have a look to the 'Get search' command of the FHEM Installer to learn more about how to search.

sequence

Define
define <name> sequence <re1> <timeout1> <re2> [<timeout2> <re3> ...]

A sequence is used to allow to trigger events for a certain combination of button presses on a remote. E.g. to switch on a lamp when pressing the Btn1:on, then Btn2:off and at last Btn1:on one after the other you could define the following:


define lampseq sequence Btn1:on 0.5 Btn2:off 0.5 Btn1:on
define lampon notify lampseq:trigger set lamp on

Subsequent patterns can be specified without device name as :<re2>. This will reuse the device name which triggered the previous sequence step:

define lampseq sequence Btn.:on 0.5 :off


You can specify timeout as <delay>:<timeout>, where "delay" sets time during which the next event shall not be received, otherwise the sequence will be aborted. This can be used to capture press and hold of a button. Example:

define lampseq sequence Btn1:on 2:3 Btn1:off

sequence will be triggerred if Btn1 is pressed for 2 to 5 seconds.
Note: the global variable $data{sequence_source} is set to the name of the device triggering the last event.

Set
N/A

Get
N/A

Attributes
• addStateEvent
• disable
• disabledForIntervals
• triggerPartial
  if set (to 1), and not all the events of a sequence are received, then a partial_X event is generated by the sequence. Example:
  
  fhem> define seq sequence d1:on 1 d1:on 1 d1:on
  fhem> attr seq triggerPartial
  fhem> set d1 on;; sleep 0.5;; set d1 on
  
  generates the event seq partial_2. This can be used to assign different tasks for a single button, depending on the number of times it is pressed.


• reportEvents
  if set (to 1), report the events (space separated) after the "trigger" or "partial_X" keyword. This way one can create more general sequences, and create different notifies to react:
  
  define seq sequence remote:btn.* 1 remote:btn.*
attr seq reportEvents
define n_b1b2 notify seq:trigger.remote:btn1.remote:btn2 set lamp1 on
define n_b2b1 notify seq:trigger.remote:btn2.remote:btn1 set lamp1 off



• strictSequence
  if set (to 1), any "unexpected" event will reset the sequence. This may be helpful to avoid brute-force attacks.
  Note: it will only work correctly if the sequence is triggered only by the configured devices (check the NOTIFYDEV internal), and the source is not generating "undesired" events together with the desired ones.

serviced

With serviced you are able to control running services either running on localhost or a remote host.
The usual command are available: start/restart/stop/status.



Define

define <name> serviced <service name> [<user@ip-address>]


Example for running serviced for local service(s):


define hb serviced homebridge


Example for running serviced for remote service(s):


define hyp serviced hyperion pi@192.168.1.4


For remote services you have to grant passwordless ssh access for the user which is running FHEM (usually fhem). You'll find a tutorial how to do that by visiting this link.

To use systemctl (systemd) or service (initd) you have to grant permissions to the system commands for the user which is running FHEM (usually fhem) by editing the sudoers file (/etc/sudoers) (visudo).

For systemd (please check your local paths):

fhem ALL=(ALL) NOPASSWD:/bin/systemctl

For initd (please check your local paths):

fhem ALL=(ALL) NOPASSWD:/usr/sbin/service


If you have homebridgeMapping in your attributes an appropriate mapping will be added, genericDeviceType as well.


Set

• start
  start the stopped service
• stop
  stop the started service
• restart
  restart the service
• status
  get status of service



Get

• status
  get status of service
  same like 'set status'



Attributes

• serviceAutostart
  delay in seconds to automatically (re)start service after start of FHEM
  default:
• serviceAutostop
  timeout in seconds to automatically stop service while shutdown of FHEM
  default:
• serviceGetStatusOnInit
  get status of service automatically on FHEM start
  default: 1
• serviceInitd
  use initd (system) instead of systemd (systemctl)
  default: 0
• serviceLogin
  ssh login string for services running on remote hosts
  passwordless ssh is mandatory
  default:
• servicePort
  ssh port to use if other than default port (22)
  default: 22
• serviceRegexFailed
  regex for failed status
  default: dead|failed|exited
• serviceRegexStarted
  regex for running status
  default: running|active
• serviceRegexStarting
  regex for starting status
  default: activating|starting
• serviceRegexStopped
  regex for stopped status
  default: inactive|stopped
• serviceStatusInterval
  interval of getting status automatically
  default:
• serviceStatusLine
  line number of status output containing the status information
  default: 3
• serviceSudo
  use sudo
  default: 1



Readings

All readings updates will create events.

• error
  last occured error, none if no error occured
  
• state
  current state
• status
  last status line from 'get/set status'

siri

[EN DE]

Module to control the FHEM/Siri integration.

Notes:
• 
  
Attr
• siriName
  The name to use for a device with siri.

speedtest

[EN DE]

Provides internet speed data via speedtest-cli.

Notes:
• speedtest-cli hast to be installed on the FHEM host.
Define
define <name> speedtest [<interval> [<server>]]

Defines a speedtest device.

The data is updated every <interval> seconds. The default is 3600 and the minimum is 1800.

<server> gives the speedtest sever id. the list of all servers is available with

speedtest-cli --list

. Examples:
define speedtest speedtest
define speedtest speedtest 3600 2760


Readings
• ping
• download
• upload

Set
• statusRequest
  manualy start a test. this works even if the device is set to disable.
Attributes
• path
  The path to the speedtest binary.
• checks-till-disable
  how often the speedtest should be run before it is automaticaly set to disabled. the value will be decreased by 1 for every run.
• disable
  set to 1 to disable the test.
• ookla
  set to 1 to use the official ookla speedtest cli binary. will be searched in /usr/local/bin if path is not set.

statistics

[EN DE]

This modul calculates for certain readings of given devices statistical values and adds them to the devices.
For detail instructions, look at and please maintain the FHEM-Wiki.
Until now statistics for the following readings are automatically built:


• Min|Avg|Max Minimum, average and maximum of instantaneous values:
  over a period of day, month and year:
  current, energy_current, humidity, luminosity, temperature, voltage
  over a period of hour, day, month and year:
  brightness, wind, wind_speed, windSpeed


• Tendency over 1h, 2h, 3h und 6h: pressure


• Delta between start and end values - over a period of hour, day, month and year:
  count, energy, energy_total, power, total, rain, rain_rate, rain_total


• Duration (and counter) of the states (on, off, open, closed...) over a period of day, month and year:
  lightsensor, lock, motion, Window, window, state (if no other reading is recognized)


Further readings can be added via the attributes deltaReadings, durationReadings, minAvgMaxReadings, tendencyReadings. This allows also to assign a reading to another statistic type.

Define

define <name> statistics <deviceNameRegExp> [Prefix]
Example: define Statistik statistics Sensor_.*|Wettersensor
 
• <DeviceNameRegExp>
  Regular expression of device names. !!! Not the device readings !!!


• [Prefix]
  Optional. Prefix set is place before statistical data. Default is stat

Set

• resetStatistics <All|DeviceName>
  Resets the statistic values of the selected device.


• doStatistics
  Calculates the current statistic values of all monitored devices.


• setStatistics <device> <reading> <period> <value>
  Sets a statistic value to a fixed value. Period is one of Hour, Day, Month, Year.
  Implemented for delta readings only (Hour, Day, Month, Year) Hint: covers not last readings

Get

not implemented yet

Attributes

• dayChangeTime <time>
  Time of day change. Default is 00:00. For weather data the day change can be set e.g. to 06:50.


• deltaReadings <readings>
  Comma separated list of reading names for which a delta statistic shall be calculated.


• durationPeriodHour < 1 | 0 >
  If set to 1, then duration readings will get hourly statistics too.


• durationReadings <readings>
  Comma separated list of reading names for which a duration statistic shall be calculated.


• excludedReadings <DeviceRegExp:ReadingNameRegExp>
  Regular expression of the readings that shall be excluded from the statistics.
  The reading have to be entered in the form deviceName:readingName.
  E.g. FritzDect:current|Sensor_.*:humidity
• ignoreDefaultAssignments < 0 | 1 >
  Ignores the default assignments of readings to a statistic type (see above).
  So, only the readings that are listed in the specific attributes are evaluated.
  


• limitDecimals <reading:decimals>
  Space separated list of reading:decimals to set the maximun number of decimal places after decimal point.
  Valid only for Delta und Avg.
  


• minAvgMaxReadings <readings>
  Comma separated list of reading names for which a min/average/max statistic shall be calculated.


• periodChangePreset <seconds>
  Preponed start of the calculation of periodical data. Default is 5 second before each full hour.
  Allows thus the correct timely assignment within plots. Should be adapted to the CPU speed or load of the server.
  


• singularReadings <DeviceRegExp:ReadingRegExp>:statTypes:period
  • statTypes: Min|Avg|Max|Delta|DurationState|Tendency
  • period: Hour|Day|Month|Year|1h|2h|3h|6h
  
  Regulare expression of statistic values, which for which singular readings are created additionally to the summary readings. Eases the creation of plots. For duration readings the name of the state has to be used as statTypes.
  Example:
  Wettersensor:rain:Delta:(Hour|Day)|(FritzDect:(current|power):(Avg|Max|Delta):(Hour|Day)
Badfenster:Window:(Open|Open_Count):Month


• specialDeltaPeriods <Device:Reading:Period:count1:count2:...>
  Creates for the given delta reading additional singular readings of the given numbers of a period (Hour, Day, Month)
  Regular expressions cannot be used. Additional readings or additional periods can be defined but have to be separated by a comma (without spaces).
  
  Example:
  attr Statistik specialDeltaPeriods Wettersensor:rain:Hour:06:72:96
  This will create 3 additional readings for the rain of the last 6, 72 and 96 hours.
  attr Statistik specialDeltaPeriods Wettersensor:rain:Hour:48,Wettersensor:rain:Day:30,EZaehler:energy:Month:6:12
  This will create 4 additional readings for the rain of the last 48 hours and the last 30 Days and the energy consumtion of the last 6 and 12 months.


• specialDeltaPeriodHours
  depreciated


• tendencyReadings <readings>
  Comma separated list of reading names for which a tendendy statistic shall be calculated.

structure

Define
define <name> structure <struct_type> <dev1> <dev2> ...

The structure device is used to organize/structure devices in order to set groups of them at once (e.g. switching everything off in a house).
The list of attached devices can be modified through the addstruct / delstruct commands. Each attached device will get the attribute <struct_type>=<name>
when it is added to the list, and the attribute will be deleted if the device is deleted from the structure.
The structure devices can also be added to a structure, e.g. you can have a building consisting of levels which consists of rooms of devices.
Example:

• define kitchen structure room lamp1 lamp2
• addstruct kitchen TYPE=FS20
• delstruct kitchen lamp1
• define house structure building kitchen living
• set house off



Set
• saveStructState <readingName>
  The state reading of all members is stored comma separated in the specified readingName.


• restoreStructState <readingName>
  The state of all members will be restored from readingName by calling "set memberName storedStateValue".

Every other set command is propagated to the attached devices. Exception: if an attached device has an attribute structexclude, and the attribute value matches (as a regexp) the name of the current structure.
If the set is of the form set <structure> [FILTER=<filter>] <type-specific> then :FILTER=<filter> will be appended to the device name in the propagated set for the attached devices like this: set <devN>:FILTER=<filter> <type-specific>
If the last set parameter is "reverse", then execute the set commands in the reverse order.
If the last set parameter is given as "random:4" only 4 structure members will be selected randomly which will receive the given command.


Get
get is not supported through a structure device.

Attributes
• async_delay
  If this attribute is defined, unfiltered set commands will not be executed in the clients immediately. Instead, they are added to a queue to be executed later. The set command returns immediately, whereas the clients will be set timer-driven, one at a time. The delay between two timercalls is given by the value of async_delay (in seconds) and may be 0 for fastest possible execution. This way, excessive delays often known from large structures, can be broken down in smaller junks.
• disable
• disabledForIntervals
• considerDisabledMembers
  if set, consider disabled members when computing the overall state of the structure. If not set or set to 0, disabled members are ignored.
• clientstate_behavior
  The backward propagated status change from the devices to this structure works in two different ways.
  • absolute
    The structure status will changed to the common device status of all defined devices to this structure if all devices are identical. Otherwise the structure status is "undefined".
  • relative
    See below for clientstate_priority.
  • relativeKnown
    Like relative, but do not trigger on events not described in clientstate_priority. Needed e.g. for HomeMatic devices.
  • last
    The structure state corresponds to the state of the device last changed.
• clientstate_priority
  If clientstate_behavior is set to relative, then you have to set the attribute "clientstate_priority" with all states of the defined devices to this structure in descending order. Each group is delemited by space or /. Each entry of one group is delimited by "pipe". The status represented by the structure is the first entry of each group. Example:
  
  • attr kitchen clientstate_behavior relative
  • attr kitchen clientstate_priority An|On|on Aus|Off|off
  • attr house clientstate_priority Any_On|An All_Off|Aus
  In this example the status of kitchen is either on or off. The status of house is either Any_on or All_off.
• <struct_type>_map
  With this attribute, which has to specified for the structure- member, you can redefine the value reported by a specific structure-member for the structure value. The attribute has three variants:
  • readingName
    take the value from readingName instead of state.
  • oldVal:newVal
    if the state reading matches oldVal, then replace it with newVal
  • readingName:oldVal:newVal
    if readingName matches oldVal, then replace it with newVal
  Example:
  • define door OWSWITCH <ROMID>
  • define lamp1 dummy
  • attr lamp1 cmdlist on off
  • define kitchen structure struct_kitchen lamp1 door
  • attr kitchen clientstate_priority An|on OK|Aus|off
  • attr lamp1 struct_kitchen_map on:An off:Aus
  • attr door struct_kitchen_map A:open:on A:closed:off
  • attr door2 struct_kitchen_map A
  If this attribute is not set, the member devices state reading is taken, or, if also absent, the STATE internal.
• evaluateSetResult
  if a set command sets the state of the structure members to something different from the set command (like set statusRequest), then you have to set this attribute to 1 in order to enable the structure instance to compute the new status.
• filterEvents
  if set, and the device triggering the event has a struct_type map, then only events (i.e. reading names) contained in the structure map will trigger the structure. Note: only the readingName and readingName:oldVal:newVal entries of the struct_type map are considered.
• propagateAttr <regexp>
  if the regexp matches the name of the attribute, then this attribute will be propagated to all the members. The default is .* (each attribute) for featurelevel <= 5.9, else ^$ (no attribute). Note: the following attibutes were never propagated for featurelevel<=5.9
  alias async_delay clientstate_behavior clientstate_priority devStateIcon disable disabledForIntervals group icon room propagateAttr setStateIndirectly stateFormat webCmd userattr
• setStateIndirectly
  If true (1), set the state only when member devices report a state change, else the state is first set to the set command argument. Default is 0.
• setStructType
  If true (1), then the <struct-type> will be set as an attribute for each member device to the name of the structure. True is the default for featurelevel <= 5.8.
• structexclude
  Note: this is an attribute for the member device, not for the struct itself.
  Exclude the device from set/notify or attribute operations. For the set and notify the value of structexclude must match the structure name, for the attr/deleteattr commands ist must match the combination of structure_name:attribute_name. Examples:
  
  define kitchen structure room lamp1 lamp2
attr lamp1 structexclude kitchen
attr lamp1 structexclude kitchen:stateFormat

• readingFnAttributes

Systemd Watchdog Client

[EN DE]

Systemd allows monitoring of programs by a watchdog. If a process does not respond within a certain time interval, it will be stopped and restarted. This module periodically sends keep-alive message to the systemd.

fhem must be started under control of systemd. Watchdog must be also configured properly.
You can use the following script:


  
[Unit]
Description=FHEM Home Automation
Requires=network.target
After=dhcpcd.service

[Service]
Type=forking
NotifyAccess=all
User=fhem
Group=dialout

# Run ExecStartPre with root-permissions
ExecStartPre=-+/bin/mkdir -p /run/fhem
ExecStartPre=+/bin/chown -R fhem:dialout /run/fhem

# Run ExecStart with defined user and group
WorkingDirectory=/opt/fhem
ExecStart=/usr/bin/perl fhem.pl fhem.cfg
#ExecStart=/usr/bin/perl fhem.pl configDB   # use for configDB
TimeoutStartSec=240
TimeoutStopSec=120

# Stop service with root priviliges
ExecStop=+/usr/bin/pkill -F /run/fhem/fhem.pid

# Restart options: no, on-success, on-failure, on-abnormal, on-watchdog, on-abort, or always.
Restart=on-failure
RestartSec=3
WatchdogSec=180
PIDFile=/run/fhem/fhem.pid

[Install]
WantedBy=multi-user.target
  
  

Define

define <name> systemd_watchdog

Specifies the device.

tahoma

[EN DE]

The module realizes the communication with io-homecontrol® Devices e.g. from Somfy® or Velux®
A registered TaHoma® Connect gateway from Overkiz® sold by Somfy® which is continuously connected to the internet is necessary for the module.


Notes:
• JSON has to be installed on the FHEM host.
• on problems refer also the fhem forum IO-Homecontrol Devices über Tahoma Box einbinden

Define
define <name> tahoma ACCOUNT <username> <password>
define <name> tahoma DEVICE <DeviceURL>
define <name> tahoma PLACE <oid>
define <name> tahoma SCENE <oid>
define <name> tahoma GROUP <tahoma_device1>,<tahoma_device2>,<tahoma_device3>


A definition is only necessary for a tahoma device:
define <name> tahoma ACCOUNT <username> <password>
If a tahoma device of the type ACCOUNT is created, all other devices accessible by the tahoma gateway are automatically created!
If the account is valid, the setup will be read from the server.
All registered devices are automatically created with name tahoma_12345 (device number 12345 is used from setup)
All defined rooms will be are automatically created.
Also all defined scenes will be automatically created.
Groups of devices can be manually added to send out one group command for all attached devices


global Attributes for ACCOUNT:
If autocreate is disabled, no devices, places and scenes will be created automatically:
attr autocreate disable


local Attributes for ACCOUNT:
Normally, the web commands will be send asynchronous, and this can be forced to wait of the result by blocking=1
attr tahoma1 blocking 1


Normally, the login data is stored encrypted after the first start, but this functionality can be disabled by cryptLoginData=0
attr tahoma1 cryptLoginData 0


Normally, the command is send by 'iPhone', but it can be changed to a personal device name
attr tahoma1 devName myFHEM


The account can be completely disabled, so no communication to server is running:
attr tahoma1 disable 1


The interval [seconds] for refreshing and fetching all states can be set:
This is an old attribute, the default is 0 = off.
attr tahoma1 interval 300


The interval [seconds] for refreshing states can be changed:
The default is 120s, allowed minimum is 60s, 0 = off.
This command actualizes the states of devices, which will be externally changed e.g. by controller.
attr tahoma1 intervalRefresh 120


The interval [seconds] for fetching all states can be set:
The default is 0 = off, allowed minimum is 120s.
Normally this isn't necessary to set, because all states will be actualized by events.
attr tahoma1 intervalStates 300


The interval [seconds] for fetching new events can be changed:
The default is 2s, allowed minimum is 2s.
attr tahoma1 intervalEvents 10


The minimal interval [seconds] for first retry of login can be changed:
The default is 5s, allowed minimum is 5s.
attr tahoma1 intervalLoginMin 30


The maximal interval [seconds] for cyclic retry of login can be changed:
The default is 160s, allowed minimum is 160s.
attr tahoma1 intervalLoginMax 300



local Attributes for DEVICE:
If the closure value 0..100 should be 100..0, the level can be inverted:
attr tahoma_23234545 levelInvert 1


The closure value can be rounded to the muliple of an integer:
attr tahoma_23234545 levelRound 10
as result, the state and reading ClosureState is rounded to muliple of 10
0..4 becomes 0, 5..14 becomes 10, 15..24 becomes 20, ...


The device can be disabled:
The device is disabled then for direct access and indirect access by GROUP and PLACE, but not by SCENE.
attr tahoma_23234545 disable 1


local Attributes for PLACE:
The commands in a room will only affect the devices in the room with inClass=RollerShutter.
This can be extend or changed by setting the placeClasses attribute:
attr tahoma_abc12345 placeClasses RollerShutter ExteriorScreen Window


The place and its sub places can be disabled:
attr tahoma_abc12345 disable 1


local Attributes for SCENE:
The scene can be disabled:
attr tahoma_4ef30a23 disable 1


local Attributes for GROUP:
The group can be disabled:
attr tahoma_group1 disable 1


Examples:
define tahoma1 tahoma ACCOUNT abc@test.com myPassword
attr tahoma1 blocking 0
attr tahoma1 room tahoma


Automatic created device e.g.:
define tahoma_23234545 tahoma DEVICE io://0234-5678-9012/23234545
attr tahoma_23234545 IODev tahoma1
attr tahoma_23234545 alias RollerShutter Badezimmer
attr tahoma_23234545 room tahoma
attr tahoma_23234545 webCmd dim


Automatic created place e.g.:
define tahoma_abc12345 tahoma PLACE abc12345-0a23-0b45-0c67-d5e6f7a1b2c3
attr tahoma_abc12345 IODev tahoma1
attr tahoma_abc12345 alias room Wohnzimmer
attr tahoma_abc12345 room tahoma


Automatic created scene e.g.:
define tahoma_4ef30a23 tahoma SCENE 4ef30a23-0b45-0c67-d5e6-f7a1b2c32e3f
attr tahoma_4ef30a23 IODev tahoma1
attr tahoma_4ef30a23 alias scene Rolladen Südfenster zu
attr tahoma_4ef30a23 room tahoma


manual created group e.g.:
define tahoma_group1 tahoma GROUP tahoma_23234545,tahoma_23234546,tahoma_23234547
attr tahoma_group1 IODev tahoma1
attr tahoma_group1 alias Gruppe Rolladen Westen
attr tahoma_group1 room tahoma

telnet

[EN DE]

Define
define <name> telnet <portNumber> [global|hostname]
or
define <name> telnet <servername>:<portNumber>

First form, server mode:
Listen on the TCP/IP port <portNumber> for incoming connections. If the second parameter is not specified, the server will only listen to localhost connections. If the second parameter is global, telnet will listen on all interfaces, else it wil try to resolve the parameter as a hostname, and listen only on this interface.
To use IPV6, specify the portNumber as IPV6:<number>, in this case the perl module IO::Socket:INET6 will be requested. On Linux you may have to install it with cpan -i IO::Socket::INET6 or apt-get libio-socket-inet6-perl; OSX and the FritzBox-7390 perl already has this module.
Examples:
define tPort telnet 7072 global
attr tPort SSL
attr allowed_tPort allowed
attr allowed_tPort validFor tPort
attr allowed_tPort globalpassword mySecret

Note: The old global attribute port is automatically converted to a telnet instance with the name telnetPort. The global allowfrom attibute is lost in this conversion.

Second form, client mode:
Connect to the specified server port, and execute commands received from there just like in server mode. This can be used to connect to a fhem instance sitting behind a firewall, when installing exceptions in the firewall is not desired or possible. Note: this client mode supprts SSL, but not IPV6.
Example:
Start tcptee first on publicly reachable host outside the firewall.
perl contrib/tcptee.pl --bidi 3000
Configure fhem inside the firewall:
define tClient telnet <tcptee_host>:3000
Connect to the fhem from outside of the firewall:
telnet <tcptee_host> 3000

Set
N/A

Get
N/A

Attributes:
• prompt
  Sets the string for the telnet prompt, the default is fhem>


• SSL
  Enable SSL encryption of the connection. Valid values are 0 and 1, 0 being the default. A change requires a FHEM restart.
  If openssl is installed, a certifcate will be generated, here is a description on how to do that manually. If the attribute is set, the telnet program wont work as a client anymore, and a replacement is needed, like one of the following:
  socat openssl:fhemhost:fhemport,verify=0 readline
  ncat --ssl fhemhost fhemport
  openssl s_client -connect fhemhost:fhemport
  


• allowfrom
  Regexp of allowed ip-addresses or hostnames. If set, only connections from these addresses are allowed.
  NOTE: if this attribute is not defined and there is no valid allowed device defined for the telnet/FHEMWEB instance and the client tries to connect from a non-local net, then the connection is refused. Following is considered a local net:
  
  IPV4: 127/8, 10/8, 192.168/16, 172.16/10, 169.254/16
  IPV6: ::1, fe80/10
  


• connectTimeout
  Wait at maximum this many seconds for the connection to be established. Default is 2.


• connectInterval
  After closing a connection, or if a connection cannot be estblished, try to connect again after this many seconds. Default is 60.


• encoding
  Sets the encoding for the data send to the client. Possible values are latin1 and utf8. Default is utf8.


• sslVersion
  See the global attribute sslVersion.


• sslCertPrefix
  Set the prefix for the SSL certificate, default is certs/server-, see also the SSL attribute.

template

[EN DE]

template [use|show] <filename> [<param1>=<value1> [<param2>=<value2> [...]]]

Includes a file with parameter substitution, i.e. read the file and process every line as a FHEM command. For any given parameter/value pair <param>=<value> on the command line, a literal %<param>% in the file is replaced by <value> before executing the command.

This can be used to to code recurring definitions of one or several devices only once and use it many times. template show .. shows what would be done, including a parameter listing, while template use ... actually does the job. The word use can be omitted.

Example

File H.templ:

define %name% FHT %fhtcode%
attr %name% IODev CUN
attr %name% alias %alias%
attr %name% group %group%
attr %name% icon icoTempHeizung.png
attr %name% room %room%,Anlagen/Heizungen

define watchdog.%name% watchdog %name% 00:15:00 SAME set %name% report2 255
attr watchdog.%name% group %group%
attr watchdog.%name% room Control/Heizungen

define %name%.log FileLog /opt/fhem/log/%name%-%Y%m.log %name%:.*
attr %name%.log group %group%
attr %name%.log icon icoLog.png
attr %name%.log logtype fht
attr %name%.log room Control/Heizungen

define %name%.weblink SVG %name%.log:%name%:CURRENT
attr %name%.weblink label sprintf("Temperatur: %.0f °C (%.0f °C .. %.0f °C) Aktor: %.0f %% (%.0f %% .. %.0f %%)", $data{currval1}, $data{min1}, $data{max1}, $data{currval2}, $data{min2}, $data{max2} )
attr %name%.weblink room %room%
attr %name%.weblink alias %alias%


Configuration:

te H.templ name=3.dz.hzg fhtcode=3f4a alias=Dachzimmerheizung group=Heizung room=Dachzimmer

Please note that although %Y% in the FileLog definition looks like a parameter, it is not substituted since no parameter Y is given on the command line. You get detailed information at verbosity level 5 when you run the command.

todoist

[EN DE]

A module to get a task list as readings from todoist. Tasks can be completed, updated and deleted. The modul comes with a weblink-widget to manage tasks comfortable.

As preparation to use this module, you need to get your API Symbol (API ID) from the preferences of your account.

Notes:

• JSON, Data::Dumper, Date::Parse, Digest::MD5, have to be installed on the FHEM host.




Define

define <name> todoist <PROJECT-ID>

PROJECT-ID: The ID of your project (=list).


Example:
define Einkaufsliste todoist 257528237




Set

• accessToken - set the API Symbol for your todoist app


• active - set the device active (starts the timer for reading task-list periodically)


• inactive - set the device inactive (deletes the timer, polling is off)


• newAccessToken - replace the saved token with a new one.


• getTasks - get the task list immediately, reset timer.


• getUsers - get the projects users immediately.


• addTask - create a new task. Needs title as parameter.


set <DEVICE> addTask <TASK_TITLE>[:<DUE_DATE>]

Additional Parameters are:

• title="<TITLE>" (string)
• dueDate (due_date)=<DUE_DATE> (can be free form text or format: YYYY-MM-DDTHH:MM)
• priority=the priority of the task (a number between 1 and 4, 4 for very urgent and 1 for natural).
• responsibleUid=the todoist-ID of the user who is responsible for accomplishing the current task
• assignedByUid=the todoist-ID of the user who assigned the current task
• order=the order of the task inside a project (the smallest value would place the task at the top)
• parentID=parent_id of the parent task.
• sectionID=section_id of the parent task.

Examples:

set <DEVICE> addTask <TASK_TITLE> dueDate=2017-01-15 priority=2

set <DEVICE> addTask <TASK_TITLE> dueDate=morgen


• updateTask - update a task. Needs Task-ID or todoist-Task-ID as parameter
  
  Possible additional parameters are:
  
  • dueDate (due_date)=<DUE_DATE> (can be free form text or format: YYYY-MM-DDTHH:MM)
  • priority=(1..4) (string)
  • title=<TITLE> (string)
  • responsibleUid=the todoist-ID of the user who is responsible for accomplishing the current task
  • assignedByUid=the todoist-ID of the user who assigned the current task
  • order=the order of the task inside a project (the smallest value would place the task at the top)
  • remove=<TYPE> (comma seperated list of attributes which should be removed from the task)
  
  Examples:
  
  set <DEVICE> updateTask ID:12345678 dueDate=2017-01-15 priority=1
set <DEVICE> updateTask 1 dueDate=übermorgen
set <DEVICE> updateTask TITLE:Brot dueDate=übermorgen
  
  
• moveTask - move a task to another parent, section or project. Expects Task-ID or todoist-Task-ID as parameter
  
  Possible additional parameters are:
  
  • parentID=todoist-ID of the new parent task.
  • projectID=todoist-ID of the receiving project.
  • sectionID=todoist-ID of the receiving section.
  
  
  
• completeTask - completes a task. Needs number of task (reading 'Task_NUMBER'), the title (TITLE:<TITLE>) or the todoist-Task-ID (ID:<ID>) as parameter
  
  set <DEVICE> completeTask <TASK-ID> - completes a task by number
  set <DEVICE> completeTask ID:<todoist-TASK-ID> - completes a task by todoist-Task-ID
  set <DEVICE> completeTask TITLE:<Task title> - completes a task by title (one word)
  set <DEVICE> completeTask title=<Task title> - completes a task by title (multiple words)
  
  
• closeTask - closes a task. Needs number of task (reading 'Task_NUMBER')m the title (TITLE:<TITLE>) or the todoist-Task-ID (ID:) as parameter
  Difference to complete is: regular task is completed and moved to history, subtask is checked (marked as done, but not moved to history),
  recurring task is moved forward (due date is updated).
  
  set <DEVICE> closeTask <TASK-ID> - completes a task by number
  set <DEVICE> closeTask ID:<todoist-TASK-ID> - completes a task by todoist-Task-ID
  set <DEVICE> closeTask TITLE:<Task title> - completes a task by title (one word)
  set <DEVICE> closeTask title=<Task title> - completes a task by title (multiple words)
  
  
• uncompleteTask - uncompletes a Task. Use it like complete.
  
  
• deleteTask - deletes a task. Needs number of task (reading 'Task_NUMBER'), title (TITLE:<TITLE>) or the todoist-Task-ID (ID:<ID>) as parameter
  
  set <DEVICE> deleteTask <TASK-ID> - deletes a task by number
  set <DEVICE> deleteTask ID:<todoist-TASK-ID> - deletes a task by todoist-Task-ID
  set <DEVICE> deleteTask TITLE:<Task title> - deletes a task by title (one word)
  set <DEVICE> deleteTask title=<Task title> - completes a task by title (multiple words)
  
  
• sortTasks - sort Tasks alphabetically
  
  
• clearList - deletes all Tasks from the list (only FHEM listed Tasks can be deleted)
  
  
• cChildProjects - searches for children and defines them if possible, deletes lists that are deleted in todoist (Attribut delDeletedLists)
  
  
• reorderTasks - expects a comma seperated list of todoist-IDs. Tasks will be reorders in the given order
  Example:
  
  set <DEVICE> reorderTasks 12345678,23456789,34567890
  
  



Attributes

• readingFnAttributes
• do_not_notify
• disable
• pollInterval get the list every pollInterval seconds. Default is 1800. Smallest possible value is 20.
  
  


• hideId
  • 0: show todoist-Task-ID (default)
  • 1: hide the todoist-Task-ID


• hideListIfEmpty
  • 0: don't hide list in widget, if empty (default)
  • 1: hide list in widget, if empty


• showPriority
  • 0: don't show priority (default)
  • 1: show priority


• showAssignedBy
  • 0: don't show assignedByUid (default)
  • 1: show assignedByUid


• showOrder
  • 0: don't show order no. of the task (default)
  • 1: show order number


• showParent
  • 0: don't show parent_id of the task
  • 1: show parent_id (default)


• showSection
  • 0: don't show section_id of the task
  • 1: show section_id (default)


• showChecked
  • 0: don't show if a task is checked (for tasks with parent_id)
  • 1: show if a task is checked (default)


• showDeleted
  • 0: don't show if a task is deleted (for tasks with parent_id)
  • 1: show if a task is deleted (default)


• showResponsible
  • 0: don't show responsibleUid (default)
  • 1: show responsibleUid


• showDetailWidget
  • 0: don't show widget in detail view of device
  • 1: show widget in detail view of device (default)


• getCompleted
  • 0: don't get completet tasks (default)
  • 1: get completed tasks
  
  ATTENTION: Only premium users have access to completed tasks!



• autoGetUsers
  • 0: don't get users automatically
  • 1: get users after every "getTasks" (default)


• avoidDuplicates
  • 0: don't check for duplicates (default)
  • 1: check for duplicates, deny new entries if task exists (exactly)


• delDeletedLists
  • 0: don't delete deleted childrens (default)
  • 1: delete deleted childrens


• listDivider
  set the divider for the Reading listText. Default is ", ".

Readings

• Task_XXX
  the tasks are listet as Task_000, Task_001 [...].
• Task_XXX_parentID
  parent ID of task XXX if not null
• Task_XXX_sectionID
  section ID of task XXX if not null
• Task_XXX_checked
  1 when a task with parent_id is checked
• Task_XXX_isDeleted
  1 when a task with parent_id is deleted
• Task_XXX_dueDate
  if a task has a due date, this reading should be filled with the date.
• Task_XXX_priority
  the priority of your task.
• Task_XXX_ID
  the todoist ID of Task_X.
• Task_XXX_completedAt
  only for completed Tasks (attribute getCompleted).
• Task_XXX_completedById
  only for completed Tasks (attribute getCompleted).
• Task_XXX_assignedByUid
  the user this task was assigned by.
• Task_XXX_responsibleUid
  the user this task was assigned to.
• Task_XXX_order
  shows the order no. of the task (attribute showOrder).
• User_XXX
  the lists users are listet as User_000, User_001 [...].
• User_XXX_ID
  the users todoist ID.
• listText
  a comma seperated list of tasks in the specified list. This may be used for TTS, Messages etc.
• count
  number of Tasks in list.
• error
  current error. Default is none.
• lastCompletedTask
  title of the last completed task.
• lastCreatedTask
  title of the last created task.
• lastDeletedTask
  title of the last deleted task.
• lastError
  last Error.
• state
  state of the todoist-Device



Weblinks

FHEMWEB weblink as frontend for one or more. There are 3 different ways to setup a todoist-weblink:


• Define a simple weblink for a Task list:
  
  define <NAME> weblink htmlCode {todoist_Html("<TODOIST-DEVCICENAME>")}
  
  
• Define a simple weblink for all active Task lists:
  
  define <NAME> weblink htmlCode {todoist_Html()}
  
  
• Define a simple weblink for a group of active Task lists:
  
  define <NAME> weblink htmlCode {todoist_Html('<REGEX-FILTER>')}
  
  
Examples:

define EinkaufslisteWeb weblink htmlCode {todoist_Html("Einkaufsliste")} - single list
define EinkaufslistenWeb weblink htmlCode {todoist_Html()} - all active lists
define PapaLists weblink htmlCode {todoist_Html("Papa_list.*")} - all active lists beginning with "Papa_list"


• Tasks can be sorted, updated and added inside the widget. You can reload a list and delete all entries of a list.
• To check (close) a task, click the checkbox in front of the completed task.
• A list can be sorted by by drag & drop. You can also move a task from one list to another. This deletes the task from the "old" list and
  adds it to the new one.
• The input field under the actual list can be used for adding tasks to this list. Leaving the field or pressing enter triggers addTask.
• Update a task by clicking it's text. You can edit the task in an input field. Leaving the field or pressing enter triggers updateTask.
• You can use parameters like "dueDate" in the input fields like this:
  Milch dueDate=morgen
• Clicking the cross behind every task deletes this one for good.
• Clicking the trashcan symbol in the title bar of every list deletes all tasks from the list.
• A list can be reloaded by clicking the round arrow symbol in the title bar of every list.
• A list is refreshed if a getTasks for this is fired (by interval or manually).

tradfri

[EN DE]

Module to control the integration of IKEA tradfri devices with FHEM.

Notes:
• JSON has to be installed on the FHEM host.
• tradfri-fhem node executable hast do be installed with sudo npm install -g tradfri-fhem
Set
• scene <name|id>
  
Get
• scenes
  
Attr
• tradfriFHEM-securityCode
  the security code on the back of the gateway
• tradfriFHEM-cmd
  The command to use as tradfri-fhem
• tradfriFHEM-params
  Additional tradfri-fhem cmdline params.
• createEventTimestampReading
  timestamp reading for every event received
  0 -> update reading without fhem event
  1 -> update reading with fhem event
  undef -> don't create reading
• createGroupReadings
  create 'artificial' readings for group devices.
  0 -> create readings only for group devices where createGroupReadings ist set to 1
  1 -> create readings for all group devices where createGroupReadings ist not set or set to 1
  undef -> do nothing

update

[EN DE]

update [-noSSL] [<fileName>|all|check|checktime|force] [http://.../controlfile]
or
update [add source|delete source|list|reset]

Update the FHEM installation. Technically this means update will download the controlfile(s) first, compare it to the local version of the file in the moddir/FHEM directory, and download each file where the attributes (timestamp and filelength) are different. Upon completion it triggers the global:UPDATE event.
-noSSL will use the http protocol instead of https, which might be necessary for some older distributions with outdated ciphers.
With the commands add/delete/list/reset you can manage the list of controlfiles, e.g. for thirdparty packages. Notes:
• The contrib directory will not be updated.
• The files are automatically transferred from the source repository (SVN) to the web site once a day, at 7:45 CET / CEST.
• The all argument is default.
• The force argument will disregard the local file.
• The check argument will only display the files it would download, and the last section of the CHANGED file.
• checktime is like check, but additionally displays the update timestamp of the new file, which is usually the version date +1 day.
• Specifying a filename will only download matching files (regexp).
See also the restore command.

Examples:

• update check
• update
• update force
• update check http://fhem.de/fhemupdate/controls_fhem.txt

Attributes (use attr global ...)
• updateInBackground
  If this attribute is set (to 1), the update will be executed in a background process. The return message is communicated via events, and in telnet the inform command is activated, in FHEMWEB the Event Monitor. Default is set. Set it to 0 to switch it off.


• updateNoFileCheck
  If set, the command won't compare the local file size with the expected size. This attribute was introduced to satisfy some experienced FHEM user, its default value is 0.


• backup_before_update
  If this attribute is set, an update will back up your complete installation via the backup command. The default is not set as update relies on the restore feature (see below).
  Example:
  
  attr global backup_before_update


• exclude_from_update
  Contains a space or comma separated list of fileNames (regexps) which will be excluded by an update. The special value commandref will disable calling commandref_join at the end, i.e commandref.html will be out of date. The module-only documentation is not affected and is up-to-date.
  Example:
  
  attr global exclude_from_update 21_OWTEMP.pm FS20.off.png
  The regexp is checked against the filename and the source:filename combination. To exclude the updates for FILE.pm from fhem.de, as you are updating it from another source, specify fhem.de.*:FILE.pm


• hideExcludedUpdates
  if set to 1, do not print messages about excluded updates.


• restoreDirs

uptime

[EN DE]

uptime [raw]

uptime shows FHEM uptime since last FHEM (re-)start.
if called with optional parameter "raw" only seconds will be shown,
without any fomatting.

version

[EN DE]

version [<filter>|revision] [noheader]

List the version of fhem.pl and all loaded modules. The optional parameter can be used to filter the ouput. The special filter value "revision" shows only the latest revision number since the last update.

The optional flag noheader disables the output of the header lines (Latest Revision, File, Rev, Last Change).

When issued via FHEMWEB command line, all executed JavaScript files with their corresponding version will be listed additionally.

Example output of version:

Latest Revision: 10814

File             Rev   Last Change

fhem.pl          10769 2016-02-08 12:11:51Z rudolfkoenig
90_at.pm         10048 2015-11-29 14:51:40Z rudolfkoenig
98_autocreate.pm 10165 2015-12-13 11:14:15Z rudolfkoenig
00_CUL.pm        10146 2015-12-10 10:17:42Z rudolfkoenig
10_CUL_HM.pm     10411 2016-01-08 15:18:17Z martinp876
...

Example output of version fhem.pl:

File             Rev   Last Change

fhem.pl          10397 2016-01-07 08:36:49Z rudolfkoenig


Example output of version fhem.pl noheader:

fhem.pl 10397 2016-01-07 08:36:49Z rudolfkoenig


vitoconnect

[EN DE]

vitoconnect implements a device for the Viessmann API Vitoconnect100 based on investigation of thetrueavatar
You need the user and password from the ViCare App account.
Attention: This module is limited to one 'installation' per account. If you have two or more heaters use one viessmann account and device for each heater.
For details see: FHEM Wiki (german)

vitoconnect needs the following libraries:
• Path::Tiny
• JSON
• DateTime
Use sudo apt install libtypes-path-tiny-perl libjson-perl libdatetime-perl or install the libraries via cpan. Otherwise you will get an error message "cannot load module vitoconnect".

Define
define <name> vitoconnect <user> <password> <interval>
It is a good idea to use a fake password here an set the correct one later because it is readable in the detail view of the device

Example:
define vitoconnect vitoconnect user@mail.xx fakePassword 60
set vitoconnect password correctPassword 60



Set

• update
  update readings immeadiatlely
• clearReadings
  clear all readings immeadiatlely
• password passwd
  store password in key store
• logResponseOnce
  dumps the json response of Viessmann server to entities.json, gw.json, actions.json in FHEM log directory
• HK1-Heizkurve-Niveau shift
  set shift of heating curve
• HK1-Heizkurve-Steigung slope
  set slope of heating curve
• HK1-Urlaub_Start start
  set holiday start time
  start has to look like this: 2019-02-02
• HK1-Urlaub_Ende end
  set holiday end time
  end has to look like this: 2019-02-16
• HK1-Urlaub_unschedule
  remove holiday start and end time
• HK1-Zeitsteuerung_Heizung schedule
  sets the heating schedule in JSON format
  e.g. {"mon":[],"tue":[],"wed":[],"thu":[],"fri":[],"sat":[],"sun":[]} is completly off and {"mon":[{"mode":"on","start":"00:00","end":"24:00","position":0}], "tue":[{"mode":"on","start":"00:00","end":"24:00","position":0}], "wed":[{"mode":"on","start":"00:00","end":"24:00","position":0}], "thu":[{"mode":"on","start":"00:00","end":"24:00","position":0}], "fri":[{"mode":"on","start":"00:00","end":"24:00","position":0}], "sat":[{"mode":"on","start":"00:00","end":"24:00","position":0}], "sun":[{"mode":"on","start":"00:00","end":"24:00","position":0}]} is on 24/7
• HK1-Betriebsart standby,dhw,dhwAndHeating,forcedReduced,forcedNormal
  sets HK1-Betriebsart to standby,dhw,dhwAndHeating,forcedReduced or forcedNormal
• HK1-Solltemperatur_comfort_aktiv activate,deactivate
  activate/deactivate comfort temperature
• HK1-Solltemperatur_comfort targetTemperature
  set comfort target temperatur
• HK1-Solltemperatur_eco_aktiv activate,deactivate
  activate/deactivate eco temperature
• HK1-Solltemperatur_normal targetTemperature
  sets the normale target temperature where targetTemperature is an integer between 3 and 37
• HK1-Solltemperatur_reduziert targetTemperature
  sets the reduced target temperature where targetTemperature is an integer between 3 and 37
• HK1-Name name
  sets the name of the circuit
• WW-einmaliges_Aufladen activate,deactivate
  activate or deactivate one time charge for hot water
• WW-Zirkulationspumpe_Zeitplan schedule
  sets the schedule in JSON format for hot water circulation pump
• WW-Zeitplan schedule
  sets the schedule in JSON format for hot water
• WW-Haupttemperatur targetTemperature
  targetTemperature is an integer between 10 and 60
  sets hot water main temperature to targetTemperature
• WW-Solltemperatur targetTemperature
  targetTemperature is an integer between 10 and 60
  sets hot water temperature to targetTemperature
• Urlaub_Start start
  set holiday start time
  start has to look like this: 2019-02-02
• Urlaub_Ende end
  set holiday end time
  end has to look like this: 2019-02-16
• Urlaub_unschedule
  remove holiday start and end time

Get

nothing to get here

Attributes
attr <name> <attribute> <value>

See commandref#attr for more info about the attr command.

Attributes:
• disable:
  stop communication with Viessmann server
• verbose:
  set the verbosity level
• vitoconnect_raw_readings:
  create readings with plain JSON names like 'heating.circuits.0.heating.curve.slope' instead of german identifiers
• vitoconnect_gw_readings:
  create readings from the gateway
• vitoconnect_actions_active:
  create readings for actions e.g. 'heating.circuits.0.heating.curve.setCurve'
Readings

vitoconnect sets one reading for every value delivered by the API (depends on the type and the settings of your heater and the version of the API!). Already known values will be mapped to clear names. Unknown values will added with their JSON path (e.g. "heating.burner.modulation.value"). Please report new readings to the module maintainer. A description of the known reading could be found here (german)

watchdog

[EN DE]

Define
define <name> watchdog <regexp1> <timespec> <regexp2> <command>

Start an arbitrary FHEM command if after <timespec> receiving an event matching <regexp1> no event matching <regexp2> is received.
The syntax for <regexp1> and <regexp2> is the same as the regexp for notify.
<timespec> is HH:MM[:SS]
<command> is a usual fhem command like used in the at or notify

Examples:
# Request data from the FHT80 _once_ if we do not receive any message for
# 15 Minutes.
define w watchdog FHT80 00:15:00 SAME set FHT80 date
# Request data from the FHT80 _each_ time we do not receive any message for
# 15 Minutes, i.e. reactivate the watchdog after it triggered. Might be
# dangerous, as it can trigger in a loop.
define w watchdog FHT80 00:15:00 SAME set FHT80 date;; trigger w .
# Shout once if the HMS100-FIT is not alive
define w watchdog HMS100-FIT 01:00:00 SAME "alarm-fit.sh"
# Send mail if the window is left open
define w watchdog contact1:open 00:15 contact1:closed "mail_me close window1"
attr w regexp1WontReactivate

Notes:

• if <regexp1> is . (dot), then activate the watchdog at definition time. Else it will be activated when the first matching event is received.
• <regexp1> resets the timer of a running watchdog, to avoid it use the regexp1WontReactivate attribute.
• if <regexp2> is SAME, then it will be the same as the first regexp, and it will be reactivated, when it is received.
• trigger <watchdogname> . will activate the trigger if its state is defined, and set it into state defined if its state is active (Next:...) or triggered. You always have to reactivate the watchdog with this command once it has triggered (unless you restart fhem)
• a generic watchdog (one watchdog responsible for more devices) is currently not possible.
• with modify all parameters are optional, and will not be changed if not specified.
• The variables $DEV, $NAME, $EVENT, $EVTPART*, $TYPE and $SELF are available in the executed code, see the notify documentation for details.


Set
• inactive
  Inactivates the current device. Note the slight difference to the disable attribute: using set inactive the state is automatically saved to the statefile on shutdown, there is no explicit save necesary.
  This command is intended to be used by scripts to temporarily deactivate the notify.
  The concurrent setting of the disable attribute is not recommended.
• active
  Activates the current device (see inactive).

Get
N/A

Attributes
• activateOnStart
  if set, the watchdog will be activated after a FHEM start if appropriate, determined by the Timestamp of the Activated and the Triggered readings. Note: since between shutdown and startup events may be missed, this attribute is 0 (disabled) by default.
• addStateEvent
• disable
• disabledForIntervals
• regexp1WontReactivate
  When a watchdog is active, a second event matching regexp1 will normally reset the timeout. Set this attribute to prevents this.


• regexp2WillReactivate
  Normally after an event matching regexp2 ist received, the watchdog is waiting for an event matching regexp1 to start the countdown. If this attribute set to 1 (the default 0), then after receivig an event matching regexp2 the countdown is reset and started. Note: if regexp1 and regexp2 are identical, or regexp2 is ., then this behavior is default.


• execOnReactivate
  If set, its value will be executed as a FHEM command when the watchdog is reactivated (after triggering) by receiving an event matching regexp1.


• autoRestart
  When the watchdog has triggered it will be automatically re-set to state defined again (waiting for regexp1) if this attribute is set to 1.


• completeOnDisabled
  If set (to 1), the watchdog will complete normally, even if at completion time disabled is active (see disabledForIntervals).

weblink

Define
define <name> weblink [link|image|iframe|htmlCode|cmdList|associatedWidth] <argument>

This is a placeholder device used with FHEMWEB to be able to add user defined links. Examples:
define homepage weblink link http://fhem.de
define webcam_picture weblink image http://w.x.y.z/current.jpg
define interactive_webcam weblink iframe http://w.x.y.z/webcam.cgi
define hr weblink htmlCode <hr>
define w_Frlink weblink htmlCode { WeatherAsHtml("w_Frankfurt") }
define systemCommands weblink cmdList\
pair:Pair:set+cul2+hmPairForSec+60\
restart:Restart:shutdown+restart\
update:UpdateCheck:update+check

define aw weblink associatedWith rgr_Residents 3

Notes:
• For cmdList <argument> consists of a list of space separated icon:label:cmd triples.
• the associatedWidth mode takes a devspec and an optional depth as arguments, and follows the devices along the "probably associated with" links seen on the detail page for depth iterations. The so collected data can be displayed as an SVG graph.
Set
N/A

Get
N/A

Attributes
• htmlattr
  HTML attributes to be used for link, image and iframe type of links. E.g.:
  
  define yw weblink iframe http://weather.yahooapis.com/forecastrss?w=650272&u=c
attr yw htmlattr width="480" height="560"

• nodetaillink
  Show no detail link for the types image and iframe.
• disable
• disabledForIntervals

weekprofile

With this module you can manage and edit different weekprofiles. You can send the profiles to different devices.
Currently the following devices will by supported:

• MAX
• other weekprofile modules
• Homematic via HM_CUL and channel _Clima or _Climate
• Homematic via HMCCUDEV, HMCCUCHN)

Additionally, also the following module types can be used as logical intermediates

• WeekdayTimer
• MQTT2_DEVICE

In the normal case the module is assoziated with a master device. So a profile 'master' will be created automatically. This profile corrensponds to the current active profile on the master device. You can also use this module without a master device. In this case a default profile will be created.

Note: WeekdayTimer and MQTT2_DEVICE TYPE devices can not be used as 'master'.

An other use case is the usage of categories 'Topics'. To enable the feature the attribute 'useTopics' have to be set. Topics are e.q. winter, summer, holidays, party, and so on. A topic consists of different week profiles. Normally one profile for each thermostat. The connection between the thermostats and the profile is an user attribute 'weekprofile' without the topic name. With 'restore_topic' the defined profile in the attribute will be transfered to the thermostat. So it is possible to change the topic easily and all thermostats will be updated with the correndponding profile.

Hint: weekprofile supports configdb and configdb migrate since svn: 21314.
You have to import the profile\config file into configdb manually if you update from an earlier version.

Attention: To transfer a profile to a device it needs a lot of Credits. This is not taken into account from this module. So it could be happend that the profile in the module and on the device are not equal until the whole profile is transfered completly.
If the maste device is Homatic HM-TC-IT-WM-W-EU then only the first profile (R_P1_...) will be used!
For this module libjson-perl have to be installed

Events:
Currently the following event will be created:

• PROFILE_TRANSFERED: if a profile or a part of a profile (changes) is send to a device
• PROFILES_SAVED: the profile are stored in the config file (also if there are no changes)
Define
define <name> weekprofile [master device]

Activate the module with or without an assoziated master device. The master device is an optional parameter. With a master device a spezial profile 'master' will be created.
Special master' profile handling:

• Can't be deleted
• Will be automatically transfered to the master device if it was modified
• Will not be saved

Without a master device a 'default' profile will be created
Set
• profile_data
  set <name> profile_data <profilename> <json data>
  The profile 'profilename' will be changed. The data have to be in json format.
• send_to_device
  set <name> send_to_device <profilename> [devices]
  The profile 'profilename' will be transfered to one or more the devices. Without the parameter device the profile will be transferd to the master device. 'devices' is a comma seperated list of device names
• copy_profile
  set <name> copy_profile <source> <destination>
  Copy from source to destination. The destination will be overwritten
• remove_profile
  set <name> remove_profile <profilename>
  Delete profile 'profilename'.
• reference_profile
  set <name> reference_profile <source> <destination>
  Create a reference from destination to source. The destination will be overwritten if it exits.
• restore_topic
  set <name> restore_topic <topic>
  All weekprofiles from the topic will be transfered to the correcponding devices. Therefore a user attribute 'weekprofile' with the weekprofile name without the topic name have to exist in the device.
• reread_master
  Refresh (reread) the master profile from the master device.
• import_profile
  set <name> import_profile <device> <[profilename]>
  Importing a profile from a supported device
Get
• profile_data
  get <name> profile_data <profilename>
  Get the profile data from 'profilename' in json-Format
• profile_names
  set <name> profile_names [topicname]
  Get a comma seperated list of weekprofile profile names from the topic 'topicname' If topicname is not set, 'default' will be used If topicname is '*', all weekprofile profile names are returned.
• profile_references [name]
  If name is '*', a comma seperated list of all references in the following syntax ref_topic:ref_profile>dest_topic:dest_profile are returned If name is 'topicname:profilename', '0' or the reference name is returned.
• topic_names
  Return a comma seperated list of topic names.
• associations [ReturnType (0|1)]
  Returns a list of supported devices with the associated profile.
  ReturnType 0: HTML table
  ReturnType 1: json list
  

Readings

• active_topic
  Active\last restored topic name
• profile_count
  Count of all profiles including references.
• topics
  List of topic names with ':' as delimiter
Attributes
• widgetTranslations
  Comma seperated list of texts translations : attr name widgetTranslations Abbrechen:Cancel,Speichern:Save
• widgetWeekdays
  Comma seperated list of week days starting at Monday attr name widgetWeekdays Monday,Tuesday,Wednesday,Thursday,Friday,Saturday,Sunday
• widgetEditOnNewPage
  Editing the profile on a new html page if it is set to '1'
• widgetEditDaysInRow
  Count of visible days in on row during Edit. Default 2.
  
• widgetTempRange
  Set the temperature range of the dropdown list in the FHEM widget Syntax: min:max:step e.g. 5:30:0.5
• tempMap
  Temperature key value pair Syntax: :,: e.g. off:5.0,on:30.0
• tempON
  deprecated - please use tempMap
• tempOFF
  deprecated - please use tempMap
• sendKeywordsToDevices
  Send temperatur keywords instead of temparture values to device Default: 0
• configFile
  Path and filename of the configuration file where the profiles will be stored Default: ./log/weekprofile-.cfg
• icon
  icon for edit
  Default: edit_settings
• useTopics
  Enable topics.
  Default: 0
• sendDelay
  Default: 0 Delay in seconds between sending profile data the same type of device. This is usefull to avoid messages like "queue is full, dropping packet" by HM devices
• forceCompleteProfile
  Default: 0 Force to send the complete profile to the device instead of only the changes. Possibility to resend a complete week profile
• weekprofile
  This attribute can be a userattr of supported modules of weekprofile to receive a specific profile with the defined name at the restore_topic command. See topics for further information

withings

[EN DE]

FHEM module for Withings devices.

Notes:
• JSON and Digest::SHA have to be installed on the FHEM host.

Define
define <name> withings ACCOUNT <login@email> <password>
define <name> withings <device>

Defines a withings device.

If a withings device of the account type is created all fhem devices for users and devices are automaticaly created.
Examples:
define withings withings ACCOUNT abc@test.com myPassword


Readings
• height
• weight
• fatFreeMass
• muscleRatio
• fatMassWeight
• fatRatio
• boneMassWeight
• boneRatio
• hydration
• diastolicBloodPressure
• systolicBloodPressure
• heartPulse
• heartECG
• heartSounds
• pulseWave
• spo2
• vascularAge
• bodyTemperature
• skinTemperature
• temperature
• dailySteps
• dailyDistance
• dailyElevation
• dailyDescent
• dailyDurationLight
• dailyDurationModerate
• dailyDurationIntense
• dailyCaloriesActive
• dailyCaloriesPassive
• sleepDurationAwake
• sleepDurationLight
• sleepDurationDeep
• sleepDurationREM
• sleepDurationTotal
• wakeupCount
• snoringDuration
• snoringEpisodeCount
• sleepScore
• co2
• temperature
• light
• noise
• voc
• batteryState
• batteryPercent

Get
• update
  trigger an update

Attributes
• interval*
  the interval in seconds used to check for new values.
  - intervalData: main user/device readings
  - intervalDebug: debugging/inofficial readings
  - intervalDaily: daily summarized activity data
  - intervalProperties: device properties
  - intervalAlert: camera alerts
  
• disable
  1 -> stop polling

xs1Bridge

[EN DE]

With this module you can read out the device xs1 from EZcontrol. There will be actors | Sensors | Timer | Information read from xs1 and written in readings. With each read only readings are created or updated, which are also defined and active in xs1. Actor | Sensor or timer definitions which are deactivated in xs1 are NOT read.

The module was developed based on the firmware version v4-Beta of the xs1. There may be errors due to different adjustments within the manufacturer's firmware.
Testet firmware: v4.0.0.5326 (Beta) @me | v3.0.0.4493 @ForumUser


Currently implemented types of xs1 for processing:

• Aktor: dimmer, switch, shutter, timerswitch
• Sensor: barometer, counter, counterdiff, light, motion, other, rain, rain_1h, rain_24h, rainintensity, remotecontrol, uv_index, waterdetector, winddirection, windgust, windspeed, windvariance


Define

xs1 without password:  define <NAME> xs1Bridge <IP>
xs1 with password:       define <NAME> xs1Bridge <User>:<Passwort>@<IP>

The module can not create without the IP of the xs1. If the IP can not be reached during module definition, the Define process is aborted.
• <IP> is IP address in the local network
• <User> is the administrator user admin (default)
• <Password> is the assigned administrator password in xs1

examples:
define EZcontrol_xs1 xs1Bridge 192.168.1.45
define EZcontrol_xs1 xs1Bridge admin:secret@192.168.1.45


Set
N/A

Get

N/A

Attributes
• debug (0,1,2)
  This brings the module into a very detailed debug output in the logfile. Program parts can be checked and errors checked.
  (Default, debug 0)


• update_only_difference (0,1)
  The actuators defined in xs1 are only updated when the value changes.
  (Default, update_only_difference 0)


• view_Device_name (0,1)
  The actor names defined in xs1 are read as Reading.
  (Default, view_Device_name 0)
  


• view_Device_function (0,1)
  The actuator functions defined in xs1 are read out as Reading.
  (Default, view_Device_function 0)
  


• xs1_blackl_aktor
  A comma-separated blacklist of actuators, which should not be created automatically as soon as xs1_control = 1(aktiv).
  (Example: 2,40,3)
  


• xs1_blackl_sensor
  A comma-separated blacklist of sensors, which should not be created automatically as soon as xs1_control = 1(aktiv).
  (Example: 3,37,55)
  


• xs1_control (0,1)
  Option to control the xs1. After activating this, the xs1Dev module creates each actuator and sensor in FHEM.
  (Default, xs1_control 0)
  
  
• xs1_interval (0,30,60,180,360)
  This is the interval in seconds at which readings are read from xs1
  For actuators, only different states are updated in the set interval.
  Sensors are always updated in intervals, regardless of the status.
  (Default, xs1_interval 60)




explanation:
• various Readings:
• Aktor_(01-64)
defined actuator in the device

• Aktor_(01-64)_name
defined actor name in the device

• Aktor_(01-64)_function(1-4)
defined actuator function in the device

• Sensor_(01-64)
defined sensor in the device

• Sensor_(01-64)_name
defined sensor name in the device

• Timer_(01-128)
defined timer in the device

• xs1_bootloader
version of bootloader

• xs1_dhcp
DHCP on/off

• xs1_features
purchased feature when buying (A = send | B = receive | C = Skripte/Makros | D = Media Access)

• xs1_firmware
firmware number

• xs1_start
device start



• The message "... Can't connect ..." or "ERROR: empty answer received" in the system logfile says that there was no query for a short time.
  (This can happen more often with DLAN.)
  
  
• If the device has not been connected after 5 connection attempts, the module will switch on < disable > !


• Create logfile automatically after define | scheme: define FileLog_xs1Bridge FileLog ./log/xs1Bridge-%Y-%m.log <name>
  The following values ​​are recorded in logfile: Timer | xs1-status information

xs1Dev

[EN DE]

This module works with the xs1Bridge module. (The xs1_control attribute in the xs1Bridge module must be set to 1!)
It communicates with this and creates all actuators of the xs1 as a device in FHEM. So you can control the actuators of the xs1 from the FHEM.

The module was developed based on the firmware version v4-Beta of the xs1. There may be errors due to different adjustments within the manufacturer's firmware.


Currently implemented types of xs1 for processing:

• Aktor: dimmer, switch, shutter, timerswitch
• Sensor: barometer, counter, counterdiff, light, motion, other, rain, rain_1h, rain_24h, rainintensity, remotecontrol, uv_index, waterdetector, winddirection, windgust, windspeed, windvariance


Define

define <name> xs1Dev <Typ> <ID> IODev=<NAME>

It is not possible to create the module without specifying type and ID of xs1.
• <ID> is internal id in xs1.
• <Typ> is the abbreviation A for actuators or S for sensors.

example:
define xs1Dev_Aktor_02 xs1Dev A 02 IODev=ezControl

Set
set <name> <value>

in which value one of the following values:

on
off
dimup
dimupdown
toggle
on, wait, off
absolut
wait
long on
long off
Stopp
on, wait, on
off, wait, off
impuls


Get

N/A

Attributes
• debug (0,1)
  This brings the module into a very detailed debug output in the logfile. Thus, program parts can be controlled and errors can be checked.
  (Default, debug 0)
• useSetExtensions (0,1)
  Toggles the SetExtensions on or off.
  (Default, useSetExtensions 0)

Explanation:
• abstract Internals:
xs1_function(1-4): defined function in the device
xs1_name: defined name in the device
xs1_typ: defined type in the device

yowsup

[EN DE]

Module to interface to the yowsup library to send and recive WhatsApp messages.

Notes:
• Probably only works on linux/unix systems.

Define
define <name> yowsup

Defines a yowsup device.

Examples:
define WhatsApp yowsup


Set
• image [<number>] <path> [<text>]
  sends an image with optional text. <number> has to be given if sending via master device.
• send [<numner>] <text>
  sends <text>. <number> has to be given if sending via master device.

Attributes
• cmd
  complette commandline to start the yowsup cli client
  eg: attr WhatsApp cmd /opt/local/bin/yowsup-cli demos -c /root/config.yowsup --yowsup
• home
  set $HOME for the started yowsup process
  PWD -> set to $PWD
  anything else -> use as $HOME
• nickname
  nickname that will be send as sender
• acceptFrom
  comma separated list of contacts (numbers) from which messages will be accepted
• commandPrefix
  not set -> don't accept commands
  0 -> don't accept commands
  1 -> allow commands, every message is interpreted as a fhem command
  anything else -> if the message starts with this prefix then everything after the prefix is taken as the command
• allowedCommands
  A comma separated list of commands that are allowed from this contact.
  If set to an empty list , (i.e. comma only) no commands are accepted.
  Note: allowedCommands should work as intended, but no guarantee can be given that there is no way to circumvent it.

Perl specials

[EN DE]

If you want to automate some tasks via FHEM, then you'll probably use at or notify. For more complex tasks you'll use either a shell-script or a perl "oneliner" as the at/notify argument. This chapter gives some tips in using the perl oneliners.

To test the following perl oneliners, type them on the telnet prompt (or FHEMWEB text input) by enclosing it in {}, one line at once. The last line will only write something in the logfile, the output of the other lines is directly visible.

{ "Hello" }
{ 1+3*4 }
{ `ls /etc` }
{ Log 1, "Hello" }

Perl expressions are separated by ;, in FHEM oneliners they have to escaped with ;;

{ my $a = 1+1;; Log 1, "Hello $a" }

To use FHEM commands from the perl expression, use the function fhem(), which takes a string argument, this string will be evaluated as a FHEM command:

{ fhem "set light on" }
define n1 notify piri:on { fhem "set light on" }

Note: if this function returns a value, it will also be logged into the global FHEM log. Use 1 as a second argument to disable this logging, this makes sense when obtainig some values via FHEM "get...".

Notify can be used to store macros for manual execution. Use the trigger command to execute the macro:

define MyMacro notify MyMacro { Log 1, "Hello"}
trigger MyMacro
define MacroWithArg notify MyMacro { Log 1, "Hello %"}
trigger MyMacro MyArg

To make date and time handling easier, the variables $sec, $min, $hour, $mday, $month, $year, $wday, $yday, $isdst are available in the perl oneliners (see also perldoc -f localtime). Exceptions: $month is in the range of 1 to 12, and $year is corrected by 1900 (as I would expect). Additionally the variable $hms contains the time in the HH:MM:SS format and $today the current date in YYYY-MM-DD format.
Additionally the variabe $we is 1 if it is weekend (i.e $wday == 0 or $wday == 6), and 0 otherwise. If the holida2we global attribute is set, $we is 1 for holidays too.

define n2 notify piri:on { if($hour > 18 || $hour < 5) { fhem "set light on" } }
define roll_en *07:45:00 { fhem "trigger SwitchAllRoll on" if(!$we) }
define roll_en *08:30:00 { fhem "trigger SwitchAllRoll on" if($we) }

$we is equivalent to calling IsWe(), which optionally takes the arguments "today", "yesterday", "tomorrow", MM-DD or YYYY-MM-DD. Note: for everything else the state reading is evaluated, and no error message is issued.

All helper functions defined in 99_Utils.pm

To access the device states/attributes, use the following functions:

• Value(<devicename>)
  Returns the STATE of the device (the string you see in parenthesis in the output of the list command). Note: STATE is meant for display purposes, and can be customized by the user via the stateFormat attribute. Use ReadingsVal(<devicename>, 'state', '') instead for computational purposes.


• OldValue(<devicename>)
• OldTimestamp(<devicename>)
  Returns the old value/timestamp of the device.


• ReadingsVal(<devicename>,<reading>,<defaultvalue>)
  Returns the reading (the value in the Readings section of "list device")


• ReadingsNum(<devicename>,<reading>, <defaultvalue>,<round>)
  Returns the first number from a reading value. Round it to <round> decimal places (optional parameter). If <round> exeeds the length of the factional part, 0's will be padded.


• ReadingsTimestamp(<devicename>,<reading>,< defaultvalue>)
  Returns the timestamp of a reading.


• ReadingsAge(<devicename>,<reading>,<defaultvalue>)
  Returns the age of a reading in seconds.


• OldReadingsVal(<devicename>,<reading>, <defaultvalue>)
  OldReadingsNum(<devicename>,<reading>, <defaultvalue>,<round>)
  OldReadingsTimestamp(<devicename>,< reading>,<defaultvalue>)
  OldReadingsAge(<devicename>,<reading>, <defaultvalue>)
  similar to the above functions, but used to access the previous values. see: oldreadings


• AttrVal(<devicename>,<attribute>,<defaultvalue>)
  Returns the attribute of a device
  
  { Value("wz") }
  { OldValue("wz") }
  { time_str2num(OldTimestamp("wz")) }
  { ReadingsVal("wz", "measured-temp", "20")+0 }
  { ReadingsTimestamp("wz", "measured-temp", 0)}
  { AttrVal("wz", "room", "none") }
  


• AttrNum(<devicename>,<attribute>, <defaultvalue>,<round>)
  Return the first number from an attribute value. Round id to <round> devimal places (optional parameter).


• InternalVal(<devicename>,<property>,<defaultvalue>)
  Return the internal value (the value in the Internals section of "list device").


• InternalNum(<devicename>,<property>, <defaultvalue>,<round>)
  Return the first number from an internal value. Round it to <round> decimal places (optional parameter). If <round> exeeds the length of the factional part, 0's will be padded.

By using the 99_SUNRISE_EL.pm module, you have access to the following functions:

sunset($offset, $min, $max)
sunrise($offset, $min, $max)
isday()

offset is in seconds, and the format of min/max is "HH:MM" or "HH:MM:SS". isday returns 1 if the sun is visible, and 0 else.

Regexp

[EN DE]

FHEM makes heavy use of regexp, which is short for regular expressions. Other shorthands are regex or re.
With a regexp you can check if a text/string contains the substrings what you are looking for, or extract parts of this string for later usage.
Regexp is not to be confused with glob, which is used in the shell: .* is the regexp equivalent of the glob *
Some examples:

Regexp	Explanation
.	Matches one arbitrary character.
x	Matches a string containing x: x, xy, but not abc
^x	Matches a string starting with x: x, xy, but not yx
x$	Matches a string ending with x: x, yx, but not xy
^x?$	Matches zero or one x: "", x, but not xx
^x*$	Matches zero or more x: "", x, xxxx, but not xy or yx
^x+$	Matches one or more x: x, xxxx, but not ""
^(xy|yx)$	Matches xy or yx
*	Not a valid regexp! This is a glob

There is a lot more to know about regexps. There is an extensive documentation coming with your perl installation: try in the OS commandline perldoc perlretut first, and perldoc perlre for details.
If unsure, test your regexp in an online regexp tester, like regex101.com, regexr.com or regextester.com .
You can also test your regexp in the FHEM commandline:

{ "StringToTest" =~ m/^Str/ }
{ "StringToTest" =~ m/^str$/ }
{ "StringToTest" =~ m/(To|From)/ }

gnuplot file syntax

[EN DE]

The .gplot files are also used by the FHEMWEB/SVG module when the plotmode attribute is set to SVG. In this case only a subset of the .gnuplot attributes are used, and some lines have special meanings: the difference will be explained in this chapter. See also this FHEM Wiki entry on creating logs.
Following is a minimal .gplot definition (valid only for plotmode SVG):

  set terminal size <SIZE>
  #FileLog 4:::
  plot title 'Temperature' with lines

The .gnuplot file consists of 3 parts:

• set commands
  Following sets are recognized:
  • terminal, only the size parameter.
    This is usually set to <SIZE>, which is replaced by the plotsize attribute of the FHEMWEB or weblink instance.
  • title
    Usually set to <TL> which is replace by the weblink title attribute, or to <Lx>, which is replaced by the weblink label attribute.
  • ylabel,y2label
    Left and right labels, printed vertically. Are also subject to label replacement.
  • yrange,y2range
    Specify the range of the left and right axis. Examples:
    
    set yrange [-0.1:1.1]
    set y2range [0:]
    
  • ytics,y2tics
    the label for the left/right axis tics. Examples:
    
    set ytics ("on" 0, "off" 1)
    set y2tics
    


• #FileLog entries
  Each line from the plot section must have one corresponding #FileLog line. For the syntax see the column_spec paragraph of the Filelog get description. Note that for SVG plots the first column of the input file always has to be in the standard fhem timestamp format (YYYY-MM-DD_HH:MM:SS)


• plot entries
  There is always one plot command with comma separated argument-blocks. Each argument-block represents one line, and has its own parameters. Following parameters are recognized:
  • axes x1y1 / x1y2
    tells the program to assign the current line to one of the two axes (left or right).
  • title
    Caption of the line. Whan clicking on this title, a small javascript program will change the title to the min/max and last values of the plot, will enable copying this line or pasting an already copied one (the existing scale of the plot wont'be changed, only the pasted line will be scaled), and other lines of the plot will temporarily be hidden.
  • with <linetype>
    Specify the line type. Following types are recognized: points, steps, fsteps, histeps and lines. Everything unknown will be mapped to the type lines. SVG special: cubic and quadratic, are mapped to the SVG path types C, and Q respectively.
  • ls <linestyle>
    The linestyle defaults to l0 for the first line, l1 for the second, and so on. It is defined in the svg_style.css file. There are two sets defined here: l0-l8 and l0fill-l6fill. The second set must be specified explicitly. If the name of the linestyle contains the word fill, then plots of the lineytype "lines" will have an additional starting and ending segment, so that filling is done correctly.
    See the SVG spec for details of this CSS file. Note: if you plan to use this attribute, you have to specify it for all the lines (attribute-blocks) in the plot command.
  • lw <linewidth>
    Sets the stroke-width style of the line. This attribute is deprecated, the corresponding feature of the CSS file / (attribute ls) should be used instead.