All help texts

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.

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.

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

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.

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

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.

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:

From https://www.karlsruhe.de/b3/wetter:

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.

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).

You can change mit language by sending something like

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.

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

adds a counter (0..9).

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

which inserts it at the start of messages.

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.

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

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

A rule can be deleted using

or

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.

or

show those parameters and callable methods of a rule.

Parameters can be changed using

or

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.

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.

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

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.

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:

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

Show infos for the bot’s admin

Export all help to a file

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.

Print content of extension file

Examples:

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

Helps using this bot

Helps using this bot

Lists scripts

list [q] [c] [REGEX]

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

List macros

mList [REGEX]

List macros (whose names match REGEX)

Plotten mancher Aussenmesswerte, Zeit als Argument.

Zeigt Taupunktverlauf, Zeit als Argument.

List rules

rList [r] [a] [REGEX]

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

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.

Ends temporary write permission

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

Send time series data as text files

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

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.

Print detailed information about values

vInfo REGEX

List values

vList [REGEX]

List current value of one or more values defined by REGEX

Print maximum value recorded during a defined time span

vMax TIMESPAN REGEX

Print minimum value recorded during a defined time span

vMin TIMESPAN REGEX

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):

Reload as much as possible without restarting the bot.

Echos what you tell it

echo FOO BAR AND WHATEVER!

(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:

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):

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:

Delete a macro

mDel MACRONAME!

Interactively create a macro from previous messages

Join a MUC

mucJoin bla@conference.host.org nickname!

Set a rule’s property

rSet!

rSet ..RULENAME.PROPERTYNAME VALUE!

rSet .CLASSNAME.RULENAME.PROPERTYNAME VALUE!

Impersonate another user

su USERNAME !

Helps instantiating a timer rule .timerDaily

Helps instantiating a timer rule .timerPeriod

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!

Add a user

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

Delete a user

For example userDel xmpp:john@doe.org!

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.

Helps instantiating a comparator

See help .vComp

Delete a value

vDelete REGEX !

Set a value.

Set a value using

vSet VALUENAME VALUE!

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

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).

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.

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.

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.

Send a message when XMPP presence changes

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:

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.

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:

or

The closing exclamation mark ends rSet.

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

Another example: delayed plot after crossing a threshold:

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

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.

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 .:

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.