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:
-
DURATION starts DURATION ago and ends at current time.
-
DATETIME+DURATION starts at DATETIME and lasts DURATION.
-
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.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.