This help was automatically exported from the bot and not specially crafted for viewing in a web browser.

1. General topics

1.1. DURATION

DURATION is a parameter which may be optional or mandatory in some messages to the bot.

It consists of a number followed by one of the characters s, m, h, d, or w, marking seconds, minutes, hours, days or weeks.

1.2. MUC

To use me in a MUC (a multi-user-chat in XMPP/Jabber) you have to directly address me, which means prefixing the message with my nickname (NICKNAME ' or 'NICKNAME:). Afterwards the user who has done this does not need to repeat it for a certain time. In case I wrongly feel addressed, tell me be quiet, stop, or shut up.

1.3. REGEX

REGEX denotes a regular expression, syntax explained at https://docs.python.org/3/library/re.html

Instead of a REGEX you can define an explicit name of a value, too.

A search using a REGEX is case insensitive by default, but you can customize it using one of

uSet user_u_SearchCaseSensitive 1!
uSet user_u_SearchCaseSensitive 0!

In some places I guess whether your input is meant to be a REGEX or an explicit name. You can prepend it with re: to enforce interpretation as REGEX.

1.4. TIMESPAN

TIMESPAN denotes one of three different methods to define a timespan using start and end time:

  1. DURATION starts DURATION ago and ends at current time.

  2. DATETIME+DURATION starts at DATETIME and lasts DURATION.

  3. DATETIME-DATETIME starts at the first time defined and extends to the second one.

help duration explains DURATION

DATETIME is [[[CC]YY]MMDD]hhmm, which means that hour and minute have to be defined, while day, month, year, and century are optional.

1.5. bot

This bot is a public example implementation of http://www.jwwulf.de/en/progelec/pymsgbot_base/

In addition to base features it receives some data via mqtt which you can view, monitor (using included rules), download, and plot. The data currently available to everyone is enviromental data from Karlsruhe, Germany.

From outside of my home:

K3Lueft_T_0     Temperature, °C
K3Lueft_T_TP_0  Dew point, °C. Value is too high usually
K3Lueft_RH_0    Relative humidity, percent. Value is too high usually
K3Lueft_u12_3   Rain sensor. <1950 means it is wet
Logger_P_PV     Current power of solar electric cells
Mome1_T_LUBW           Temperature
Mome1_T_LUBW_TP        Dew point
Mome1_RH_LUBW          Relative humidity
Mome1_RegenSum_LUBW    Rain

1.6. command

Send list c to see command scripts available to you.

Usually a command script changes a state of the bot or something else.

The message used to execute a command script has to end with an exclamation mark.

To get help for a command script named NAME, send help !NAME, for example help !vSub.

1.7. dialog

Some questions and commands start a simple dialog with you in case you didn’t call them with every parameter they expect.

Some commands do just this to ease instantiating rules (see help rule).

1.8. language

You can change mit language by sending something like

uSet user_str_Language de!

1.9. macro

You can define macros by first sending messages you want to include in a macro followed by mSave! which will guide you through the process of creating a macro.

Macros can have arguments.

Use ?mList to list/show macros and !mDel to delete them.

Attention: macros may shadow questions and commands.

1.10. messages

The following user variables control information added to messages send to you by the bot, their default value is 0 (off).

uSet user_u_MsgAddTXCnt 1!

adds a counter (0..9).

uSet user_u_MsgAddTime 1!

adds the time the message was sent (only if at least one minute elapsed since the previous message).

This information is appended to the message unless you set

uSet user_u_MsgAddInFrontOf 1!

which inserts it at the start of messages.

1.11. question

Send list q to see question scripts available to you.

In contrast to a command script, a question script usually does not change any state. It only generates an answer being send to you.

Messages calling a question script do not end with a question mark.

To get help for a question script named NAME, send help ?NAME, for example help ?list.

1.12. rule

Rules are more powerful than question and command scripts. They can execute code because of a time condition or when (certain) values are changed.

Send rList a to see classes of rules available to you and rList r to see rules you already started.

Send .CLASSNAME to list all active rules of that class.

Most rules can be instantiated more than once, but every instance needs a unique name. A rule of class CLASSNAME named RULENAME is instantiated using

.CLASSNAME.RULENAME !

Some classes may need parameters on creation, see their help (help .CLASSNAME).

A rule can be deleted using

.CLASSNAME.RULENAME.delete!

or

..RULENAME.delete!

Notice how CLASSNAME is optional in case of a certain instance of a rule.

RULENAME is case sensitive.

Rules may have parameters which can be changed after instantiation.

.CLASSNAME.RULENAME

or

..RULENAME

show those parameters and callable methods of a rule.

Parameters can be changed using

rSet ..RULENAME.PARAMETERNAME VALUE !

or

rSet!

see help !rSet.

A rule’s parameters are not values (see help value).

There are command scripts having the same name as a rule class. They are intended to ease instantiation by using interactive questions and answers.

1.13. settings

You can list your current user settings using vList user_

uSet user_str_Emphasize *! emphasizes some of my output using *; you can turn it off by sending uSet user_str_Emphasize !

help user_ might explain more user settings.

1.14. totp

To secure against unintended or unauthorized changes, you can enable a kind of write protection which comes into play when executing command scripts or instantiating rules.

Do so by sending

uSet user_str_TOTPSecret SECRET force!

SECRET must be base32 encoded (groups of eight characters A-Z and 2-7). I’ll ask you for a passcode derived (TOTP, 6 digits, SHA1, interval 30 seconds) from this SECRET when needed.

In case my admin created a rule of class TOTP_decAllowedTics, asking a passcode is supressed for a certain time after you gave me a valid code. Without this rule, I will not ask until you execute userTOTPExpire.

The protection can be turned off again by sending uSet user_str_TOTPSecret 0 force SECRET!

An app like FreeOTP+ (https://f-droid.org/de/packages/org.liberty.android.freeotpplus/) can be used to generate passcodes.

1.15. value

This bot is able to handle time series data. Every value has a name, a current value and a list of previous values including their timestamp.

You can list currently known values by sending vList, see help ?vList.

There are more questions and commands regarding values which can listed by list v.+.

There are values which store user settings; their names start with user_. They do not store a history of previous values and differ in some more aspects, but can be listed using vList user_.

In case you often list current values and have no problems using this bot, setting vList (instead of help) to be your default question may suit you:

uSet user_str_DefaultQuestion vList!

This setting enables you to send .+ or user_ instead of vList .+ or vList user_, for example.

2. scr_question

2.1. ?adminHelp

Show infos for the bot’s admin

2.2. ?adminHelpExport

Export all help to a file

2.3. ?adminTestPlotLimits

Vorsicht, die Ausführung ist aufwendig und dauert lange! Erzeugt viele Plots mit verschiedenen Einstellungen um Grenzen zu bestimmen. Um alle Tests auszuführen, muss es mit dem Parameter -1 aufgerufen werden.

2.4. ?extRead

Print content of extension file

Examples:

extRead .vSub
extRead ?help
extRead !vSet

You can optionally pass the files' encoding as second parameter.

2.5. ?help

Helps using this bot

2.6. ?hilfe

Helps using this bot

2.7. ?list

Lists scripts

list [q] [c] [REGEX]

Optionally only list *q*uestion or *c*ommand scripts, or scripts, whose name matches REGEX. Examples:

list
list q
list c
list q v.+
list c .Set

2.8. ?mList

List macros

mList [REGEX]

List macros (whose names match REGEX)

2.9. ?pLuft

Plotten mancher Aussenmesswerte, Zeit als Argument.

2.10. ?ptp

Zeigt Taupunktverlauf, Zeit als Argument.

2.11. ?rList

List rules

rList [r] [a] [REGEX]

Optionally only list *a*vailable or *r*unning rules. Optionally add a REGEX. Examples:

rList
rList r
rList a
rList a timer.+

2.12. ?userInfo

Show info about users

Without an argument, the current user is shown. If the argument is not a user, the list of users is printed.

2.13. ?userTOTPExpire

Ends temporary write permission

See help totp. This has to be a question script although it changes a state.

2.14. ?vDatafile

Send time series data as text files

Syntax and meaning of parameters is identical to vPlot, see help ?vPlot

2.15. ?vExplore

Explore available devices and values

vExplore devices [REGEX]

Show devices whose name matches REGEX

vExplore values [REGEX [REGEX]]

Show values of devices whose name matches the first REGEX. The second REGEX limits values to be listed.

Devices and values are listed separately. Each value is listed together with the number of devices which implement it.

2.16. ?vInfo

Print detailed information about values

vInfo REGEX

2.17. ?vList

List values

vList [REGEX]

List current value of one or more values defined by REGEX

2.18. ?vMax

Print maximum value recorded during a defined time span

vMax TIMESPAN REGEX

2.19. ?vMin

Print minimum value recorded during a defined time span

vMin TIMESPAN REGEX

2.20. ?vPlot

Draw a plot of time series data

vPlot [zip] [to TARGET] TIMESPAN REGEX […] [ ; REGEX […] ]

zip causes plots to be delivered in a zip archive.

TIMESPAN see help timespan

Several values can be shown in one plot. A semicolon starts a new plot.

Apart from plotting raw data (REGEX) one of several functions can be applied to the data (they can not be nested):

none(REGEX) enforce raw data
stairauto(REGEX) automatic stair type plotting depending on how many points in time are shown
staircase(REGEX) to enforce stair type plotting
diffinterval(REGEX,DURATION) is not a real differentiation
chgvis(REGEX,LEVEL) plots an unchanged value as LEVEL and a changed value as LEVEL+1

3. scr_cmd

3.1. !adminReload

Reload as much as possible without restarting the bot.

3.2. !echo

Echos what you tell it

echo FOO BAR AND WHATEVER!

3.3. !extWrite

(Over)write or delete an extension file

You have to send a message containing newlines. The file’s content starts from the second line of the message. Example:

extWrite .newRule
first line
second line
last line!

Just like in other places, rules start with ., question scripts with ?, and command scripts with !. See help extRead.

The closing exclamation mark is not part of the file being written but part of the command script’s call.

Don’t forget the following method which returns True as second value to enable overwriting/deleting the file (if that is your intention):

def GetAccessInfo(self):
return (['admin'], True, 1)

The third return value is needed for rules and states the number of instantiations for a user.

Do not provide content to delete a file. Example:

extWrite ?rList!

3.4. !mDel

Delete a macro

mDel MACRONAME!

3.5. !mSave

Interactively create a macro from previous messages

3.6. !mucJoin

Join a MUC

mucJoin bla@conference.host.org nickname!

3.7. !rSet

Set a rule’s property

rSet!

rSet ..RULENAME.PROPERTYNAME VALUE!

rSet .CLASSNAME.RULENAME.PROPERTYNAME VALUE!

3.8. !su

Impersonate another user

su USERNAME !

3.9. !timerDaily

Helps instantiating a timer rule .timerDaily

3.10. !timerPeriod

Helps instantiating a timer rule .timerPeriod

3.11. !uSet

Set a user value

uSet PROPERTYNAME VALUE!

A string can be set to an empty string by omitting the second argument, for example uSet user_str_Emphasize!

3.12. !userAdd

Add a user

For example userAdd xmpp:john@doe.org!. An invitation message is sent to the user.

3.13. !userDel

Delete a user

For example userDel xmpp:john@doe.org!

3.14. !userPermission

Edit a user’s permissions

First argument: username

Second argument: permission changes. - removes all permissions, + grants all permissions of the calling user. Multiple changes can be performed in one call.

Example: userPermission xmpp:user@host -,+vSet,+extRead!

+admin allows everything.

3.15. !vComp

Helps instantiating a comparator

See help .vComp

3.16. !vDelete

Delete a value

vDelete REGEX !

3.17. !vSet

Set a value.

Set a value using

vSet VALUENAME VALUE!

3.18. !vSub

Helps instantiating/changing a subscription

vSub REGEX [CONDITION] [GRACETIME] as RULENAME

This command helps instantiating a subscription rule .vSub.RULENAME when called without arguments. It changes settings of an existing rule otherwise.

See help .vSub

4. rules

4.1. .TOTP_decAllowedTics

Periodic timer tic for TOTP token expiry

This is needed in context of help totp. Calls GD.TOTP_decAllowedTics() every ten seconds, which makes a temporary write permission expire after 10 seconds multiplied by nInitAfterTOTP (taken from the config file, section writeenable).

4.2. .adminSaveHistory

Saves value history periodically

Instantiate without arguments or with a list of times: .adminSaveHistory.RULENAME 1:30,7:30,13:30,19:30!

Calling ..RULENAME.save! saves data at once.

4.3. .adminSaveUsers

Saves user data periodically

Instantiate without arguments or with a list of times: .adminSaveUsers.RULENAME 1:30,7:30,13:30,19:30!

Calling ..RULENAME.save! saves data at once.

4.4. .ping

Periodically sends a message

Optional argument on instantiation for time between messages. The message can not be configured. See help .timerPeriod if you need more.

4.5. .sendPresence

Send a message when XMPP presence changes

4.6. .timerDaily

Execute a command at a given time, optionally repeat

First argument: time of day as hh:mm

Second argument: number of times to execute this timer (-1 means infinitely)

Remaining arguments: the command to be executed

All properties can be changed afterwards. Example:

.timerDaily.test 13:12 1 echo This is a test.!
..test.set 12:13!
rSet ..test.nDays 31!

The property nDays is a sum of 1,2,4,8,16,32,64 for monday, tuesday, …, sunday. So 1+2+4+8+16=31 means monday to friday, 32+64=96 stands for saturday and sunday.

See help .timerPeriod for how to test or change the command and how to execute multiple commands.

timerDaily! provides interactive help to create a rule of this class.

4.7. .timerPeriod

Delayed execution of a command, optional repetition

First argument: time until execution

Second argument: number of times to execute this timer (-1 means infinitely)

Remaining arguments: the command to be executed

All properties can be changed afterwards. A modified time becomes effective after an execution or after ..RULENAME.reset!, which resets the timer.

The command can be set using

rSet ..RULENAME.strCmd NEW_CMD!

More than one command can be scheduled by sending a multiline message. Example:

rSet ..RULENAME.strCmd
echo Hello World!
vList!

or

rSet ..RULENAME.strCmd
vList
echo Hello World!!

The closing exclamation mark ends rSet.

You can test command execution by sending ..RULENAME.testcmd!.

Another example: delayed plot after crossing a threshold:

.vComp.ShowWarmDelayed K3Lueft_T_0 20 3!
rset ..ShowWarmDelayed.strCmd .timerPeriod.DelayedPlot 30m 1 vPlot 3h K3Lueft_T_0!!

timerPeriod! provides interactive help to create a rule of this class.

4.8. .vComp

Action when a value crosses a threshold

There is no help describing the rule yet, but there is a helper command vComp!.

Setting/testing a command to execute: see help .timerPeriod

..RULENAME.vList lists monitored values

vComp! provides interactive help to create a rule of this class.

4.9. .vSub

Action when a value changes

Instantiation with .vSub.RULENAME REGEX [CONDITION] [GRACETIME] !

This rule monitors one or more values (defined using REGEX) and sends a message if their change matches CONDITION. A change within GRACETIME after a message will not trigger an action.

If CONDITION is not given, it defaults to .:

  .       Every change.
  =       Everytime the value is set, even if unchanged.
  <VALUE  New value is smaller than VALUE
  >VALUE  New value is greater than VALUE
  <<VALUE New value is smaller than VALUE, previous was greater
  >>VALUE New value is greater than VALUE, previous was smaller

GRACETIME: see help duration

Setting/testing a command to execute: see help .timerPeriod

..RULENAME.vList lists monitored values

If ..RULENAME.liststrOnlySendWhenPresence is not empty, action will only be taken in case of this XMPP presence, for example: rSet ..RULENAME.liststrOnlySendWhenPresence available,away!

Temporarily mute the rule using rSet ..RULENAME.nMuted 1!

vSub! provides interactive help to create a rule of this class.


Latest modification: 18.09.2021 13:10
Jens W. Wulf

Impressum
Datenschutzerklärung